org.apache.commons.collections.map
Class AbstractHashedMap

java.lang.Object
  java.util.AbstractMap
      org.apache.commons.collections.map.AbstractHashedMap

All Implemented Interfaces:

java.util.Map, IterableMap

Direct Known Subclasses:

AbstractLinkedMap, AbstractReferenceMap, CaseInsensitiveMap, HashedMap, IdentityMap

public class AbstractHashedMap
extends java.util.AbstractMap
implements IterableMap

An abstract implementation of a hash-based map which provides numerous points for subclasses to override.

This class implements all the features necessary for a subclass hash-based map. Key-value entries are stored in instances of the HashEntry class, which can be overridden and replaced. The iterators can similarly be replaced, without the need to replace the KeySet, EntrySet and Values view classes.

Overridable methods are provided to change the default hashing behaviour, and to change how entries are added to and removed from the map. Hopefully, all you need for unusual subclasses is here.

NOTE: From Commons Collections 3.1 this class extends AbstractMap. This is to provide backwards compatibility for ReferenceMap between v3.0 and v3.1. This extends clause will be removed in v4.0.

Since:

Commons Collections 3.0

Version:

$Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $

Author:

java util HashMap, Stephen Colebourne, Christian Siefkes

Nested Class Summary

protected static class	AbstractHashedMap.EntrySet EntrySet implementation.
protected static class	AbstractHashedMap.EntrySetIterator EntrySet iterator.
protected static class	AbstractHashedMap.HashEntry HashEntry used to store the data.
protected static class	AbstractHashedMap.HashIterator Base Iterator
protected static class	AbstractHashedMap.HashMapIterator MapIterator implementation.
protected static class	AbstractHashedMap.KeySet KeySet implementation.
protected static class	AbstractHashedMap.KeySetIterator KeySet iterator.
protected static class	AbstractHashedMap.Values Values implementation.
protected static class	AbstractHashedMap.ValuesIterator Values iterator.

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry

Field Summary

protected AbstractHashedMap.HashEntry[]	data Map entries
protected static int	DEFAULT_CAPACITY The default capacity to use
protected static float	DEFAULT_LOAD_FACTOR The default load factor to use
protected static int	DEFAULT_THRESHOLD The default threshold to use
protected AbstractHashedMap.EntrySet	entrySet Entry set
protected static java.lang.String	GETKEY_INVALID
protected static java.lang.String	GETVALUE_INVALID
protected AbstractHashedMap.KeySet	keySet Key set
protected float	loadFactor Load factor, normally 0.75
protected static int	MAXIMUM_CAPACITY The maximum capacity allowed
protected int	modCount Modification count for iterators
protected static java.lang.String	NO_NEXT_ENTRY
protected static java.lang.String	NO_PREVIOUS_ENTRY
protected static java.lang.Object	NULL An object for masking null
protected static java.lang.String	REMOVE_INVALID
protected static java.lang.String	SETVALUE_INVALID
protected int	size The size of the map
protected int	threshold Size at which to rehash
protected AbstractHashedMap.Values	values Values

Constructor Summary

protected	AbstractHashedMap() Constructor only used in deserialization, do not use otherwise.
protected	AbstractHashedMap(int initialCapacity) Constructs a new, empty map with the specified initial capacity and default load factor.
protected	AbstractHashedMap(int initialCapacity, float loadFactor) Constructs a new, empty map with the specified initial capacity and load factor.
protected	AbstractHashedMap(int initialCapacity, float loadFactor, int threshold) Constructor which performs no validation on the passed in parameters.
protected	AbstractHashedMap(java.util.Map map) Constructor copying elements from another map.

Method Summary

