CONTENTS

• BitSet
• Date
• Dictionary
• Enumeration
• Hashtable
• Observable
• Observer
• Properties
• Random
• Stack
• StringTokenizer
• Vector
• EmptyStackException
• NoSuchElementException

In this chapter you learn about the util package. This package provides some of the most useful Java classes that you will come to rely on. It introduces ten classes, two exception classes, and two interfaces, as shown in Table 34.1. Figure 34.1 provides a graphical representation of the hierarchy of these contents.

Figure 34.1: Contents of package java.util

The BitSet class is useful for storing and manipulating arbitrarily long sets of bits. The Date class can be used to represent dates and times and provides methods for converting dates to and from Strings. The abstract class Dictionary is a superclass of Hashtable. The Hashtable class can be used for creating an array of keys and values and allowing elements to be looked up by either key or value. The Properties class extends Hashtable in a couple of significant ways, most notably by allowing elements to be streamed into or out of the class. The Observable class can be extended and allows you to create new classes that notify other classes when they change. The Random class is a pseudo-random number generator that can return integer, floating-point or Gaussian-distributed values. The Stack class is an extension of Vector and supplies a last-in, first-out data structure. The Vector class can be used for storing any objects and can store objects of more than one type in the same vector. The StringTokenizer class provides a very flexible mechanism for parsing Strings.

In addition to these classes the util package also includes two interfaces: Enumeration and Observer. The Enumeration interface provides two methods that allow for easy traversal through a set of items. The Observer interface can be implemented by any class that needs to observe a subclass of Observable.

BitSet

Object

The class java.util.BitSet is derived directly from Object but also implements the Cloneable interface, as shown in Listing 34.1.

Listing 34.1. The BitSet class.

public class BitSet extends Object implements Cloneable {
  // public constructors
     public BitSet();
     public BitSet(int nbits);
  // public instance methods
     public void and(BitSet set);
     public void clear(int bit);
     public Object clone();
     public boolean equals(Object obj);
     public boolean get(int bit);
     public int hashCode();
     public void or(BitSet set);
     public void set(int bit);
     public int size();
     public String toString();
     public void xor(BitSet set);
}

This class represents a dynamically sized set of bits. Two constructors are provided: one that creates an empty set of unspecified size and one that creates a set of a specified size. The set method can be used to set an individual bit or clear can be used to clear an individual bit. The first bit in a BitSet is the zero bit so that myBitset.set(0) is a valid statement.

The logical functions and, or, and xor are all supported and will combine the BitSet with another set. BitSets can be compared for equality using equals and can be converted to strings using toString. For the purpose of converting a BitSet to a String, a set bit is represented by the value 1 and a clear bit is represented by 0.

public BitSet()

This constructor creates an empty bit set.

public BitSet(int nbits)

This constructor creates an empty bit set with the specified number of bits.

nbits is the number of bits in the set.

public void and(BitSet set)

This method logically ANDs the BitSet with another BitSet. For example, the following code results in only bit 4 being set in bits1:

BitSet bits1 = new BitSet(10);
bits1.set(1);
bits1.set(4);

BitSet bits2 = new BitSet(10);
bits2.set(4);
bits2.set(5);
bits1.and(bits2);

set is the bit set to AND with the current set.

public void clear(int bit)

Clears the specified bit.

bit is the bit to clear.

public Object clone()

This method overrides the clone method in Object. It can be used to clone the bit set. For example, the following code creates a duplicate copy of bits in clonedBits:

BitSet bits = new BitSet(10);
bits.set(0);
bits.set(1);
bits.set(5);
BitSet clonedBits = (BitSet)bits.clone();

public boolean equals(Object obj)

This method can be used to compare the contents of two BitSets. If the same bits are set in the two BitSets, they are considered equal. Consider the following code sample:

BitSet bits1 = new BitSet(10);
bits1.set(0);
bits1.set(1);
bits1.set(4);

BitSet bits2 = new BitSet(10);
bits2.set(0);
bits2.set(1);
bits2.set(4);

BitSet bits3 = new BitSet(10);
bits3.set(0);
bits3.set(1);
bits3.set(5);

Graphics g = getGraphics();
if (bits1.equals(bits2))
    g.drawString("bits1 equals! bits2", 15, 15);
if (bits1.equals(bits3))
    g.drawString("bits1 equals! bits3", 15, 30);

In this case, bits1 will equal bits2 because the same bits are set; however, bits1 will not equal bits3.

obj is a bit set to compare against.

public boolean get(int bit)

Gets the value of a specified bit in the set.

bit is the bit to get.

public int hashCode()

This method overrides the hashCode method in Object and can be used to get a hash code for the instance.

A hash code for the instance.

public void or(BitSet set)

This method logically ORs the BitSet with another. For example, the following code results in bits 1, 4, and 5 being set in bits1:

BitSet bits1 = new BitSet(10);
bits1.set(1);

bits1.set(4);

BitSet bits2 = new BitSet(10);
bits2.set(4);

bits2.set(5);

bits1.or(bits2);

set is the bit set to OR with the current set.

public void set(int bit)

Sets the specified bit.

bit is the bit to set.

public int size()

This method returns the amount of space, in bits, used to store the set. Space for a bit set is allocated in 64-bit increments, so the following example will indicate that len1 equals 64 and len2 equals 128:

BitSet bits1 = new BitSet();
bits1.set(0);
bits1.set(1);
bits1.set(4);

BitSet bits2 = new BitSet(65);
bits2.set(0);
bits2.set(1);
bits2.set(5);

int len1 = bits1.size();       // will equal 64
int len2 = bits2.size();       // will equal 128

The amount of space, in bits, used to store the bit set.

public String toString()

This method formats the BitSet as a String. The String will consist of an opening curly brace, comma-separated values representing each set bit, and a closing curly brace. For example, the following code places {0, 1, 4} in the variable str:

BitSet bits1 = new BitSet();
bits1.set(0);
bits1.set(1);
bits1.set(4);
String str = bits1.toString();

A string representing the bits in the bit set that are set.

public void xor(BitSet set)

