| java.lang.Object
 java.util.AbstractMap
org.apache.commons.collections.map.AbstractHashedMap
All known Subclasses: org.apache.commons.collections.map.CaseInsensitiveMap, org.apache.commons.collections.map.IdentityMap, org.apache.commons.collections.map.HashedMap, org.apache.commons.collections.map.AbstractLinkedMap, org.apache.commons.collections.map.AbstractReferenceMap,
| AbstractHashedMap | | public class AbstractHashedMap extends AbstractMap implements IterableMap(Code) | | 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: 171349 $ $Date: 2005-05-22 18:48:56 +0100 (Sun, 22 May 2005) $
author:
java util HashMap
author:
Stephen Colebourne
author:
Christian Siefkes |
| Inner Class :protected static class HashMapIterator extends HashIterator implements MapIterator | |
| Inner Class :protected static class EntrySet extends AbstractSet | |
| Inner Class :protected static class EntrySetIterator extends HashIterator | |
| Inner Class :protected static class KeySet extends AbstractSet | |
| Inner Class :protected static class KeySetIterator extends EntrySetIterator | |
| Inner Class :protected static class ValuesIterator extends HashIterator | |
| Inner Class :abstract protected static class HashIterator implements Iterator | |
| Constructor Summary | |
| protected | AbstractHashedMap()
Constructor only used in deserialization, do not use otherwise. | | protected | AbstractHashedMap(int initialCapacity, float loadFactor, int threshold)
Constructor which performs no validation on the passed in parameters. | | 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(Map map)
Constructor copying elements from another map. |
| Method Summary | |
| protected void | addEntry(HashEntry entry, int hashIndex)
Adds an entry into this map. | | protected void | addMapping(int hashIndex, int hashCode, Object key, 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. | | public void | clear()
Clears the map, resetting the size to zero and nullifying references
to avoid garbage collection issues. | | protected Object | clone()
Clones the map without cloning the keys or values. | | public boolean | containsKey(Object key)
Checks whether the map contains the specified key. | | public boolean | containsValue(Object value)
Checks whether the map contains the specified value. | | protected Object | convertKey(Object key)
Converts input keys to another object for storage in the map. | | protected HashEntry | createEntry(HashEntry next, int hashCode, Object key, Object value)
Creates an entry to store the key-value data. | | protected Iterator | createEntrySetIterator()
Creates an entry set iterator. | | protected Iterator | createKeySetIterator()
Creates a key set iterator. | | protected Iterator | createValuesIterator()
Creates a values iterator. | | protected void | destroyEntry(HashEntry entry)
Kills an entry ready for the garbage collector. | | protected void | doReadObject(ObjectInputStream in)
Reads the map data from the stream. | | protected void | doWriteObject(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(HashEntry entry)
Gets the hashCode field from a HashEntry. | | protected Object | entryKey(HashEntry entry)
Gets the key field from a HashEntry. | | protected HashEntry | entryNext(HashEntry entry)
Gets the next field from a HashEntry. | | public Set | entrySet()
Gets the entrySet view of the map. | | protected Object | entryValue(HashEntry entry)
Gets the value field from a HashEntry. | | public boolean | equals(Object obj)
Compares this map with another. | | public Object | get(Object key)
Gets the value mapped to the key specified. | | protected HashEntry | getEntry(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. | | protected int | hash(Object key)
Gets the hash code for the key specified. | | public 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. | | public boolean | isEmpty()
Checks whether the map is currently empty. | | protected boolean | isEqualKey(Object key1, Object key2)
Compares two keys, in internal converted form, to see if they are equal. | | protected boolean | isEqualValue(Object value1, Object value2)
Compares two values, in external form, to see if they are equal. | | public Set | keySet()
Gets the keySet view of the map. | | 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. | | public Object | put(Object key, Object value)
Puts a key-value mapping into this map. | | public void | putAll(Map map)
Puts all the values from the specified map into this map. | | public Object | remove(Object key)
Removes the specified mapping from this map. | | protected void | removeEntry(HashEntry entry, int hashIndex, HashEntry previous)
Removes an entry from the chain stored in a particular index. | | protected void | removeMapping(HashEntry entry, int hashIndex, HashEntry previous)
Removes a mapping from the map. | | protected void | reuseEntry(HashEntry entry, int hashIndex, int hashCode, Object key, Object value)
Reuses an existing key-value mapping, storing completely new data. | | public int | size()
Gets the size of the map. | | public String | toString()
Gets the map as a String. | | protected void | updateEntry(HashEntry entry, Object newValue)
Updates an existing key-value mapping to change the value. | | public Collection | values()
Gets the values view of the map. |
| DEFAULT_CAPACITY | | final protected static int DEFAULT_CAPACITY(Code) | | The default capacity to use
|
| DEFAULT_LOAD_FACTOR | | final protected static float DEFAULT_LOAD_FACTOR(Code) | | The default load factor to use
|
| DEFAULT_THRESHOLD | | final protected static int DEFAULT_THRESHOLD(Code) | | The default threshold to use
|
| GETKEY_INVALID | | final protected static String GETKEY_INVALID(Code) | | |
| GETVALUE_INVALID | | final protected static String GETVALUE_INVALID(Code) | | |
| MAXIMUM_CAPACITY | | final protected static int MAXIMUM_CAPACITY(Code) | | The maximum capacity allowed
|
| NO_NEXT_ENTRY | | final protected static String NO_NEXT_ENTRY(Code) | | |
| NO_PREVIOUS_ENTRY | | final protected static String NO_PREVIOUS_ENTRY(Code) | | |
| NULL | | final protected static Object NULL(Code) | | An object for masking null
|
| REMOVE_INVALID | | final protected static String REMOVE_INVALID(Code) | | |
| SETVALUE_INVALID | | final protected static String SETVALUE_INVALID(Code) | | |
| data | | protected transient HashEntry[] data(Code) | | Map entries
|
| entrySet | | protected transient EntrySet entrySet(Code) | | Entry set
|
| keySet | | protected transient KeySet keySet(Code) | | Key set
|
| loadFactor | | protected transient float loadFactor(Code) | | Load factor, normally 0.75
|
| modCount | | protected transient int modCount(Code) | | Modification count for iterators
|
| size | | protected transient int size(Code) | | The size of the map
|
| threshold | | protected transient int threshold(Code) | | Size at which to rehash
|
| values | | protected transient Values values(Code) | | Values
|
| AbstractHashedMap | | protected AbstractHashedMap()(Code) | | Constructor only used in deserialization, do not use otherwise.
|
| AbstractHashedMap | | protected AbstractHashedMap(int initialCapacity, float loadFactor, int threshold)(Code) | | Constructor which performs no validation on the passed in parameters.
Parameters:
initialCapacity - the initial capacity, must be a power of two
Parameters:
loadFactor - the load factor, must be > 0.0f and generally < 1.0f
Parameters:
threshold - the threshold, must be sensible |
| AbstractHashedMap | | protected AbstractHashedMap(int initialCapacity)(Code) | | Constructs a new, empty map with the specified initial capacity and
default load factor.
Parameters:
initialCapacity - the initial capacity
throws:
IllegalArgumentException - if the initial capacity is less than one |
| AbstractHashedMap | | protected AbstractHashedMap(int initialCapacity, float loadFactor)(Code) | | Constructs a new, empty map with the specified initial capacity and
load factor.
Parameters:
initialCapacity - the initial capacity
Parameters:
loadFactor - the load factor
throws:
IllegalArgumentException - if the initial capacity is less than one
throws:
IllegalArgumentException - if the load factor is less than or equal to zero |
| AbstractHashedMap | | protected AbstractHashedMap(Map map)(Code) | | Constructor copying elements from another map.
Parameters:
map - the map to copy
throws:
NullPointerException - if the map is null |
| addEntry | | protected void addEntry(HashEntry entry, int hashIndex)(Code) | | 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
Parameters:
hashIndex - the index into the data array to store at |
| addMapping | | protected void addMapping(int hashIndex, int hashCode, Object key, Object value)(Code) | | 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
Parameters:
hashCode - the hash code of the key to add
Parameters:
key - the key to add
Parameters:
value - the value to add |
| calculateNewCapacity | | protected int calculateNewCapacity(int proposedCapacity)(Code) | | Calculates the new capacity of the map.
This implementation normalizes the capacity to a power of two.
Parameters:
proposedCapacity - the proposed capacity the normalized new capacity |
| calculateThreshold | | protected int calculateThreshold(int newCapacity, float factor)(Code) | | Calculates the new threshold of the map, where it will be resized.
This implementation uses the load factor.
Parameters:
newCapacity - the new capacity
Parameters:
factor - the load factor the new resize threshold |
| checkCapacity | | protected void checkCapacity()(Code) | | Checks the capacity of the map and enlarges it if necessary.
This implementation uses the threshold to check if the map needs enlarging
|
| clear | | public void clear()(Code) | | Clears the map, resetting the size to zero and nullifying references
to avoid garbage collection issues.
|
| clone | | protected Object clone()(Code) | | Clones the map without cloning the keys or values.
To implement clone(), a subclass must implement the
Cloneable interface and make this method public.
a shallow clone |
| containsKey | | public boolean containsKey(Object key)(Code) | | Checks whether the map contains the specified key.
Parameters:
key - the key to search for true if the map contains the key |
| containsValue | | public boolean containsValue(Object value)(Code) | | Checks whether the map contains the specified value.
Parameters:
value - the value to search for true if the map contains the value |
| convertKey | | protected Object convertKey(Object key)(Code) | | 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 the converted key |
| createEntry | | protected HashEntry createEntry(HashEntry next, int hashCode, Object key, Object value)(Code) | | 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
Parameters:
hashCode - the hash code to use
Parameters:
key - the key to store
Parameters:
value - the value to store the newly created entry |
| createEntrySetIterator | | protected Iterator createEntrySetIterator()(Code) | | Creates an entry set iterator.
Subclasses can override this to return iterators with different properties.
the entrySet iterator |
| createKeySetIterator | | protected Iterator createKeySetIterator()(Code) | | Creates a key set iterator.
Subclasses can override this to return iterators with different properties.
the keySet iterator |
| createValuesIterator | | protected Iterator createValuesIterator()(Code) | | Creates a values iterator.
Subclasses can override this to return iterators with different properties.
the values iterator |
| destroyEntry | | protected void destroyEntry(HashEntry entry)(Code) | | 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 |
| doReadObject | | protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException(Code) | | 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 |
| doWriteObject | | protected void doWriteObject(ObjectOutputStream out) throws IOException(Code) | | 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 |
| ensureCapacity | | protected void ensureCapacity(int newCapacity)(Code) | | 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) |
| entryHashCode | | protected int entryHashCode(HashEntry entry)(Code) | | 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 the hashCode field of the entry
throws:
NullPointerException - if the entry is null
since:
Commons Collections 3.1 |
| entryKey | | protected Object entryKey(HashEntry entry)(Code) | | 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 the key field of the entry
throws:
NullPointerException - if the entry is null
since:
Commons Collections 3.1 |
| entryNext | | protected HashEntry entryNext(HashEntry entry)(Code) | | 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 the next field of the entry
throws:
NullPointerException - if the entry is null
since:
Commons Collections 3.1 |
| entrySet | | public Set entrySet()(Code) | | Gets the entrySet view of the map.
Changes made to the view affect this map.
To simply iterate through the entries, use
AbstractHashedMap.mapIterator() .
the entrySet view |
| entryValue | | protected Object entryValue(HashEntry entry)(Code) | | 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 the value field of the entry
throws:
NullPointerException - if the entry is null
since:
Commons Collections 3.1 |
| equals | | public boolean equals(Object obj)(Code) | | Compares this map with another.
Parameters:
obj - the object to compare to true if equal |
| get | | public Object get(Object key)(Code) | | Gets the value mapped to the key specified.
Parameters:
key - the key the mapped value, null if no match |
| getEntry | | protected HashEntry getEntry(Object key)(Code) | | 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 the entry, null if no match |
| hash | | protected int hash(Object key)(Code) | | 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 the hash code |
| hashCode | | public int hashCode()(Code) | | Gets the standard Map hashCode.
the hash code defined in the Map interface |
| hashIndex | | protected int hashIndex(int hashCode, int dataSize)(Code) | | 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
Parameters:
dataSize - the size of the data to pick a bucket from the bucket index |
| init | | protected void init()(Code) | | Initialise subclasses during construction, cloning or deserialization.
|
| isEmpty | | public boolean isEmpty()(Code) | | Checks whether the map is currently empty.
true if the map is currently size zero |
| isEqualKey | | protected boolean isEqualKey(Object key1, Object key2)(Code) | | 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
Parameters:
key2 - the second key extracted from the entry via entry.key true if equal |
| isEqualValue | | protected boolean isEqualValue(Object value1, Object value2)(Code) | | 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
Parameters:
value2 - the second value extracted from the entry via getValue() true if equal |
| mapIterator | | public MapIterator mapIterator()(Code) | | 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.
the map iterator |
| put | | public Object put(Object key, Object value)(Code) | | Puts a key-value mapping into this map.
Parameters:
key - the key to add
Parameters:
value - the value to add the value previously mapped to this key, null if none |
| remove | | public Object remove(Object key)(Code) | | Removes the specified mapping from this map.
Parameters:
key - the mapping to remove the value mapped to the removed key, null if key not in map |
| removeEntry | | protected void removeEntry(HashEntry entry, int hashIndex, HashEntry previous)(Code) | | 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
Parameters:
hashIndex - the index into the data structure
Parameters:
previous - the previous entry in the chain |
| removeMapping | | protected void removeMapping(HashEntry entry, int hashIndex, HashEntry previous)(Code) | | 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
Parameters:
hashIndex - the index into the data structure
Parameters:
previous - the previous entry in the chain |
| reuseEntry | | protected void reuseEntry(HashEntry entry, int hashIndex, int hashCode, Object key, Object value)(Code) | | 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
Parameters:
hashIndex - the index in the data array
Parameters:
hashCode - the hash code of the key to add
Parameters:
key - the key to add
Parameters:
value - the value to add |
| size | | public int size()(Code) | | Gets the size of the map.
the size |
| toString | | public String toString()(Code) | | Gets the map as a String.
a string version of the map |
| updateEntry | | protected void updateEntry(HashEntry entry, Object newValue)(Code) | | 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
Parameters:
newValue - the new value to store |
|
|