protected void	addEntry(AbstractHashedMap.HashEntry entry, int hashIndex) Adds an entry into this map.
protected void	addMapping(int hashIndex, int hashCode, java.lang.Object key, java.lang.Object value) Adds a new key-value mapping into this map.
protected int	calculateNewCapacity(int proposedCapacity) Calculates the new capacity of the map.
protected int	calculateThreshold(int newCapacity, float factor) Calculates the new threshold of the map, where it will be resized.
protected void	checkCapacity() Checks the capacity of the map and enlarges it if necessary.
void	clear() Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues.
protected java.lang.Object	clone() Clones the map without cloning the keys or values.
boolean	containsKey(java.lang.Object key) Checks whether the map contains the specified key.
boolean	containsValue(java.lang.Object value) Checks whether the map contains the specified value.
protected java.lang.Object	convertKey(java.lang.Object key) Converts input keys to another object for storage in the map.
protected AbstractHashedMap.HashEntry	createEntry(AbstractHashedMap.HashEntry next, int hashCode, java.lang.Object key, java.lang.Object value) Creates an entry to store the key-value data.
protected java.util.Iterator	createEntrySetIterator() Creates an entry set iterator.
protected java.util.Iterator	createKeySetIterator() Creates a key set iterator.
protected java.util.Iterator	createValuesIterator() Creates a values iterator.
protected void	destroyEntry(AbstractHashedMap.HashEntry entry) Kills an entry ready for the garbage collector.
protected void	doReadObject(java.io.ObjectInputStream in) Reads the map data from the stream.
protected void	doWriteObject(java.io.ObjectOutputStream out) Writes the map data to the stream.
protected void	ensureCapacity(int newCapacity) Changes the size of the data structure to the capacity proposed.
protected int	entryHashCode(AbstractHashedMap.HashEntry entry) Gets the hashCode field from a HashEntry.
protected java.lang.Object	entryKey(AbstractHashedMap.HashEntry entry) Gets the key field from a HashEntry.
protected AbstractHashedMap.HashEntry	entryNext(AbstractHashedMap.HashEntry entry) Gets the next field from a HashEntry.
java.util.Set	entrySet() Gets the entrySet view of the map.
protected java.lang.Object	entryValue(AbstractHashedMap.HashEntry entry) Gets the value field from a HashEntry.
boolean	equals(java.lang.Object obj) Compares this map with another.
java.lang.Object	get(java.lang.Object key) Gets the value mapped to the key specified.
protected AbstractHashedMap.HashEntry	getEntry(java.lang.Object key) Gets the entry mapped to the key specified.
protected int	hash(java.lang.Object key) Gets the hash code for the key specified.
int	hashCode() Gets the standard Map hashCode.
protected int	hashIndex(int hashCode, int dataSize) Gets the index into the data storage for the hashCode specified.
protected void	init() Initialise subclasses during construction, cloning or deserialization.
boolean	isEmpty() Checks whether the map is currently empty.
protected boolean	isEqualKey(java.lang.Object key1, java.lang.Object key2) Compares two keys, in internal converted form, to see if they are equal.
protected boolean	isEqualValue(java.lang.Object value1, java.lang.Object value2) Compares two values, in external form, to see if they are equal.
java.util.Set	keySet() Gets the keySet view of the map.
MapIterator	mapIterator() Gets an iterator over the map.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Puts a key-value mapping into this map.
void	putAll(java.util.Map map) Puts all the values from the specified map into this map.
java.lang.Object	remove(java.lang.Object key) Removes the specified mapping from this map.
protected void	removeEntry(AbstractHashedMap.HashEntry entry, int hashIndex, AbstractHashedMap.HashEntry previous) Removes an entry from the chain stored in a particular index.
protected void	removeMapping(AbstractHashedMap.HashEntry entry, int hashIndex, AbstractHashedMap.HashEntry previous) Removes a mapping from the map.
protected void	reuseEntry(AbstractHashedMap.HashEntry entry, int hashIndex, int hashCode, java.lang.Object key, java.lang.Object value) Reuses an existing key-value mapping, storing completely new data.
int	size() Gets the size of the map.
java.lang.String	toString() Gets the map as a String.
protected void	updateEntry(AbstractHashedMap.HashEntry entry, java.lang.Object newValue) Updates an existing key-value mapping to change the value.
java.util.Collection	values() Gets the values view of the map.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NO_NEXT_ENTRY

protected static final java.lang.String NO_NEXT_ENTRY

See Also:

Constant Field Values

NO_PREVIOUS_ENTRY

protected static final java.lang.String NO_PREVIOUS_ENTRY

See Also:

Constant Field Values