This method logically XORs the BitSet with another BitSet. For example, the following code results in bits 4 and 5 being set in bits1:

BitSet bits1 = new BitSet(10);
bits1.set(0);
bits1.set(1);
bits1.set(4);

BitSet bits2 = new BitSet(10);
bits2.set(0);
bits2.set(1);
bits2.set(5);

bits1.xor(bits2);

set is the bit set to XOR with the current set.

Date

Object

The class java.util.Date extends Object. The Date class stores a representation of a date and time and provides methods for manipulating the date and time components. A new Date instance may be constructed using any of the following:

• The current date and time as expressed in the UNIX-standard milliseconds since midnight January 1, 1970;
• A String;
• Integers representing the year, month, day, hours, minutes, and seconds.

Dates can be compared with the before, after, and equals methods. Methods are also provided for converting a date into various formatted Strings. The non-private interface of the Date class is shown in Listing 34.2.

Listing 34.2. The Date class.

public class Date extends Object {
  // public constructors
     public Date();
     public Date(long date);
     public Date (int year, int month, int date);
     public Date (int year, int month, int date,int hrs,int min);
     public Date (int year, int month, int date, int hrs,
             int min, int sec);
     public Date (String s);
  // static methods
     public static long UTC(int year, int month, int date, 
             int hrs, int min, int sec);
     public static long parse(String s);
  // public instance methods
     public int getYear();
     public void setYear(int year);
     public int getMonth();
     public void setMonth(int month);
     public int getDate();
     public void setDate(int date);
     public int getDay();
     public int getHours();
     public void setHours(int hours);
     public int getMinutes();
     public void setMinutes(int minutes);
     public int getSeconds();
     public void setSeconds(int seconds);
     public long getTime();
     public void setTime(long time);
     public boolean before(Date when);
     public boolean after(Date when);
     public boolean equals(Object obj);
     public int hashCode();
     public native String toString();
     public native String toLocaleString();
     public native String toGMTString();
     public int getTimezoneOffset();
}

public Date()

This method creates a new Date object using today's date. For example, to display today's date you could write the following:

Date today = new Date();
Graphics g = getGraphics();
g.drawString("Today is " + today, 15, 15);

public Date(long date)

This method creates a Date from a long that represents the number of milliseconds since January 1, 1970.

date is the number of milliseconds since January 1, 1970.

public Date(int year, int month, int date)

This method creates a new Date object that corresponds to the year, month, and day passed to it. The first month of the year is month zero. The day of the month is normalized so that impossible dates become real dates. For example, you'd think badDate in the following code would be equal to November 33, 1996.

Date goodDate = new Date(95, 10, 14);   // November 14, 1995    
Date badDate = new Date(96, 10, 33);    // December 3, 1996

However, badDate is adjusted to be December 3, 1996 instead. The value in goodDate will correctly be November 14, 1995.

year is the number of years since 1900.

public Date(int year, int month, int date, int hrs, int min)

This method creates a new Date object that corresponds to the year, month, day, hours, and minutes passed to it. As with the prior constructor, the day of the month is normalized so that impossible dates become real dates. For example, to create a variable named birthday that holds November 14, 1995 at 1:16 PM (13:16 in military time), you would use the following:

Date birthday = new Date(95, 10, 14, 13, 16);

year is the number of years since 1900.

public Date(int year, int month, int date, int hrs, int min, int sec)

This method creates a new Date object that corresponds to the year, month, day, hour, minute, and seconds passed to it. As with the other constructors, the day of the month is normalized so that impossible dates become real dates.

year is the number of years since 1900.

public Date(String s)

This method creates a new date based on the date string passed to it. For example, to create a variable that represents August 31, 1996, you could use the following:

Date aDate = new Date("August 31 1996");

s is a time string in the format passed to java.util.Date.Parse, as described later in this chapter.

public static long UTC(int year, int month, int date, int hrs, int min, int sec)

This method calculates the time in UTC (Coordinated Universal Time) format based on the specified parameters. Parameters are expected to be given in UTC values, not the time in the local time zone.

year is the number of years since 1900.

public static long parse(String s)

This method calculates the time in UTC format based on the string passed to it.

s is a formatted time string such as "Mon, 8 Apr 1996 21:32:PM PST". To specify the time zone, you can use any of the continental United States time zone abbreviations (est, edt, cst, cdt, mst, mdt, pst, pdt) or you can use "GMT" with an offset, such as the following:

Mon, 8 Apr 1996 21:32:PM GMT+0800

This calculates GMT plus eight hours. This method considers GMT and UTC to be equivalent and does not make adjustments for the periodic "leap seconds."

public boolean after(Date when)

Determines whether the Date occurs after the specified date. For example, to determine if the United States Independence Day (July 4) is after the French Bastille Day (July 14), use the following code:

Date independenceDay = new Date(96, 6, 4);
Date bastilleDay = new Date(96, 6, 14);

Graphics g = getGraphics();
if (independenceDay.after(bastilleDay))
    g.drawString("Independence Day is after Bastille Day",15,15);
else
    g.drawString("Independence Day is before Bastille Day",15,15);

when is the date to compare against.

public boolean before(Date when)

Determines whether the date occurs before the specified date.

when is the date to compare against.

public boolean equals(Object obj)

This method determines whether two date objects are the same by comparing the dates represented by each object. For example, the following code will verify that Independence Day and the Fourth of July are the same date:

Date independenceDay = new Date(96, 6, 4);
Date fourthOfJuly = new Date(96, 6, 4);

Graphics g = getGraphics();
if (independenceDay.equals(fourthOfJuly))
    g.drawString("They're equal", 15, 15);
else
    g.drawString("They're not equal", 15, 15);

obj is the object to compare against.

public int getDate()

This method returns the day (or date) portion of a date object.

public int getDay()

This method returns the day of the week. Sunday is assigned a value of 0.

The day of the week from 0 (Sunday) to 6 (Saturday).

public int getHours()

This method returns the hours.

The hours from 0 to 23.

public int getMinutes()

This method returns the minutes.

The minutes from 0 to 59.

public int getMonth()

This method returns the month.

