File	Doc	Category	Size	Date	Package
Hashtable.java	API Doc	Java SE 6 API	35766	Tue Jun 10 00:25:54 BST 2008	java.util

Hashtable

• java.lang.Object
  • java.util.Dictionary

 {@code
Hashtable numbers
= new Hashtable();
numbers.put("one", 1);
numbers.put("two", 2);
numbers.put("three", 3);}

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

Fields Summary
private transient Entry[]	table The hash table data.
private transient int	count The total number of entries in the hash table.
private int	threshold The table is rehashed when its size exceeds this threshold. (The value of this field is (int)(capacity * loadFactor).)
private float	loadFactor The load factor for the hashtable.
private transient int	modCount The number of times this Hashtable has been structurally modified Structural modifications are those that change the number of entries in the Hashtable or otherwise modify its internal structure (e.g., rehash). This field is used to make iterators on Collection-views of the Hashtable fail-fast. (See ConcurrentModificationException).
private static final long	serialVersionUID use serialVersionUID from JDK 1.0.2 for interoperability
private volatile transient Set	keySet Each of these fields are initialized to contain an instance of the appropriate view the first time this view is requested. The views are stateless, so there's no reason to create more than one of each.
private volatile transient Set	entrySet
private volatile transient Collection	values
private static final int	KEYS
private static final int	VALUES
private static final int	ENTRIES
private static Enumeration	emptyEnumerator
private static Iterator	emptyIterator

Constructors Summary
public Hashtable(int initialCapacity, float loadFactor) Constructs a new, empty hashtable with the specified initial capacity and the specified load factor. param initialCapacity the initial capacity of the hashtable. param loadFactor the load factor of the hashtable. exception IllegalArgumentException if the initial capacity is less than zero, or if the load factor is nonpositive. if (initialCapacity < 0) throw new IllegalArgumentException("Illegal Capacity: "+ initialCapacity); if (loadFactor <= 0 || Float.isNaN(loadFactor)) throw new IllegalArgumentException("Illegal Load: "+loadFactor); if (initialCapacity==0) initialCapacity = 1; this.loadFactor = loadFactor; table = new Entry[initialCapacity]; threshold = (int)(initialCapacity * loadFactor);
public Hashtable(int initialCapacity) Constructs a new, empty hashtable with the specified initial capacity and default load factor (0.75). param initialCapacity the initial capacity of the hashtable. exception IllegalArgumentException if the initial capacity is less than zero. this(initialCapacity, 0.75f);
public Hashtable() Constructs a new, empty hashtable with a default initial capacity (11) and load factor (0.75). this(11, 0.75f);
public Hashtable(Map t) Constructs a new hashtable with the same mappings as the given Map. The hashtable is created with an initial capacity sufficient to hold the mappings in the given Map and a default load factor (0.75). param t the map whose mappings are to be placed in this map. throws NullPointerException if the specified map is null. since 1.2 this(Math.max(2*t.size(), 11), 0.75f); putAll(t);

