java.util
Class Hashtable

java.lang.Object
  extended by java.util.Hashtable
Direct Known Subclasses:
ObjectPathHashtableBase, ContentProtectedHashtable

public class Hashtable
extends Object

This class implements a hashtable, which maps keys to values.

Any non-null object can be used as a key or as a value. To successfully store and retrieve objects from a hashtable, the objects used as keys must implement the Object.hashCode() and Object.equals(java.lang.Object) methods.

A hashtable has two parameters that affect its efficiency: its capacity and its load factor. The load factor should be between 0.0 and 1.0. When the number of entries in the hashtable exceeds the product of the load factor and the current capacity, the capacity is increased by invoking Hashtable.rehash(). Larger load factors use memory more efficiently, at the expense of larger expected time per lookup.

If many entries are to be made into a hashtable, creating it with a sufficiently large capacity may allow the entries to be inserted more efficiently than letting it perform automatic rehashing as needed to grow the table.

This example creates a hashtable of numbers. It uses the names of the numbers as keys:

     Hashtable numbers = new Hashtable();
     numbers.put("one", new Integer(1));
     numbers.put("two", new Integer(2));
     numbers.put("three", new Integer(3));
 

To retrieve a number, use the following code:

     Integer n = (Integer)numbers.get("two");
     if( n != null ) {
         System.out.println("two = " + n);
     }
 

This hashtable implementation is significantly more object-efficient than the original JDK version. However, for hashtables mapping integers to objects or integers to integers, see IntHashtable and IntIntHashtable.


Constructor Summary
Hashtable()
          Construct a new, empty hashtable with a default capacity and load factor.
Hashtable(int initialCapacity)
          Construct a new, empty hashtable with the specified capacity.
 
Method Summary
 void clear()
          Flush this hashtable.
 boolean contains(Object value)
          Determines if some key maps into the specified value in this hashtable.
 boolean containsKey(Object key)
          Determines if the specified object is a key in this hashtable.
 Enumeration elements()
          Retrieves an enumeration of the values in this hashtable.
 Object get(Object key)
          Retrieves value by key.
 boolean isEmpty()
          Determines if this hashtable maps no keys to values.
 Enumeration keys()
          Retrieves an enumeration of the keys in this hashtable.
 Object put(Object key, Object value)
          Maps value to key in this hashtable.
protected  void rehash()
          Rehashes the contents of this hashtable.
 Object remove(Object key)
          Removes value by key.
 int size()
          Retrieves the number of keys in this hashtable.
 String toString()
          Retrieves string representation of this hashtable.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Constructor Detail

Hashtable

public Hashtable(int initialCapacity)
Construct a new, empty hashtable with the specified capacity.

Parameters:
initialCapacity - Initial capacity of the hashtable.
Throws:
IllegalArgumentException - If the initial capacity is less than zero

Hashtable

public Hashtable()
Construct a new, empty hashtable with a default capacity and load factor.



Method Detail

size

public int size()
Retrieves the number of keys in this hashtable.

Returns:
Number of keys in this hashtable.

isEmpty

public boolean isEmpty()
Determines if this hashtable maps no keys to values.

Returns:
True if this hashtable has no keys mapped to values; otherwise, false.

keys

public Enumeration keys()
Retrieves an enumeration of the keys in this hashtable.

Returns:
Enumeration of keys in this hashtable.
See Also:
Enumeration, Hashtable.elements()

elements

public Enumeration elements()
Retrieves an enumeration of the values in this hashtable.

Use the Enumeration methods on the returned object to fetch the elements sequentially.

Returns:
Enumeration of the values in this hashtable.
See Also:
Enumeration, Hashtable.keys()

contains

public boolean contains(Object value)
Determines if some key maps into the specified value in this hashtable.

This operation is more expensive than Hashtable.containsKey(java.lang.Object).

Parameters:
value - Value to search for.
Returns:
True if some key maps to the provided value in this hashtable; otherwise, false.
Throws:
NullPointerException - If null value provided.

containsKey

public boolean containsKey(Object key)
Determines if the specified object is a key in this hashtable.

Parameters:
key - Key to test.
Returns:
True if provided object is a key in this hashtable; otherwise, false.
See Also:
Hashtable.contains(java.lang.Object)

clear

public void clear()
Flush this hashtable.

Invoke this method to remove all keys and values from this hashtable.


toString

public String toString()
Retrieves string representation of this hashtable.

Overrides:
toString in class Object
Returns:
String form of this hashtable.

remove

public Object remove(Object key)
Removes value by key.

If the key does not exist in this hashtable, then this method does nothing.

Parameters:
key - Key for value to remove.
Returns:
Value that had been associated with key, or null if no value had been associated with key.

get

public Object get(Object key)
Retrieves value by key.

Parameters:
key - Key in this hashtable.
Returns:
Object value associated with provided key, or null if no object associated with the key.

rehash

protected void rehash()
Rehashes the contents of this hashtable.

Invoke this method to rehash this hashtable into one with a larger capacity. This hashtable invokes this method automatically when the number of keys exceeds its capacity and load factor.


put

public Object put(Object key,
                  Object value)
Maps value to key in this hashtable.

The value can be retrieved by invoking Hashtable.get(java.lang.Object) with a key that is equal to the original key (as determined by Object.equals(java.lang.Object).

Parameters:
key - Key to associate with the value.
value - Value to put into table.
Returns:
Previous value associated with key, or null if key had no previous associated value.
Throws:
NullPointerException - If null key or null value.





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.