The month from 0 (January) to 11 (December).

public int getSeconds()

This method returns the seconds.

The seconds from 0 to 59.

public long getTime()

This method returns the number of milliseconds since midnight on January 1, 1970.

The time expressed in elapsed milliseconds.

public int getTimezoneOffset()

This method returns the offset in minutes of the current time zone from the UTC. For example, California is in the Pacific time zone and during Pacific Standard Time the following will display that it is 480 minutes (8 hours) different from UTC:

Date date1 = new Date(96, 11, 14);

Graphics g = getGraphics();
g.drawString("Timezone Offset: " + date1.getTimezoneOffset()
        + " minutes from UTC", 15, 15);

The number of minutes difference between the time zone of the object and UTC.

public int getYear()

This method returns the year after 1900.

The year after 1900.

public int hashCode()

This method overrides the hashCode method in Object and can be used to get a hash code for the instance.

A hash code for the instance.

public void setDate(int date)

This method sets the day of the month portion of a Date object.

date is the day value.

public void setHours(int hours)

This method sets the hours portion of a Date object.

hours is the hours from 0 (midnight) to 23.

public void setMinutes(int minutes)

This method sets the minutes portion of a Date object.

minutes is the minutes from 0 to 59.

public void setMonth(int month)

This method sets the month portion of a Date object.

month is the zero-based month from 0 (January) to 11 (December).

public void setSeconds(int seconds)

This method sets the seconds portion of a Date object.

seconds is the seconds from 0 to 59.

public void setTime(long time)

This method sets the time to the time represented by the number of milliseconds in the time parameter. It is frequently used in conjunction with the getTime method, which returns a number of milliseconds. An example of using setTime in conjunction with getTime is as follows:

Date date1 = new Date(96, 11, 14);
long milliSeconds = date1.getTime();
Date date2 = new Date();
date2.setTime(milliSeconds);

if (date1.equals(date2)) {
    Graphics g = getGraphics();
    g.drawString("Dates are equal", 15, 15);
}

time is the new time in milliseconds since January 1, 1970.

public void setYear(int year)

This method sets the year portion of a date instance. As an example, consider the following code:

Date birthday = new Date(95, 10, 14);
birthday.setYear(100);
int day = birthday.getDay();
switch (birthday.getDay()) {
    case 0: // Sunday
        g.drawString("It will be a Sunday", 15, 15);
        break;
    case 1: // Monday
        g.drawString("It will be a Monday", 15, 15);
        break;
    case 2: // Tuesday
        g.drawString("It will be a Tuesday", 15, 15);
        break;
    case 3: // Wednesday
        g.drawString("It will be a Wednesday", 15, 15);
        break;
    case 4: // Thursday
        g.drawString("It will be a Thursday", 15, 15);
        break;
    case 5: // Friday
        g.drawString("It will be a Friday", 15, 15);
        break;
    case 6: // Saturday
        g.drawString("It will be a Saturday", 15, 15);
        break;
}

This example shows how to plan a birthday party in the year 2000. First, the variable birthday is set to November 14, 1995. Then, setYear is used to change the year to 2000 (1900 + 100). Finally, a switch statement on getDay is used to determine the day of the week.

Year is the year after 1900. For 1996, use 96.

public String toGMTString()

This method creates a string that contains the date and time formatted according to GMT (Greenwich Mean Time) conventions. For example, if run on a machine set to Pacific Standard Time, the following code will display "14 Nov 1995 08:00:00 GMT":

Date date1 = new Date(95, 10, 14);

Graphics g = getGraphics();
if (date1.equals(date1))
    g.drawString("GMT: " + date1.toGMTString(), 15, 15);

A string representing the date in GMT format, such as "14 Nov 1995 08:00:00 GMT".

public String toLocaleString()

This method creates a string that contains the date and time in the format of the current locale. For example, the following code will display "11/14/95 00:00:00":

Date date1 = new Date(95, 10, 14);

Graphics g = getGraphics();
if (date1.equals(date1))
    g.drawString("Locale: " + date1.toLocaleString(), 15, 15);

A string representing the date as formatted for the locale of the instance, such as "11/14/95 00:00:00".

public String toString()

This method creates a string that contains the day of the week, the date, and the time. For example, the following code will display "Tue Nov 14 00:00:00 1995":

Date date1 = new Date(95, 10, 14);

Graphics g = getGraphics();
if (date1.equals(date1))
    g.drawString("String: " + date1.toString(), 15, 15);

A string representing the day of the week, date, and time of the instance, such as "Tue Nov 14 00:00:00 1995".

Dictionary

Object

The abstract class java.util.Dictionary extends Object. The non-private members of Dictionary are shown in Listing 34.3.

Listing 34.3. The Dictionary class.

public class Dictionary extends Object {
  // public constructors
     public Dictionary();
  // public instance methods
     public abstract Enumeration elements();
     public abstract Object get(Object key);
     public abstract boolean isEmpty();
     public abstract Enumeration keys();
     public abstract Object put(Object key, Object value);
     public abstract Object remove(Object key);
     public abstract int size();
}

The Dictionary class is an abstract class. Hashtable is derived directly from Dictionary, and Properties is derived from Hashtable. Although one of these classes will probably meet your needs, you could extend Dictionary in your own new class if necessary.

Each element in a Dictionary consists of a key and value. Elements are added to a Dictionary using put and are retrieved using get. Elements may be deleted with remove. The methods elements and keys each return an enumeration of the values and keys, respectively, stored in the Dictionary.

public Dictionary()

This is a default constructor that will create an empty Dictionary.

public abstract Enumeration elements()

This abstract method returns an Enumeration of all elements in a Dictionary.

An enumeration of each of the elements in the Dictionary. The methods of Enumeration can be used to iterate through the elements.

public abstract Object get(Object key)

This abstract method retrieves an object from a Dictionary based on its key.

key is the key of the object to be retrieved.

public abstract boolean isEmpty()

This abstract method can be used to determine if the Dictionary is empty.

true if the Dictionary is empty; false, if not.

public abstract Enumeration keys()

This abstract method returns an Enumeration of all keys in a Dictionary.