Methods Summary
public synchronized void	clear() Clears this hashtable so that it contains no keys. Entry tab[] = table; modCount++; for (int index = tab.length; --index >= 0; ) tab[index] = null; count = 0;
public synchronized java.lang.Object	clone() Creates a shallow copy of this hashtable. All the structure of the hashtable itself is copied, but the keys and values are not cloned. This is a relatively expensive operation. return a clone of the hashtable try { Hashtable<K,V> t = (Hashtable<K,V>) super.clone(); t.table = new Entry[table.length]; for (int i = table.length ; i-- > 0 ; ) { t.table[i] = (table[i] != null) ? (Entry<K,V>) table[i].clone() : null; } t.keySet = null; t.entrySet = null; t.values = null; t.modCount = 0; return t; } catch (CloneNotSupportedException e) { // this shouldn't happen, since we are Cloneable throw new InternalError(); }
public synchronized boolean	contains(java.lang.Object value) Tests if some key maps into the specified value in this hashtable. This operation is more expensive than the {@link #containsKey containsKey} method. Note that this method is identical in functionality to {@link #containsValue containsValue}, (which is part of the {@link Map} interface in the collections framework). param value a value to search for return true if and only if some key maps to the value argument in this hashtable as determined by the equals method; false otherwise. exception NullPointerException if the value is null if (value == null) { throw new NullPointerException(); } Entry tab[] = table; for (int i = tab.length ; i-- > 0 ;) { for (Entry<K,V> e = tab[i] ; e != null ; e = e.next) { if (e.value.equals(value)) { return true; } } } return false;
public synchronized boolean	containsKey(java.lang.Object key) Tests if the specified object is a key in this hashtable. param key possible key return true if and only if the specified object is a key in this hashtable, as determined by the equals method; false otherwise. throws NullPointerException if the key is null see #contains(Object) Entry tab[] = table; int hash = key.hashCode(); int index = (hash & 0x7FFFFFFF) % tab.length; for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) { if ((e.hash == hash) && e.key.equals(key)) { return true; } } return false;
public boolean	containsValue(java.lang.Object value) Returns true if this hashtable maps one or more keys to this value. Note that this method is identical in functionality to {@link #contains contains} (which predates the {@link Map} interface). param value value whose presence in this hashtable is to be tested return true if this map maps one or more keys to the specified value throws NullPointerException if the value is null since 1.2 return contains(value);
public synchronized java.util.Enumeration	elements() Returns an enumeration of the values in this hashtable. Use the Enumeration methods on the returned object to fetch the elements sequentially. return an enumeration of the values in this hashtable. see java.util.Enumeration see #keys() see #values() see Map return this.<V>getEnumeration(VALUES);
public java.util.Set	entrySet() Returns a {@link Set} view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations. since 1.2 if (entrySet==null) entrySet = Collections.synchronizedSet(new EntrySet(), this); return entrySet;
public synchronized boolean	equals(java.lang.Object o) Compares the specified Object with this Map for equality, as per the definition in the Map interface. param o object to be compared for equality with this hashtable return true if the specified Object is equal to this Map see Map#equals(Object) since 1.2 if (o == this) return true; if (!(o instanceof Map)) return false; Map<K,V> t = (Map<K,V>) o; if (t.size() != size()) return false; try { Iterator<Map.Entry<K,V>> i = entrySet().iterator(); while (i.hasNext()) { Map.Entry<K,V> e = i.next(); K key = e.getKey(); V value = e.getValue(); if (value == null) { if (!(t.get(key)==null && t.containsKey(key))) return false; } else { if (!value.equals(t.get(key))) return false; } } } catch (ClassCastException unused) { return false; } catch (NullPointerException unused) { return false; } return true;
public synchronized V	get(java.lang.Object key) Returns the value to which the specified key is mapped, or {@code null} if this map contains no mapping for the key. More formally, if this map contains a mapping from a key {@code k} to a value {@code v} such that {@code (key.equals(k))}, then this method returns {@code v}; otherwise it returns {@code null}. (There can be at most one such mapping.) param key the key whose associated value is to be returned return the value to which the specified key is mapped, or {@code null} if this map contains no mapping for the key throws NullPointerException if the specified key is null see #put(Object, Object) Entry tab[] = table; int hash = key.hashCode(); int index = (hash & 0x7FFFFFFF) % tab.length; for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) { if ((e.hash == hash) && e.key.equals(key)) { return e.value; } } return null;
private java.util.Enumeration	getEnumeration(int type) if (count == 0) { return (Enumeration<T>)emptyEnumerator; } else { return new Enumerator<T>(type, false); }
private java.util.Iterator	getIterator(int type) if (count == 0) { return (Iterator<T>) emptyIterator; } else { return new Enumerator<T>(type, true); }
public synchronized int	hashCode() Returns the hash code value for this Map as per the definition in the Map interface. see Map#hashCode() since 1.2 /* * This code detects the recursion caused by computing the hash code * of a self-referential hash table and prevents the stack overflow * that would otherwise result. This allows certain 1.1-era * applets with self-referential hash tables to work. This code * abuses the loadFactor field to do double-duty as a hashCode * in progress flag, so as not to worsen the space performance. * A negative load factor indicates that hash code computation is * in progress. */ int h = 0; if (count == 0 || loadFactor < 0) return h; // Returns zero loadFactor = -loadFactor; // Mark hashCode computation in progress Entry[] tab = table; for (int i = 0; i < tab.length; i++) for (Entry e = tab[i]; e != null; e = e.next) h += e.key.hashCode() ^ e.value.hashCode(); loadFactor = -loadFactor; // Mark hashCode computation complete return h;
public synchronized boolean	isEmpty() Tests if this hashtable maps no keys to values. return true if this hashtable maps no keys to values; false otherwise. return count == 0;
public java.util.Set	keySet() Returns a {@link Set} view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations. since 1.2 if (keySet == null) keySet = Collections.synchronizedSet(new KeySet(), this); return keySet;
public synchronized java.util.Enumeration	keys() Returns an enumeration of the keys in this hashtable. return an enumeration of the keys in this hashtable. see Enumeration see #elements() see #keySet() see Map return this.<K>getEnumeration(KEYS);
public synchronized V	put(K key, V value) Maps the specified key to the specified value in this hashtable. Neither the key nor the value can be null. The value can be retrieved by calling the get method with a key that is equal to the original key. param key the hashtable key param value the value return the previous value of the specified key in this hashtable, or null if it did not have one exception NullPointerException if the key or value is null see Object#equals(Object) see #get(Object) // Make sure the value is not null if (value == null) { throw new NullPointerException(); } // Makes sure the key is not already in the hashtable. Entry tab[] = table; int hash = key.hashCode(); int index = (hash & 0x7FFFFFFF) % tab.length; for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) { if ((e.hash == hash) && e.key.equals(key)) { V old = e.value; e.value = value; return old; } } modCount++; if (count >= threshold) { // Rehash the table if the threshold is exceeded rehash(); tab = table; index = (hash & 0x7FFFFFFF) % tab.length; } // Creates the new entry. Entry<K,V> e = tab[index]; tab[index] = new Entry<K,V>(hash, key, value, e); count++; return null;
public synchronized void	putAll(java.util.Map t) Copies all of the mappings from the specified map to this hashtable. These mappings will replace any mappings that this hashtable had for any of the keys currently in the specified map. param t mappings to be stored in this map throws NullPointerException if the specified map is null since 1.2 for (Map.Entry<? extends K, ? extends V> e : t.entrySet()) put(e.getKey(), e.getValue());
private void	readObject(java.io.ObjectInputStream s) Reconstitute the Hashtable from a stream (i.e., deserialize it). // Read in the length, threshold, and loadfactor s.defaultReadObject(); // Read the original length of the array and number of elements int origlength = s.readInt(); int elements = s.readInt(); // Compute new size with a bit of room 5% to grow but // no larger than the original size. Make the length // odd if it's large enough, this helps distribute the entries. // Guard against the length ending up zero, that's not valid. int length = (int)(elements * loadFactor) + (elements / 20) + 3; if (length > elements && (length & 1) == 0) length--; if (origlength > 0 && length > origlength) length = origlength; Entry[] table = new Entry[length]; count = 0; // Read the number of elements and then all the key/value objects for (; elements > 0; elements--) { K key = (K)s.readObject(); V value = (V)s.readObject(); // synch could be eliminated for performance reconstitutionPut(table, key, value); } this.table = table;
private void	reconstitutionPut(java.util.Hashtable$Entry[] tab, K key, V value) The put method used by readObject. This is provided because put is overridable and should not be called in readObject since the subclass will not yet be initialized. This differs from the regular put method in several ways. No checking for rehashing is necessary since the number of elements initially in the table is known. The modCount is not incremented because we are creating a new instance. Also, no return value is needed. if (value == null) { throw new java.io.StreamCorruptedException(); } // Makes sure the key is not already in the hashtable. // This should not happen in deserialized version. int hash = key.hashCode(); int index = (hash & 0x7FFFFFFF) % tab.length; for (Entry<K,V> e = tab[index] ; e != null ; e = e.next) { if ((e.hash == hash) && e.key.equals(key)) { throw new java.io.StreamCorruptedException(); } } // Creates the new entry. Entry<K,V> e = tab[index]; tab[index] = new Entry<K,V>(hash, key, value, e); count++;
protected void	rehash() Increases the capacity of and internally reorganizes this hashtable, in order to accommodate and access its entries more efficiently. This method is called automatically when the number of keys in the hashtable exceeds this hashtable's capacity and load factor. int oldCapacity = table.length; Entry[] oldMap = table; int newCapacity = oldCapacity * 2 + 1; Entry[] newMap = new Entry[newCapacity]; modCount++; threshold = (int)(newCapacity * loadFactor); table = newMap; for (int i = oldCapacity ; i-- > 0 ;) { for (Entry<K,V> old = oldMap[i] ; old != null ; ) { Entry<K,V> e = old; old = old.next; int index = (e.hash & 0x7FFFFFFF) % newCapacity; e.next = newMap[index]; newMap[index] = e; } }
public synchronized V	remove(java.lang.Object key) Removes the key (and its corresponding value) from this hashtable. This method does nothing if the key is not in the hashtable. param key the key that needs to be removed return the value to which the key had been mapped in this hashtable, or null if the key did not have a mapping throws NullPointerException if the key is null Entry tab[] = table; int hash = key.hashCode(); int index = (hash & 0x7FFFFFFF) % tab.length; for (Entry<K,V> e = tab[index], prev = null ; e != null ; prev = e, e = e.next) { if ((e.hash == hash) && e.key.equals(key)) { modCount++; if (prev != null) { prev.next = e.next; } else { tab[index] = e.next; } count--; V oldValue = e.value; e.value = null; return oldValue; } } return null;
public synchronized int	size() Returns the number of keys in this hashtable. return the number of keys in this hashtable. return count;
public synchronized java.lang.String	toString() Returns a string representation of this Hashtable object in the form of a set of entries, enclosed in braces and separated by the ASCII characters ", " (comma and space). Each entry is rendered as the key, an equals sign =, and the associated element, where the toString method is used to convert the key and element to strings. return a string representation of this hashtable int max = size() - 1; if (max == -1) return "{}"; StringBuilder sb = new StringBuilder(); Iterator<Map.Entry<K,V>> it = entrySet().iterator(); sb.append('{"); for (int i = 0; ; i++) { Map.Entry<K,V> e = it.next(); K key = e.getKey(); V value = e.getValue(); sb.append(key == this ? "(this Map)" : key.toString()); sb.append('="); sb.append(value == this ? "(this Map)" : value.toString()); if (i == max) return sb.append('}").toString(); sb.append(", "); }
public java.util.Collection	values() Returns a {@link Collection} view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations. since 1.2 if (values==null) values = Collections.synchronizedCollection(new ValueCollection(), this); return values;
private synchronized void	writeObject(java.io.ObjectOutputStream s) Save the state of the Hashtable to a stream (i.e., serialize it). serialData The capacity of the Hashtable (the length of the bucket array) is emitted (int), followed by the size of the Hashtable (the number of key-value mappings), followed by the key (Object) and value (Object) for each key-value mapping represented by the Hashtable The key-value mappings are emitted in no particular order. // Write out the length, threshold, loadfactor s.defaultWriteObject(); // Write out length, count of elements and then the key/value objects s.writeInt(table.length); s.writeInt(count); for (int index = table.length-1; index >= 0; index--) { Entry entry = table[index]; while (entry != null) { s.writeObject(entry.key); s.writeObject(entry.value); entry = entry.next; } }