REMOVE_INVALID

protected static final java.lang.String REMOVE_INVALID

See Also:

Constant Field Values

GETKEY_INVALID

protected static final java.lang.String GETKEY_INVALID

See Also:

Constant Field Values

GETVALUE_INVALID

protected static final java.lang.String GETVALUE_INVALID

See Also:

Constant Field Values

SETVALUE_INVALID

protected static final java.lang.String SETVALUE_INVALID

See Also:

Constant Field Values

DEFAULT_CAPACITY

protected static final int DEFAULT_CAPACITY

The default capacity to use

See Also:

Constant Field Values

DEFAULT_THRESHOLD

protected static final int DEFAULT_THRESHOLD

The default threshold to use

See Also:

Constant Field Values

DEFAULT_LOAD_FACTOR

protected static final float DEFAULT_LOAD_FACTOR

The default load factor to use

See Also:

Constant Field Values

MAXIMUM_CAPACITY

protected static final int MAXIMUM_CAPACITY

The maximum capacity allowed

See Also:

Constant Field Values

NULL

protected static final java.lang.Object NULL

An object for masking null

loadFactor

protected transient float loadFactor

Load factor, normally 0.75

size

protected transient int size

The size of the map

data

protected transient AbstractHashedMap.HashEntry[] data

Map entries

threshold

protected transient int threshold

Size at which to rehash

modCount

protected transient int modCount

Modification count for iterators

entrySet

protected transient AbstractHashedMap.EntrySet entrySet

Entry set

keySet

protected transient AbstractHashedMap.KeySet keySet

Key set

values

protected transient AbstractHashedMap.Values values

Values

Constructor Detail

AbstractHashedMap

protected AbstractHashedMap()

Constructor only used in deserialization, do not use otherwise.

AbstractHashedMap

protected AbstractHashedMap(int initialCapacity,
                            float loadFactor,
                            int threshold)

Constructor which performs no validation on the passed in parameters.

Parameters:

initialCapacity - the initial capacity, must be a power of two

loadFactor - the load factor, must be > 0.0f and generally < 1.0f

threshold - the threshold, must be sensible

AbstractHashedMap

protected AbstractHashedMap(int initialCapacity)

Constructs a new, empty map with the specified initial capacity and default load factor.

Parameters:

initialCapacity - the initial capacity

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than one

AbstractHashedMap

protected AbstractHashedMap(int initialCapacity,
                            float loadFactor)

Constructs a new, empty map with the specified initial capacity and load factor.

Parameters:

initialCapacity - the initial capacity

loadFactor - the load factor

Throws:

java.lang.IllegalArgumentException - if the initial capacity is less than one

java.lang.IllegalArgumentException - if the load factor is less than or equal to zero

AbstractHashedMap

protected AbstractHashedMap(java.util.Map map)

Constructor copying elements from another map.

Parameters:

map - the map to copy

Throws:

java.lang.NullPointerException - if the map is null

Method Detail

init

protected void init()

Initialise subclasses during construction, cloning or deserialization.

get

public java.lang.Object get(java.lang.Object key)

Gets the value mapped to the key specified.

Specified by:

get in interface java.util.Map

Overrides:

get in class java.util.AbstractMap

Parameters:

key - the key

Returns:

the mapped value, null if no match

size

public int size()

Gets the size of the map.

Specified by:

size in interface java.util.Map

Overrides:

size in class java.util.AbstractMap

Returns:

the size

isEmpty

public boolean isEmpty()

Checks whether the map is currently empty.

Specified by:

isEmpty in interface java.util.Map

Overrides:

isEmpty in class java.util.AbstractMap

Returns:

true if the map is currently size zero

containsKey

public boolean containsKey(java.lang.Object key)

Checks whether the map contains the specified key.

Specified by:

containsKey in interface java.util.Map

Overrides:

containsKey in class java.util.AbstractMap

Parameters:

key - the key to search for

Returns:

true if the map contains the key

containsValue

public boolean containsValue(java.lang.Object value)

Checks whether the map contains the specified value.

Specified by:

containsValue in interface java.util.Map

Overrides:

containsValue in class java.util.AbstractMap

Parameters:

value - the value to search for

Returns:

true if the map contains the value

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Puts a key-value mapping into this map.

Specified by:

put in interface java.util.Map

Overrides:

put in class java.util.AbstractMap

Parameters:

key - the key to add

value - the value to add

Returns:

the value previously mapped to this key, null if none

putAll

public void putAll(java.util.Map map)

Puts all the values from the specified map into this map.

This implementation iterates around the specified map and uses put(Object, Object).

Specified by:

putAll in interface java.util.Map

Overrides:

putAll in class java.util.AbstractMap

Parameters:

map - the map to add

Throws:

java.lang.NullPointerException - if the map is null

remove

public java.lang.Object remove(java.lang.Object key)

Removes the specified mapping from this map.

Specified by:

remove in interface java.util.Map

Overrides:

remove in class java.util.AbstractMap

Parameters:

key - the mapping to remove

Returns:

the value mapped to the removed key, null if key not in map

clear

public void clear()

Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues.

Specified by:

clear in interface java.util.Map

Overrides:

clear in class java.util.AbstractMap

convertKey

protected java.lang.Object convertKey(java.lang.Object key)

Converts input keys to another object for storage in the map. This implementation masks nulls. Subclasses can override this to perform alternate key conversions.

The reverse conversion can be changed, if required, by overriding the getKey() method in the hash entry.

Parameters:

key - the key convert

Returns:

the converted key

hash

protected int hash(java.lang.Object key)

Gets the hash code for the key specified. This implementation uses the additional hashing routine from JDK1.4. Subclasses can override this to return alternate hash codes.

Parameters:

key - the key to get a hash code for

Returns:

the hash code

isEqualKey

protected boolean isEqualKey(java.lang.Object key1,
                             java.lang.Object key2)

Compares two keys, in internal converted form, to see if they are equal. This implementation uses the equals method and assumes neither key is null. Subclasses can override this to match differently.

Parameters:

key1 - the first key to compare passed in from outside

key2 - the second key extracted from the entry via entry.key

Returns:

true if equal

isEqualValue

protected boolean isEqualValue(java.lang.Object value1,
                               java.lang.Object value2)

Compares two values, in external form, to see if they are equal. This implementation uses the equals method and assumes neither value is null. Subclasses can override this to match differently.

Parameters:

value1 - the first value to compare passed in from outside

value2 - the second value extracted from the entry via getValue()

Returns:

true if equal

hashIndex

protected int hashIndex(int hashCode,
                        int dataSize)

Gets the index into the data storage for the hashCode specified. This implementation uses the least significant bits of the hashCode. Subclasses can override this to return alternate bucketing.

Parameters:

hashCode - the hash code to use

dataSize - the size of the data to pick a bucket from

Returns:

the bucket index

getEntry

protected AbstractHashedMap.HashEntry getEntry(java.lang.Object key)

Gets the entry mapped to the key specified.

This method exists for subclasses that may need to perform a multi-step process accessing the entry. The public methods in this class don't use this method to gain a small performance boost.

Parameters:

key - the key

Returns:

the entry, null if no match

updateEntry

protected void updateEntry(AbstractHashedMap.HashEntry entry,
                           java.lang.Object newValue)

Updates an existing key-value mapping to change the value.

This implementation calls setValue() on the entry. Subclasses could override to handle changes to the map.

Parameters:

entry - the entry to update

newValue - the new value to store

reuseEntry

protected void reuseEntry(AbstractHashedMap.HashEntry entry,
                          int hashIndex,
                          int hashCode,
                          java.lang.Object key,
                          java.lang.Object value)

Reuses an existing key-value mapping, storing completely new data.

This implementation sets all the data fields on the entry. Subclasses could populate additional entry fields.

Parameters:

entry - the entry to update, not null

hashIndex - the index in the data array

hashCode - the hash code of the key to add

key - the key to add

value - the value to add

addMapping

protected void addMapping(int hashIndex,
                          int hashCode,
                          java.lang.Object key,
                          java.lang.Object value)

Adds a new key-value mapping into this map.

This implementation calls createEntry(), addEntry() and checkCapacity(). It also handles changes to modCount and size. Subclasses could override to fully control adds to the map.