An enumeration of each of the keys in the Dictionary. The methods of Enumeration can be used to iterate through the keys.

public abstract Object put(Object key, Object value)

This abstract method inserts a new element into the Dictionary. To retrieve an element use the get method.

key is the key to be added.

public abstract Object remove(Object key)

This abstract method removes an object from a Dictionary.

key is the key of the element to be removed.

public abstract int size()

This abstract method returns the number of elements in the Dictionary.

The number of items stored in the Dictionary.

Enumeration

The interface java.util.Enumeration defines methods that can be used to iterate through a set of objects. The methods hasMoreElements and nextElement are typically used in a loop that visits each item in the set. For example, the following code will iterate through each item in a Vector calling the method DoSomething for each element:

for (Enumeration e = myVector.elements() ; e.hasMoreElements() ;)
    DoSomething(e.nextElement());

The Enumeration interface is shown in Listing 34.4.

Listing 34.4. The Enumeration interface.

public interface Enumeration {
    // public instance methods
     public abstract boolean hasMoreElements();
     public abstract Object nextElement();

     }

public abstract boolean hasMoreElements()

Can be used to determine if the enumeration has more elements.

true if there are more elements; false, if not.

public abstract Object nextElement()

This method returns the next element in the enumeration. Calling it repeatedly will move through the enumeration.

The next element in the enumeration.

Hashtable

Dictionary

The class java.util.Hashtable extends Dictionary. The non-private members of Hashtable are shown in Listing 34.5.

Listing 34.5. The Hashtable class.

public class Hashtable extends Dictionary {
  // public constructors
     public Hashtable(int initialCapacity, float loadFactor);
     public Hashtable(int initialCapacity);
     public Hashtable();
  // public instance methods
     public synchronized void clear();
     public synchronized Object clone();
     public synchronized boolean contains(Object value);
     public synchronized boolean containsKey(Object key);
     public synchronized Enumeration elements();
     public synchronized Object get(Object key);
     public boolean isEmpty();
     public synchronized Enumeration keys();
     public synchronized Object put(Object key, Object value);
     public synchronized Object remove(Object key);
     public int size();
     public synchronized String toString();
  // protected instance methods
     protected void rehash();
}

A Hashtable is used for mapping keys to values. For example, it could be used to map names to ages, programmers to projects, job titles to salaries, and so on. The Properties class extends Hashtable and adds the ability to read and write a Hashtable to a stream.

Each element in a Hashtable consists of a key and value. Elements are added to a Hashtable using the put method and are retrieved using get. Elements may be deleted from a Hashtable with remove. A Hashtable expands in size as elements are added to it. When creating a new Hashtable, you can specify an initial capacity and a load factor. The Hashtable increases in size whenever adding a new element would move the Hashtable past its threshold. A Hashtable's threshold is its capacity multiplied by its load factor. For example, a Hashtable with a capacity of 100 and a load factor of 0.75 would have a threshold of 75 items.

public Hashtable(int initialCapacity, float loadFactor)

This constructor creates a new instance of a Hashtable with the specified initial capacity and load factor. Although an initial capacity is specified, the Hashtable grows as needed when new items are added. The initial capacity specifies how many elements could be stored in the Hashtable if the load factor is 1.0. The load factor is a number between 0.0 and 1.0 and specifies the percent of the Hashtable that must be full before the size is automatically increased.

initialCapacity is the initial capacity of the Hashtable.

public Hashtable(int initialCapacity)

This constructor creates a new Hashtable with the specified initial capacity and a default load factor of 0.75.

initialCapacity is the initial capacity of the Hashtable.

public Hashtable()

This constructor creates a new Hashtable using default values for the initial capacity and the load factor. A default of 101 is used for the initial capacity, and 0.75 is used for the load factor.

public synchronized void clear()

This method removes all elements from a Hashtable. The following example creates a Hashtable, inserts three items into it, and then removes all of them using clear:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));
ages.clear();

public synchronized Object clone()

This method clones the Hashtable into a new Hashtable. The keys and values themselves are not cloned. The following example results in the creation of two Hashtables, each with the same three elements:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));
Hashtable clonedAges = (Hashtable)ages.clone();

A cloned Hashtable.

public synchronized boolean contains(Object value)

This method searches the Hashtable to determine if a specific value is stored. For example, consider the following example, which searches the ages Hashtable for anyone with an age of 0:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

Graphics g = getGraphics();
if (ages.contains(new Integer(0)))
    g.drawString("Found a baby!", 15, 15);
else
    g.drawString("No babies found!", 15, 15);

value is the value to search for.

public synchronized boolean containsKey(Object key)

This method searches the Hashtable to determine if a specific key occurs. As an example, consider the following code, which searches for the name Savannah:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

Graphics g = getGraphics();
if (ages.containsKey("Savannah"))
    g.drawString("Savannah was found!", 15, 15);
else
    g.drawString("Savannah not found!", 15, 15);

key is the key to search for.

public synchronized Enumeration elements()

This method returns an enumeration of all of the element values in the instance. For example, the following code will display the integers 33, 34, and 0:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

Graphics g = getGraphics();
int count = 0;
for (Enumeration enum = ages.elements() ; enum.hasMoreElements() ;) {
    count++;
    g.drawString("Value = " + (Integer)enum.nextElement(), 15, 15*count);
}

An enumeration of each of the keys in the Hashtable. The methods of Enumeration can be used to iterate through the keys.

public synchronized Object get(Object key)

This function retrieves the object associated with the specified key. For example, the following code puts three objects into a Hashtable and then retrieves Laura's age:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

Integer age = (Integer)ages.get("Laura");

Graphics g = getGraphics();
if (age != null)
    g.drawString("Laura is " + age, 15, 15);

key is the key of the object to be retrieved.

public boolean isEmpty()

This method can be used to determine if the Hashtable is empty.

true if the Hashtable is empty; false, if not.

public synchronized Enumeration keys()

This method returns an enumeration of all of the keys in the instance. For example, the following code will display the names Mike, Laura, and Savannah:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

