Class AbstractHashedMap<K,V>
- Type Parameters:
K- the type of the keys in this mapV- the type of the values in this map
- All Implemented Interfaces:
Map<K,,V> Get<K,,V> IterableGet<K,,V> IterableMap<K,,V> Put<K,V>
- Direct Known Subclasses:
AbstractLinkedMap,AbstractReferenceMap,CaseInsensitiveMap,HashedMap
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 behavior, 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 v5.0.
- Since:
- 3.0
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static classEntrySet implementation.protected static classEntrySet iterator.protected static classHashEntry used to store the data.protected static classBase Iterator.protected static classMapIterator implementation.protected static classKeySet implementation.protected static classKeySet iterator.protected static classValues implementation.protected static classValues iterator.Nested classes/interfaces inherited from class java.util.AbstractMap
AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K, V> -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected static final intThe default capacity to useprotected static final floatThe default load factor to useprotected static final intThe default threshold to useprotected static final StringException message.protected static final StringException message.protected static final intThe maximum capacity allowedprotected static final StringException message.protected static final StringException message.protected static final ObjectAn object for masking nullprotected static final StringException message.protected static final StringException message. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedConstructor only used in deserialization, do not use otherwise.protectedAbstractHashedMap(int initialCapacity) Constructs a new, empty map with the specified initial capacity and default load factor.protectedAbstractHashedMap(int initialCapacity, float loadFactor) Constructs a new, empty map with the specified initial capacity and load factor.protectedAbstractHashedMap(int initialCapacity, float loadFactor, int threshold) Constructor which performs no validation on the passed in parameters.protectedAbstractHashedMap(Map<? extends K, ? extends V> map) Constructor copying elements from another map. -
Method Summary
Modifier and TypeMethodDescriptionprotected voidaddEntry(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex) Adds an entry into this map.protected voidaddMapping(int hashIndex, int hashCode, K key, V value) Adds a new key-value mapping into this map.protected intcalculateNewCapacity(int proposedCapacity) Calculates the new capacity of the map.protected intcalculateThreshold(int newCapacity, float factor) Calculates the new threshold of the map, where it will be resized.protected voidChecks the capacity of the map and enlarges it if necessary.voidclear()Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues.protected AbstractHashedMap<K, V> clone()Clones the map without cloning the keys or values.booleancontainsKey(Object key) Checks whether the map contains the specified key.booleancontainsValue(Object value) Checks whether the map contains the specified value.protected ObjectconvertKey(Object key) Converts input keys to another object for storage in the map.protected AbstractHashedMap.HashEntry<K, V> createEntry(AbstractHashedMap.HashEntry<K, V> next, int hashCode, K key, V value) Creates an entry to store the key-value data.Creates an entry set iterator.Creates a key set iterator.Creates a values iterator.protected voiddestroyEntry(AbstractHashedMap.HashEntry<K, V> entry) Kills an entry ready for the garbage collector.protected voidReads the map data from the stream.protected voidWrites the map data to the stream.protected voidensureCapacity(int newCapacity) Changes the size of the data structure to the capacity proposed.protected intentryHashCode(AbstractHashedMap.HashEntry<K, V> entry) Gets thehashCodefield from aHashEntry.protected KentryKey(AbstractHashedMap.HashEntry<K, V> entry) Gets thekeyfield from aHashEntry.protected AbstractHashedMap.HashEntry<K, V> entryNext(AbstractHashedMap.HashEntry<K, V> entry) Gets thenextfield from aHashEntry.entrySet()Gets the entrySet view of the map.protected VentryValue(AbstractHashedMap.HashEntry<K, V> entry) Gets thevaluefield from aHashEntry.booleanCompares this map with another.Gets the value mapped to the key specified.protected AbstractHashedMap.HashEntry<K, V> Gets the entry mapped to the key specified.protected intGets the hash code for the key specified.inthashCode()Gets the standard Map hashCode.protected inthashIndex(int hashCode, int dataSize) Gets the index into the data storage for the hashCode specified.protected voidinit()Initialize subclasses during construction, cloning or deserialization.booleanisEmpty()Checks whether the map is currently empty.protected booleanisEqualKey(Object key1, Object key2) Compares two keys, in internal converted form, to see if they are equal.protected booleanisEqualValue(Object value1, Object value2) Compares two values, in external form, to see if they are equal.keySet()Gets the keySet view of the map.Gets an iterator over the map.Puts a key-value mapping into this map.voidPuts all the values from the specified map into this map.Removes the specified mapping from this map.protected voidremoveEntry(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, AbstractHashedMap.HashEntry<K, V> previous) Removes an entry from the chain stored in a particular index.protected voidremoveMapping(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, AbstractHashedMap.HashEntry<K, V> previous) Removes a mapping from the map.protected voidreuseEntry(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, int hashCode, K key, V value) Reuses an existing key-value mapping, storing completely new data.intsize()Gets the size of the map.toString()Gets the map as a String.protected voidupdateEntry(AbstractHashedMap.HashEntry<K, V> entry, V newValue) Updates an existing key-value mapping to change the value.values()Gets the values view of the map.Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, waitMethods inherited from interface java.util.Map
compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll
-
Field Details
-
NO_NEXT_ENTRY
-
NO_PREVIOUS_ENTRY
-
REMOVE_INVALID
-
GETKEY_INVALID
-
GETVALUE_INVALID
-
SETVALUE_INVALID
-
DEFAULT_CAPACITY
-
DEFAULT_THRESHOLD
-
DEFAULT_LOAD_FACTOR
-
MAXIMUM_CAPACITY
-
NULL
-
-
Constructor Details
-
AbstractHashedMap
protected AbstractHashedMap()Constructor only used in deserialization, do not use otherwise. -
AbstractHashedMap
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 negative
-
AbstractHashedMap
Constructs a new, empty map with the specified initial capacity and load factor.- Parameters:
initialCapacity- the initial capacityloadFactor- the load factor- Throws:
IllegalArgumentException- if the initial capacity is negativeIllegalArgumentException- if the load factor is less than or equal to zero
-
AbstractHashedMap
Constructor which performs no validation on the passed in parameters.- Parameters:
initialCapacity- the initial capacity, must be a power of twoloadFactor- the load factor, must be > 0.0f and generally < 1.0fthreshold- the threshold, must be sensible
-
AbstractHashedMap
Constructor copying elements from another map.- Parameters:
map- the map to copy- Throws:
NullPointerException- if the map is null
-
-
Method Details
-
addEntry
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 addhashIndex- the index into the data array to store at
-
addMapping
Adds a new key-value mapping into this map.This implementation calls
createEntry(),addEntry()andcheckCapacity(). It also handles changes tomodCountandsize. Subclasses could override to fully control adds to the map.- Parameters:
hashIndex- the index into the data array to store athashCode- the hash code of the key to addkey- the key to addvalue- the value to add
-
calculateNewCapacity
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
Calculates the new threshold of the map, where it will be resized. This implementation uses the load factor.- Parameters:
newCapacity- the new capacityfactor- the load factor- Returns:
- the new resize threshold
-
checkCapacity
Checks the capacity of the map and enlarges it if necessary.This implementation uses the threshold to check if the map needs enlarging
-
clear
-
clone
Clones the map without cloning the keys or values.To implement
clone(), a subclass must implement theCloneableinterface and make this method public.- Overrides:
clonein classAbstractMap<K,V> - Returns:
- a shallow clone
- Throws:
InternalError- ifAbstractMap.clone()failed
-
containsKey
Checks whether the map contains the specified key.- Specified by:
containsKeyin interfaceGet<K,V> - Specified by:
containsKeyin interfaceMap<K,V> - Overrides:
containsKeyin classAbstractMap<K,V> - Parameters:
key- the key to search for- Returns:
- true if the map contains the key
- See Also:
-
containsValue
Checks whether the map contains the specified value.- Specified by:
containsValuein interfaceGet<K,V> - Specified by:
containsValuein interfaceMap<K,V> - Overrides:
containsValuein classAbstractMap<K,V> - Parameters:
value- the value to search for- Returns:
- true if the map contains the value
- See Also:
-
convertKey
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
-
createEntry
protected AbstractHashedMap.HashEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K, V> next, int hashCode, K key, V 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 sequencehashCode- the hash code to usekey- the key to storevalue- the value to store- Returns:
- the newly created entry
-
createEntrySetIterator
Creates an entry set iterator. Subclasses can override this to return iterators with different properties.- Returns:
- the entrySet iterator
-
createKeySetIterator
Creates a key set iterator. Subclasses can override this to return iterators with different properties.- Returns:
- the keySet iterator
-
createValuesIterator
Creates a values iterator. Subclasses can override this to return iterators with different properties.- Returns:
- the values iterator
-
destroyEntry
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
Reads the map data from the stream. This method must be overridden if a subclass must be setup beforeput()is used.Serialization is not one of the JDK's nicest topics. Normal serialization will initialize 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()orcalculateThreshold()will work correctly.- Parameters:
in- the input stream- Throws:
IOException- if an error occurs while reading from the streamClassNotFoundException- if an object read from the stream cannot be loaded
-
doWriteObject
Writes the map data to the stream. This method must be overridden if a subclass must be setup beforeput()is used.Serialization is not one of the JDK's nicest topics. Normal serialization will initialize 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:
IOException- if an error occurs while writing to the stream
-
ensureCapacity
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
Gets thehashCodefield from aHashEntry. Used in subclasses that have no visibility of the field.- Parameters:
entry- the entry to query, must not be null- Returns:
- the
hashCodefield of the entry - Throws:
NullPointerException- if the entry is null- Since:
- 3.1
-
entryKey
Gets thekeyfield from aHashEntry. Used in subclasses that have no visibility of the field.- Parameters:
entry- the entry to query, must not be null- Returns:
- the
keyfield of the entry - Throws:
NullPointerException- if the entry is null- Since:
- 3.1
-
entryNext
Gets thenextfield from aHashEntry. Used in subclasses that have no visibility of the field.- Parameters:
entry- the entry to query, must not be null- Returns:
- the
nextfield of the entry - Throws:
NullPointerException- if the entry is null- Since:
- 3.1
-
entrySet
Gets the entrySet view of the map. Changes made to the view affect this map. To simply iterate through the entries, usemapIterator(). -
entryValue
Gets thevaluefield from aHashEntry. Used in subclasses that have no visibility of the field.- Parameters:
entry- the entry to query, must not be null- Returns:
- the
valuefield of the entry - Throws:
NullPointerException- if the entry is null- Since:
- 3.1
-
equals
-
get
-
getEntry
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
-
hash
-
hashCode
-
hashIndex
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 usedataSize- the size of the data to pick a bucket from- Returns:
- the bucket index
-
init
Initialize subclasses during construction, cloning or deserialization. -
isEmpty
-
isEqualKey
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 outsidekey2- the second key extracted from the entry viaentry.key- Returns:
- true if equal
-
isEqualValue
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 outsidevalue2- the second value extracted from the entry viagetValue()- Returns:
- true if equal
-
keySet
Gets the keySet view of the map. Changes made to the view affect this map. To simply iterate through the keys, usemapIterator(). -
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:
mapIteratorin interfaceIterableGet<K,V> - Returns:
- the map iterator
-
put
Puts a key-value mapping into this map. -
putAll
Puts all the values from the specified map into this map.This implementation iterates around the specified map and uses
put(Object, Object). -
remove
Removes the specified mapping from this map. -
removeEntry
protected void removeEntry(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, AbstractHashedMap.HashEntry<K, V> 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 removehashIndex- the index into the data structureprevious- the previous entry in the chain
-
removeMapping
protected void removeMapping(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, AbstractHashedMap.HashEntry<K, V> previous) Removes a mapping from the map.This implementation calls
removeEntry()anddestroyEntry(). It also handles changes tomodCountandsize. Subclasses could override to fully control removals from the map.- Parameters:
entry- the entry to removehashIndex- the index into the data structureprevious- the previous entry in the chain
-
reuseEntry
protected void reuseEntry(AbstractHashedMap.HashEntry<K, V> entry, int hashIndex, int hashCode, K key, V 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 nullhashIndex- the index in the data arrayhashCode- the hash code of the key to addkey- the key to addvalue- the value to add
-
size
-
toString
-
updateEntry
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 updatenewValue- the new value to store
-
values
Gets the values view of the map. Changes made to the view affect this map. To simply iterate through the values, usemapIterator().
-