Parameters:

hashIndex - the index into the data array to store at

hashCode - the hash code of the key to add

key - the key to add

value - the value to add

createEntry

protected AbstractHashedMap.HashEntry createEntry(AbstractHashedMap.HashEntry next,
                                                  int hashCode,
                                                  java.lang.Object key,
                                                  java.lang.Object value)

Creates an entry to store the key-value data.

This implementation creates a new HashEntry instance. Subclasses can override this to return a different storage class, or implement caching.

Parameters:

next - the next entry in sequence

hashCode - the hash code to use

key - the key to store

value - the value to store

Returns:

the newly created entry

addEntry

protected void addEntry(AbstractHashedMap.HashEntry entry,
                        int hashIndex)

Adds an entry into this map.

This implementation adds the entry to the data storage table. Subclasses could override to handle changes to the map.

Parameters:

entry - the entry to add

hashIndex - the index into the data array to store at

removeMapping

protected void removeMapping(AbstractHashedMap.HashEntry entry,
                             int hashIndex,
                             AbstractHashedMap.HashEntry previous)

Removes a mapping from the map.

This implementation calls removeEntry() and destroyEntry(). It also handles changes to modCount and size. Subclasses could override to fully control removals from the map.

Parameters:

entry - the entry to remove

hashIndex - the index into the data structure

previous - the previous entry in the chain

removeEntry

protected void removeEntry(AbstractHashedMap.HashEntry entry,
                           int hashIndex,
                           AbstractHashedMap.HashEntry previous)

Removes an entry from the chain stored in a particular index.

This implementation removes the entry from the data storage table. The size is not updated. Subclasses could override to handle changes to the map.

Parameters:

entry - the entry to remove

hashIndex - the index into the data structure

previous - the previous entry in the chain

destroyEntry

protected void destroyEntry(AbstractHashedMap.HashEntry entry)

Kills an entry ready for the garbage collector.

This implementation prepares the HashEntry for garbage collection. Subclasses can override this to implement caching (override clear as well).

Parameters:

entry - the entry to destroy

checkCapacity

protected void checkCapacity()

Checks the capacity of the map and enlarges it if necessary.

This implementation uses the threshold to check if the map needs enlarging

ensureCapacity

protected void ensureCapacity(int newCapacity)

Changes the size of the data structure to the capacity proposed.

Parameters:

newCapacity - the new capacity of the array (a power of two, less or equal to max)

calculateNewCapacity

protected int calculateNewCapacity(int proposedCapacity)

Calculates the new capacity of the map. This implementation normalizes the capacity to a power of two.

Parameters:

proposedCapacity - the proposed capacity

Returns:

the normalized new capacity

calculateThreshold

protected int calculateThreshold(int newCapacity,
                                 float factor)

Calculates the new threshold of the map, where it will be resized. This implementation uses the load factor.

Parameters:

newCapacity - the new capacity

factor - the load factor

Returns:

the new resize threshold

entryNext

protected AbstractHashedMap.HashEntry entryNext(AbstractHashedMap.HashEntry entry)

Gets the next field from a HashEntry. Used in subclasses that have no visibility of the field.

Parameters:

entry - the entry to query, must not be null

Returns:

the next field of the entry

Throws:

java.lang.NullPointerException - if the entry is null

Since:

Commons Collections 3.1

entryHashCode

protected int entryHashCode(AbstractHashedMap.HashEntry entry)

Gets the hashCode field from a HashEntry. Used in subclasses that have no visibility of the field.

Parameters:

entry - the entry to query, must not be null

Returns:

the hashCode field of the entry

Throws:

java.lang.NullPointerException - if the entry is null

Since:

Commons Collections 3.1

entryKey

protected java.lang.Object entryKey(AbstractHashedMap.HashEntry entry)

Gets the key field from a HashEntry. Used in subclasses that have no visibility of the field.

Parameters:

entry - the entry to query, must not be null

Returns:

the key field of the entry

Throws:

java.lang.NullPointerException - if the entry is null

Since:

Commons Collections 3.1

entryValue

protected java.lang.Object entryValue(AbstractHashedMap.HashEntry entry)