Graphics g = getGraphics();
int count = 0;
for (Enumeration enum = ages.keys() ; enum.hasMoreElements() ;) {
    count++;
    g.drawString((String)enum.nextElement(), 15, 15*count);
}

An enumeration of each of the keys in the Hashtable. The methods of Enumeration can be used to iterate through the keys.

public synchronized Object put(Object key, Object value)

This method inserts a new element into the Hashtable. To retrieve an element use the get method. The following sample code creates a new Hashtable and then puts three elements into it:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));

key is the key to be added.

protected void rehash()

This method rehashes the Hashtable into a larger Hashtable. It is not normally necessary to call this method directly because it is invoked automatically based on the capacity and load factor of the Hashtable.

public synchronized Object remove(Object key)

This method removes an object from a Hashtable. The following code illustrates how to remove an element:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));
ages.remove("Laura");

key is the key of the element to be removed.

public int size()

This method returns the number of elements in the Hashtable.

The number of items stored in the Hashtable.

public synchronized String toString()

This method overrides the toString method in Object and formats the contents of the Hashtable as a String. For example, the following code will display {Savannah=0, Laura=34, Mike=33}:

Hashtable ages = new Hashtable();
ages.put("Mike", new Integer(33));
ages.put("Laura", new Integer(34));
ages.put("Savannah", new Integer(0));
Graphics g = getGraphics();
g.drawString(ages.toString(), 15, 15);

A String representation of the Hashtable.

Observable

Object

The class java.util.Observable extends Object directly. An Observable class is a class that may be watched or monitored by another class that implements the Observer interface. Associated with an Observable instance is a list of Observers. Whenever the Observable instance changes, it can notify each of its Observers. By using Observable and Observer classes, you can achieve a better partitioning of your code by decreasing the reliance of one class on another.

The non-private members of Observable are shown in Listing 34.6.

Listing 34.6. The Observable class.

public class Observable extends Object {
  // public constructors
     public Observable();
  // public instance methods
     public synchronized void addObserver(Observer o);
     public synchronized int countObservers();
     public synchronized void deleteObserver(Observer o);
     public synchronized void deleteObservers();
     public synchronized boolean hasChanged();
     public void notifyObservers();
     public synchronized void notifyObservers(Object arg);
// protected instance methods
     protected synchronized void clearChanged();
     protected synchronized void setChanged();
}

As an example of how Observable can be used, consider the following declaration of a class that extends Observable:

class Obsable extends Observable {
    private int secretNumber;

    public Obsable(int x) {
        secretNumber = x;
    }
    public void setSecretNumber(int x) {
        secretNumber = x;
        setChanged();
        notifyObservers(new Integer(secretNumber));
    }
}

The Obsable class stores a secret number, and whenever that number changes, all Observers are notified. No Observable class is complete without an Observer, so here is the Test class that extends Applet and implements the Observer interface:

public class Test extends Applet implements Observer {
    Integer secretNumber;

    public void update(Observable o, Object arg) {
        secretNumber = (Integer)arg;
    }

    public boolean mouseDown(Event e, int x, int y)   {
        Obsable obs = new Obsable(12);
        obs.addObserver(this);
        obs.setSecretNumber(23);

        Graphics g = getGraphics();
        g.drawString("Secret Number: " + secretNumber, 15, 35);
        return true;
    }

    public boolean handleEvent(Event event) {
        return super.handleEvent(event);
    }

    public void init() {
        super.init();
        setLayout(null);
        resize(230,190);
    }
}

The Test class contains an update method that is part of the Observer interface. This method is passed an Observable item and an Object as parameters. As shown in the declaration of Obsable, the Object is an Integer. Therefore, update casts the Object into an Integer and stores it in the instance variable secretNumber. The mouseDown method is used to test this code. When a mouse button is pressed, a new Obsable instance is created, the instance of Test is added as an Observer and the setSecretNumber method is called. This method in Obsable causes all Observers to be notified. Because Test is an Observer, its update method is invoked, and the new value for secretNumber (23) is stored. It is then displayed as evidence that update was called.

public Observable()

This is an empty, default constructor.

public synchronized void addObserver(Observer o)

This method adds an Observer to the list of objects that are observing this instance. The observer must implement the Observer interface. Frequently, the Observer parameter passed to this method is the this implicit member variable, as shown in the following:

Obsable obs = new Obsable(12);
obs.addObserver(this);

o is the observer to add.

protected synchronized void clearChanged()

This method clears the internal flag that indicates an Observable instance has changed.

public synchronized int countObservers()

This method counts the number of Observers that are observing the instance.

The number of Observers for the instance.

public synchronized void deleteObserver(Observer o)

This method deletes an Observer from the list of Observers that are monitoring an Observable object. The Observer must have been previously added with addObserver.

o is the observer to delete.

public synchronized void deleteObservers()

This method deletes all Observers of the Observable instance.

public synchronized boolean hasChanged()

This method can be used to query whether an Observable has changed.

true if an observable change has occurred; false, otherwise.

public void notifyObservers()

This method notifies all Observers that a change has occurred in the Observable object. This results in a call to the update method in each Observer.

public synchronized void notifyObservers(Object arg)

This method notifies all Observers that a change has occurred in the Observable object. This results in a call to the update method in each Observer to which arg will be passed.

arg is any object that can be used to convey information to the Observers.

protected synchronized void setChanged()

This method sets an internal flag to indicate that an observable change has occurred within the instance.

Observer

The interface java.util.Observer defines an update method that is invoked by an Observable object whenever the Observable object has changed and wants to notify its Observers. The Observer interface is shown in Listing 34.7.

Listing 34.7. The Observer interface.

public interface Observer {
    // public instance methods
     public abstract void update(Observable o, Object arg);
}

For an example of how to use an Observer with an Observable class, see the discussion of the Observable class earlier in this chapter.

public abstract void update(Observable o, Object arg)

This method is called whenever an Observable instance that is being observed invokes either of its notifyObservers methods.

o-The Observable object that is generating this message.

Properties

Hashtable

The class java.util.Properties extends Hashtable, which extends Dictionary. The non-private members of Properties are shown in Listing 34.8.

Listing 34.8. The Properties class.

public class Properties extends Hashtable {
  // public constructors
     public Properties();
     public Properties(Properties defaults);
  // public instance methods
     public String getProperty(String key);
     public String getProperty(String key, String defaultValue);
     public void list(PrintStream out);
     public synchronized void load(InputStream in);
     public Enumeration propertyNames();
     public synchronized void save(OutputStream out, String header);
  // protected variables
     protected Properties defaults;
}

This class can be used to store keys and associated values. Through its save and load methods, Properties can be written to disk. This makes this class an excellent mechanism for storing configuration information between runs of a program. An example of a Properties file written by the save method is as follows:

#This is a header comment
#Sun Jun 02 15:01:48 1996
prop3=put three
prop2=put two
prop1=put one

Because Properties is a subclass of Hashtable, new key/value pairs are added by using the put method of Hashtable. The following example shows how to create an instance, put three properties into it, save it, and then reload the keys and values into a different instance:

// create a new instance
Properties props1 = new Properties();

// put three properties into it
props1.put("prop1", "put one");
props1.put("prop2", "put two");
props1.put("prop3", "put three");

// retrieve each of the three properties
String prop1 = props1.getProperty("prop1", "one");
String prop2 = props1.getProperty("prop2", "two");
String prop3 = props1.getProperty("prop3");

// save the properties to a file
props1.save(new FileOutputStream("test.ini"), "My header");

// create a new instance and read the file in from the file
Properties props2 = new Properties();
FileInputStream inStr = new FileInputStream("test.ini");
props2.load(inStr);

// retrieve a property from the second instance
String prop = props2.getProperty("prop2", "two");

protected Properties defaults

This member stores the default property values.

public Properties()

This constructor is used to create an empty, new instance of Properties as follows:

Properties myProps = new Properties();

public Properties(Properties defaults)

This constructor creates a new instance of Properties and will establish a set of default properties.

public String getProperty(String key)

This method is used to retrieve a property based on its key. If no matching key is found, the defaults are searched. If no match is found there either, null is returned. It can be used as follows:

String prop1 = myProps.getProperty("prop1");

key is the key of the property to retrieve.

public String getProperty(String key, String defaultValue)

This method is used to retrieve a property based on its key. If no match is found, the defaultValue is returned. It can be used as follows:

String prop1 = myProps.getProperty("prop1", "default");

key is the key of the property to retrieve.

public void list(PrintStream out)

This method lists all of the properties to the specified PrintStream. It is useful mainly while debugging.

out is the PrintStream where the properties are to be printed.

public synchronized void load(InputStream in) throws IOException

This method reads a set of properties from the specified InputStream. Used in conjunction with the save method, Properties can be written to disk at the end of a program run and then reloaded at the start of the next run. The following example illustrates how to load a Properties instance from a file named TEST.INI:

Properties props = new Properties();
FileInputStream inStr = new FileInputStream("test.ini");
props.load(inStr);

in is the InputStream from which the Properties are to be read.

public Enumeration propertyNames()

This method returns an enumeration of all the property names in the instance. For example, the following code displays the names of each of the three properties:

Properties props1 = new Properties();
props1.put("prop1", "put one");
props1.put("prop2", "put two");
props1.put("prop3", "put three");

int count = 0;
Graphics g = getGraphics();
for (Enumeration enum = props1.propertyNames() ; enum.hasMoreElements() ;) {
    count++;
    g.drawString((String)enum.nextElement(), 15, 15*count);
}

An enumeration of each of the property names. The methods of Enumeration can be used to iterate through the property names.

public synchronized void save(OutputStream out, String header)

This method saves the Properties to an OutputStream. Because FileOutputStream is a subclass of OutputStream, this method can be used to write to a file. As an example of writing Properties to a file, consider the following code:

Properties props1 = new Properties();
props1.put("prop1", "put one");
props1.put("prop2", "put two");
props1.put("prop3", "put three");
props1.save(new FileOutputStream("test.ini"), "My header");

This example creates a Properties set with three values and then writes them to a file named TEST.INI. The file is written with the header text My header. In this case, TEST.INI appears as follows:

#My header
#Sun Jun 02 15:01:48 1996
prop3=put three
prop2=put two
prop1=put one

out is the OutputStream to which the Properties are to be written.

Random

Object

The class java.util.Random is derived directly from Object, as shown in Listing 34.9.

Listing. 34.9. The Random class.

public class Random extends Object {
  // public constructors
     public Random();
     public Random(long seed);
  // public instance methods
     public double nextDouble();
     public float nextFloat();
     public synchronized double nextGaussian();
     public int nextInt();
     public long nextLong();
     public synchronized void setSeed(long seed);
}

This class represents a pseudo-random number generator. Two constructors are provided: One takes a seed value as a parameter, and the other takes no parameters and uses the current time as a seed. Values can be retrieved from the generator using the following methods:

nextDouble

nextFloat

nextGaussian

nextInt

nextLong

public random()

This constructor creates a new random number generator that is seeded based on the current time.

public random(long seed)

This constructor creates a new random number generator based on the specified seed value. You should use this constructor rather than random() if a repeatable sequence of pseudo-random numbers is necessary. Even if a repeatable sequence of numbers is not necessary once a program is complete, it can frequently be useful during the debugging stages. A program that uses random numbers can be particularly difficult to debug. Because of this, you may want to consider providing a configuration setting that enables you to force a random number generator to a known seed.

A program can reset the seed of an already created instance by using the member method setSeed.

seed is the seed value.

public double nextDouble()

This method retrieves the next number from the random number generator. The number will be a pseudo-random, uniformly distributed double between 0.0D and 1.0D.

A randomly distributed double between 0.0D and 1.0D.

public float nextFloat()

This method retrieves the next number from the random number generator. The number will be a pseudo-random, uniformly distributed float between 0.0F and 1.0F.

A randomly distributed float between 0.0F and 1.0F.

public synchronized double nextGaussian()

This method retrieves the next value from the pseudo-random number generator. The value will be returned as a Gaussian-distributed double that has a mean of 0 and a standard deviation of 1.