Gets the value field from a HashEntry. Used in subclasses that have no visibility of the field.

Parameters:

entry - the entry to query, must not be null

Returns:

the value field of the entry

Throws:

java.lang.NullPointerException - if the entry is null

Since:

Commons Collections 3.1

mapIterator

public MapIterator mapIterator()

Gets an iterator over the map. Changes made to the iterator affect this map.

A MapIterator returns the keys in the map. It also provides convenient methods to get the key and value, and set the value. It avoids the need to create an entrySet/keySet/values object. It also avoids creating the Map.Entry object.

Specified by:

mapIterator in interface IterableMap

Returns:

the map iterator

entrySet

public java.util.Set entrySet()

Gets the entrySet view of the map. Changes made to the view affect this map. To simply iterate through the entries, use mapIterator().

Specified by:

entrySet in interface java.util.Map

Specified by:

entrySet in class java.util.AbstractMap

Returns:

the entrySet view

createEntrySetIterator

protected java.util.Iterator createEntrySetIterator()

Creates an entry set iterator. Subclasses can override this to return iterators with different properties.

Returns:

the entrySet iterator

keySet

public java.util.Set keySet()

Gets the keySet view of the map. Changes made to the view affect this map. To simply iterate through the keys, use mapIterator().

Specified by:

keySet in interface java.util.Map

Overrides:

keySet in class java.util.AbstractMap

Returns:

the keySet view

createKeySetIterator

protected java.util.Iterator createKeySetIterator()

Creates a key set iterator. Subclasses can override this to return iterators with different properties.

Returns:

the keySet iterator

values

public java.util.Collection values()

Gets the values view of the map. Changes made to the view affect this map. To simply iterate through the values, use mapIterator().

Specified by:

values in interface java.util.Map

Overrides:

values in class java.util.AbstractMap

Returns:

the values view

createValuesIterator

protected java.util.Iterator createValuesIterator()

Creates a values iterator. Subclasses can override this to return iterators with different properties.

Returns:

the values iterator

doWriteObject

protected void doWriteObject(java.io.ObjectOutputStream out)
                      throws java.io.IOException

Writes the map data to the stream. This method must be overridden if a subclass must be setup before put() is used.

Serialization is not one of the JDK's nicest topics. Normal serialization will initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the put() method on read can be affected by subclass state.

The solution adopted here is to serialize the state data of this class in this protected method. This method must be called by the writeObject() of the first serializable subclass.

Subclasses may override if they have a specific field that must be present on read before this implementation will work. Generally, the read determines what must be serialized here, if anything.

Parameters:

out - the output stream

Throws:

java.io.IOException

doReadObject

protected void doReadObject(java.io.ObjectInputStream in)
                     throws java.io.IOException,
                            java.lang.ClassNotFoundException

Reads the map data from the stream. This method must be overridden if a subclass must be setup before put() is used.

Serialization is not one of the JDK's nicest topics. Normal serialization will initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the put() method on read can be affected by subclass state.

The solution adopted here is to deserialize the state data of this class in this protected method. This method must be called by the readObject() of the first serializable subclass.

Subclasses may override if the subclass has a specific field that must be present before put() or calculateThreshold() will work correctly.

Parameters:

in - the input stream

Throws:

java.io.IOException

java.lang.ClassNotFoundException

clone

protected java.lang.Object clone()

Clones the map without cloning the keys or values.

To implement clone(), a subclass must implement the Cloneable interface and make this method public.

Overrides:

clone in class java.util.AbstractMap

Returns:

a shallow clone

equals

public boolean equals(java.lang.Object obj)

Compares this map with another.

Specified by:

equals in interface java.util.Map

Overrides:

equals in class java.util.AbstractMap

Parameters:

obj - the object to compare to

Returns:

true if equal

hashCode

public int hashCode()

Gets the standard Map hashCode.

Specified by:

hashCode in interface java.util.Map

Overrides:

hashCode in class java.util.AbstractMap

Returns:

the hash code defined in the Map interface

toString

public java.lang.String toString()

Gets the map as a String.

Overrides:

toString in class java.util.AbstractMap

Returns:

a string version of the map