A Gaussian-distributed double.

public int nextInt()

This method retrieves the next number from the random number generator. The number will be a pseudo-random int with a value that is uniformly distributed among all possible int values.

A randomly distributed int.

public long nextLong()

This method retrieves the next number from the random number generator. The number will be a pseudo-random long with a value that is uniformly distributed among all possible long values.

A randomly distributed long.

public synchronized void setSeed(long seed)

This method sets a seed value for the pseudo-random number generator. The seed value is used to determine the values that are generated. By setting a specific seed value, the random number generator can be coerced into generating a specific sequence of values.

seed is the seed value.

Stack

Vector

The class java.util.Stack extends the class java.util.Vector, which is described later in this chapter. This class implements a simple last-in, first-out stack. An item is stored on a stack by "pushing" it onto the stack. An item may subsequently be "popped" off the stack and used. The item popped off a stack will always be the most recently pushed item. The non-private interface of the class is shown in Listing 34.10.

Listing 34.10. The Stack class.

public class Stack extends Vector {
  // public constructors
     public Stack();
  // public instance methods
     public empty();
     public peek();
     public pop();
     public push(Object item);
     public search(Object o);
}

Because Stack extends the Vector class, no size is associated with a Stack instance. The Stack continues to grow in size as new items are pushed onto it. In addition to methods to push and pop items, a peek method is provided for looking at the next item, a search method is provided for scanning the Stack for a specific item, and an empty method is provided for determining whether more items are stored in the Stack.

public Stack()

There is no explicit constructor provided. To create a new Stack, use the default constructor as follows:

Stack myStack = new Stack();

public boolean empty()

This method can be used to determine whether the Stack contains items.

true if the Stack is empty; false, otherwise.

public Object peek()

This method can be used to peek at the top item on the Stack. It is similar to pop but does not remove the item from the Stack.

The item at the top of the Stack.

public Object pop()

This method retrieves the last item added to the Stack. To examine, but not remove, the top item in the Stack use the peek method.

The item at the top of the Stack.

public Object push(Object item)

This method adds a new item to the Stack.

item is the item to push onto the Stack.

public int search(Object o)

This method examines the Stack to see whether the specified object is in the Stack.

o is the object of the search.

StringTokenizer

Object

The class java.util.StringTokenizer extends Object and implements the Enumeration interface. A StringTokenizer can be used to parse a String into its constituent tokens. For example, each word in a sentence could be considered a token. However, the StringTokenizer class goes beyond the parsing of sentences. You can create a fully customized tokenizer by specifying the set of token delimiters when the StringTokenizer is created. For parsing text, the default whitespace delimiters are usually sufficient. However, you could use the set of arithmetic operators (+, *, /, and -) if parsing an expression.

Because StringTokenizer implements the Enumeration interface, it includes the hasMoreElements and nextElement methods. Additionally, the methods hasMoreTokens and nextToken are provided. The hasMoreTokens method is identical to hasMoreElements, except that you may prefer the method name. The same is true of nextToken and nextElement. The non-private interface of the class is shown in Listing 34.11.

Listing 34.11. The StringTokenizer class.

public class StringTokenizer extends Object implements Enumeration {
  // public constructors
     public StringTokenizer(String str, String delim, boolean returnTokens);
     public StringTokenizer(String str, String delim);
     public StringTokenizer(String str);
  // public instance methods
     public int countTokens();
     public boolean hasMoreElements();
     public boolean hasMoreTokens();
     public Object nextElement();
     public String nextToken();
    public String nextToken(String delim);
}

public StringTokenizer(String str, String delim, boolean returnTokens)

This constructor creates a new instance based on the String to be tokenized, the set of delimiters, and a flag indicating whether delimiters should be returned as tokens. The following example shows how to create a StringTokenizer for parsing simple math expressions:

String s = "4*3+2/4";
StringTokenizer st = new StringTokenizer(s, "*+/-", true);

Graphics g = getGraphics();
int tokenCount = 0;
while (st.hasMoreTokens()) {
    tokenCount++;
    g.drawString(st.nextToken(), 15, 15*tokenCount);
}

str is the String to be tokenized.

public StringTokenizer(String str, String delim)

This constructor creates a new instance based on the String to be tokenized and a set of delimiters. The following example shows how to create a StringTokenizer, which can be used on a comma-delimited String:

String s = "field1,field2,field3,and field 4";
StringTokenizer st = new StringTokenizer(s,",",false);
int tokenCount = 0;

Graphics g = getGraphics();
while (st.hasMoreTokens()) {
    tokenCount++;
    g.drawString(st.nextToken(), 15, 15*tokenCount);
}

str is the String to be tokenized.

public StringTokenizer(String str)

This constructor creates a new instance based on the String to be tokenized and the default set of delimiters. The default delimiters are the space, tab, newline, and carriage return characters.

public int countTokens()

This method returns the number of remaining tokens.

The quantity of tokens remaining in the String being tokenized.

public boolean hasMoreElements()

This method can be used to determine whether the StringTokenizer contains more elements (tokens). This method is identical to hasMoreTokens and is a member of StringTokenizer because StringTokenizer implements the Enumeration interface.

true if there are more elements; false, otherwise.

public boolean hasMoreTokens()

This method can be used to determine whether the StringTokenizer contains more tokens. It is identical to hasMoreElements.

true if there are more tokens; false, otherwise.

public Object nextElement()

This method overrides nextElement in the Enumeration interface and exists because StringTokenizer implements that interface. It is identical to nextToken and returns the next token in the enumeration.

The next token in the enumeration.

public String nextToken()

This method returns the next token in the String that is being tokenized. Typically, it is used inside a loop that processes each token. For example, the following code uses whitespace delimiters to tokenize the string "This has four tokens" and displays each of the tokens:

String s = "This has four tokens";
StringTokenizer st = new StringTokenizer(s);

int tokenCount = 0;
Graphics g = getGraphics();
while (st.hasMoreTokens()) {
    tokenCount++;
    g.drawString(st.nextToken(), 15, 15*tokenCount);
}

The next token in the string being tokenized.

public String nextToken(String delim)

This method changes the set of delimiter characters and then returns the next token. The new delimiter set remains in effect after this method completes.

delim is a String containing the new set of delimiters.

Vector

Object

The class java.util.Vector extends the class java.util.Object and implements the Cloneable interface. A Vector is analogous to a linked list in other languages or class libraries. A Vector stores items of type Object, so it can be used to store instances of any Java class. A single Vector may store different elements that are instances of different classes. The non-private interface of the class is shown in Listing 34.12.

Listing 34.12. The Vector class.

public class Vector extends Object {
  // public constructors
     public Vector(int initialCapacity, int capacityIncrement);
     public Vector(int initialCapacity);
     public Vector();
  // public instance methods
     public final synchronized void addElement(Object obj);
     public final int capacity();
     public synchronized Object clone();
     public final boolean contains(Object elem);
     public final synchronized void copyInto(Object anArray[]);
     public final synchronized Object elementAt(int index);
     public final synchronized Enumeration elements();
     public final synchronized void ensureCapacity(int minCapacity);
     public final synchronized Object firstElement();
     public final int indexOf(Object elem);
     public final synchronized int indexOf(Object elem, int index);
     public final synchronized void insertElementAt(Object obj, int index);
     public final boolean isEmpty();
     public final synchronized Object lastElement();
     public final int lastIndexOf(Object elem);
     public final synchronized int lastIndexOf(Object elem, int index);
     public final synchronized void removeAllElements();
     public final synchronized boolean removeElement(Object obj);
     public final synchronized void removeElementAt(int index);
     public final synchronized void setElementAt(Object obj, int index);
     public final synchronized void setSize(int newSize);
     public final int size();
     public final synchronized String toString();
     public final synchronized void trimToSize();
  // protected variables
     protected int capacityIncrement;
     protected int elementCount;
     protected Object elementData[];
}

public Vector(int initialCapacity, int capacityIncrement)

This constructor creates a new instance of a Vector with space for initialCapacity elements initially. Memory for additional elements is allocated in blocks that each hold capacityIncrement elements. For example, to allocate a Vector that will hold 100 elements initially and will allocate space for ten more at a time, use the following code:

Vector myVector = new Vector(100, 10);

initialCapacity is the number of elements for which to allocate space when the object is created.

public Vector(int initialCapacity)

This constructor creates a new instance of a Vector with space for initialCapacity elements. Whenever a new element that would exceed this capacity is added, the size of the vector is doubled.

initialCapacity is the number of elements for which to allocate space when the object is created.

public Vector()

This constructor creates a new instance of a Vector. Initially, the Vector has room for storing ten elements, but this increases automatically to accommodate new elements. Whenever a new element is added that exceeds this capacity, the size of the vector is doubled.

protected int capacityIncrement

This member stores the amount by which the Vector will be incremented each time it needs to grow. If capacityIncrement is 0, then the buffer does not grow by a fixed amount but instead, doubles whenever it needs to grow.

protected int elementCount

This member stores the number of elements in the Vector.

protected Object elementData[]

This member is the array where the Vector elements are stored.

public final synchronized void addElement(Object obj)

This method is used to insert new elements into the Vector. A Vector can store objects of different types. For example, to create a Vector holding three Dates and a Stack with three items pushed onto it, use the following code:

Vector myVector = new Vector();

myVector.addElement(new Date(95, 10, 14));
myVector.addElement(new Date(96, 10, 14));
myVector.addElement(new Date(97, 10, 14));

Stack s = new Stack();
s.push(new Integer(0));
s.push(new Integer(10));
s.push(new Integer(20));

myVector.addElement(s);

obj is the object to add to the vector.

public final int capacity()

The method returns the number of elements that will fit in the Vector before more space is allocated. For example, the variable qty in the following code will equal 15:

Vector myVector = new Vector(10, 5);
myVector.addElement(new Integer(1));
myVector.addElement(new Integer(2));
myVector.addElement(new Integer(3));
myVector.addElement(new Integer(4));
myVector.addElement(new Integer(5));
myVector.addElement(new Integer(6));
myVector.addElement(new Integer(7));
myVector.addElement(new Integer(8));
myVector.addElement(new Integer(9));
myVector.addElement(new Integer(10));
myVector.addElement(new Integer(11));
int qty = myVector.capacity();

In this example, qty equals 15 because of the 10 allocated by the constructor and the additional 5 allocated when the size of the Vector exceeded its initial capacity.

The number of elements that will fit in the currently allocated portion of the Vector.

public synchronized Object clone()

This method overrides clone in Object and will clone the Vector. Only the Vector itself is cloned; the elements of the Vector are not cloned. The following example creates two duplicate Vectors, each containing the same three strings:

Vector vector1 = new Vector();
vector1.addElement(new String("first string"));
vector1.addElement(new String("second string"));
vector1.addElement(new String("third string"));

Vector vector2 = (Vector)vector1.clone();

A cloned copy of the Vector.

public final boolean contains(Object elem)

This method determines whether an object is stored in a Vector. In the following example, 2 is contained in the vector but 12 is not:

Vector myVector = new Vector();
myVector.addElement(new Integer(1));
myVector.addElement(new Integer(2));
myVector.addElement(new Integer(3));

Graphics g = getGraphics();
if (myVector.contains(new Integer(2)))
    g.drawString("it contains 2", 15, 15);
if (myVector.contains(new Integer(12)))
    g.drawString("it contains 12", 15, 30);

true if the object is stored in the Vector; false, otherwise.

public final synchronized void copyInto(Object anArray[])

This method copies the elements of the Vector into an array. The following example copies the Vector into the array strArray and then displays the second string ("second string"):

String strArray[];

Vector vector1 = new Vector();
vector1.addElement(new String("first string"));
vector1.addElement(new String("second string"));
vector1.addElement(new String("third string"));

strArray = new String[vector1.size()];
vector1.copyInto(strArray);

Graphics g = getGraphics();
g.drawString("second array element is " + strArray[1], 15, 15);

anArray is the array into which the Vector elements will be copied.