Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
AbstractMap
org.apache.commons.collections.map.AbstractHashedMap
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.
Nested Class Summary | |
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
protected static class |
|
Field Summary | |
protected static int |
|
protected static float |
|
protected static int |
|
protected static String | |
protected static String | |
protected static int |
|
protected static String | |
protected static String | |
protected static Object |
|
protected static String | |
protected static String | |
protected AbstractHashedMap.HashEntry[] |
|
protected AbstractHashedMap.EntrySet |
|
protected AbstractHashedMap.KeySet |
|
protected float |
|
protected int |
|
protected int |
|
protected int |
|
protected AbstractHashedMap.Values |
|
Constructor Summary | |
| |
| |
| |
| |
|
Method Summary | |
protected void |
|
protected void |
|
protected int |
|
protected int |
|
protected void |
|
void |
|
protected Object |
|
boolean |
|
boolean |
|
protected Object |
|
protected AbstractHashedMap.HashEntry |
|
protected Iterator |
|
protected Iterator |
|
protected Iterator |
|
protected void |
|
protected void |
|
protected void |
|
protected void |
|
protected int |
|
protected Object |
|
protected AbstractHashedMap.HashEntry |
|
Set |
|
protected Object |
|
boolean |
|
Object |
|
protected AbstractHashedMap.HashEntry |
|
protected int |
|
int |
|
protected int |
|
protected void |
|
boolean |
|
protected boolean |
|
protected boolean |
|
Set |
|
MapIterator |
|
Object |
|
void |
|
Object |
|
protected void |
|
protected void |
|
protected void |
|
int |
|
String |
|
protected void |
|
Collection |
|
protected static final int DEFAULT_CAPACITY
The default capacity to use
- Field Value:
- 16
protected static final float DEFAULT_LOAD_FACTOR
The default load factor to use
- Field Value:
- 0.0f
protected static final int DEFAULT_THRESHOLD
The default threshold to use
- Field Value:
- 12
protected static final String GETKEY_INVALID
protected static final String GETVALUE_INVALID
protected static final int MAXIMUM_CAPACITY
The maximum capacity allowed
- Field Value:
- 1073741824
protected static final String NO_NEXT_ENTRY
protected static final String NO_PREVIOUS_ENTRY
protected static final Object NULL
An object for masking null
protected static final String REMOVE_INVALID
protected static final String SETVALUE_INVALID
protected float loadFactor
Load factor, normally 0.75
protected int modCount
Modification count for iterators
protected int size
The size of the map
protected int threshold
Size at which to rehash
protected AbstractHashedMap()
Constructor only used in deserialization, do not use otherwise.
protected AbstractHashedMap(Map map)
Constructor copying elements from another map.
- Parameters:
map
- the map to copy
protected AbstractHashedMap(int initialCapacity)
Constructs a new, empty map with the specified initial capacity and default load factor.
- Parameters:
initialCapacity
- the initial capacity
protected AbstractHashedMap(int initialCapacity, float loadFactor)
Constructs a new, empty map with the specified initial capacity and load factor.
- Parameters:
initialCapacity
- the initial capacityloadFactor
- the load factor
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 twoloadFactor
- the load factor, must be > 0.0f and generally < 1.0fthreshold
- the threshold, must be sensible
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 addhashIndex
- the index into the data array to store at
protected void addMapping(int hashIndex, int hashCode, Object key, Object value)
Adds a new key-value mapping into this map. This implementation callscreateEntry()
,addEntry()
andcheckCapacity()
. It also handles changes tomodCount
andsize
. 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
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
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 capacityfactor
- the load factor
- Returns:
- the new resize threshold
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
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. To implementclone()
, a subclass must implement theCloneable
interface and make this method public.
- Returns:
- a shallow clone
public boolean containsKey(Object key)
Checks whether the map contains the specified key.
- Parameters:
key
- the key to search for
- Returns:
- true if the map contains the key
public boolean containsValue(Object value)
Checks whether the map contains the specified value.
- Parameters:
value
- the value to search for
- Returns:
- true if the map contains the value
protected Object convertKey(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
protected AbstractHashedMap.HashEntry createEntry(AbstractHashedMap.HashEntry next, int hashCode, Object key, 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 sequencehashCode
- the hash code to usekey
- the key to storevalue
- the value to store
- Returns:
- the newly created entry
protected Iterator createEntrySetIterator()
Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
- Returns:
- the entrySet iterator
protected Iterator createKeySetIterator()
Creates a key set iterator. Subclasses can override this to return iterators with different properties.
- Returns:
- the keySet iterator
protected Iterator createValuesIterator()
Creates a values iterator. Subclasses can override this to return iterators with different properties.
- Returns:
- the values iterator
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
protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
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 initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case theput()
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 thereadObject()
of the first serializable subclass. Subclasses may override if the subclass has a specific field that must be present beforeput()
orcalculateThreshold()
will work correctly.
- Parameters:
in
- the input stream
protected void doWriteObject(ObjectOutputStream out) throws IOException
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 initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case theput()
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 thewriteObject()
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
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)
protected int entryHashCode(AbstractHashedMap.HashEntry entry)
Gets thehashCode
field from aHashEntry
. 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
- Since:
- Commons Collections 3.1
protected Object entryKey(AbstractHashedMap.HashEntry entry)
Gets thekey
field from aHashEntry
. 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
- Since:
- Commons Collections 3.1
protected AbstractHashedMap.HashEntry entryNext(AbstractHashedMap.HashEntry entry)
Gets thenext
field from aHashEntry
. 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
- Since:
- Commons Collections 3.1
public Set entrySet()
Gets the entrySet view of the map. Changes made to the view affect this map. To simply iterate through the entries, usemapIterator()
.
- Returns:
- the entrySet view
protected Object entryValue(AbstractHashedMap.HashEntry entry)
Gets thevalue
field from aHashEntry
. 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
- Since:
- Commons Collections 3.1
public boolean equals(Object obj)
Compares this map with another.
- Parameters:
obj
- the object to compare to
- Returns:
- true if equal
public Object get(Object key)
Gets the value mapped to the key specified.
- Parameters:
key
- the key
- Returns:
- the mapped value, null if no match
protected AbstractHashedMap.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. 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
protected int hash(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
public int hashCode()
Gets the standard Map hashCode.
- Returns:
- the hash code defined in the Map interface
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 usedataSize
- the size of the data to pick a bucket from
- Returns:
- the bucket index
protected void init()
Initialise subclasses during construction, cloning or deserialization.
public boolean isEmpty()
Checks whether the map is currently empty.
- Returns:
- true if the map is currently size zero
protected boolean isEqualKey(Object key1, 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 outsidekey2
- the second key extracted from the entry viaentry.key
- Returns:
- true if equal
protected boolean isEqualValue(Object value1, 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 outsidevalue2
- the second value extracted from the entry viagetValue()
- Returns:
- true if equal
public Set keySet()
Gets the keySet view of the map. Changes made to the view affect this map. To simply iterate through the keys, usemapIterator()
.
- Returns:
- the keySet view
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
public Object put(Object key, Object value)
Puts a key-value mapping into this map.
- Parameters:
key
- the key to addvalue
- the value to add
- Returns:
- the value previously mapped to this key, null if none
public void putAll(Map map)
Puts all the values from the specified map into this map. This implementation iterates around the specified map and usesput(Object,Object)
.
- Parameters:
map
- the map to add
public Object remove(Object key)
Removes the specified mapping from this map.
- Parameters:
key
- the mapping to remove
- Returns:
- the value mapped to the removed key, null if key not in map
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 removehashIndex
- the index into the data structureprevious
- the previous entry in the chain
protected void removeMapping(AbstractHashedMap.HashEntry entry, int hashIndex, AbstractHashedMap.HashEntry previous)
Removes a mapping from the map. This implementation callsremoveEntry()
anddestroyEntry()
. It also handles changes tomodCount
andsize
. 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
protected void reuseEntry(AbstractHashedMap.HashEntry entry, int hashIndex, int hashCode, Object key, 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 nullhashIndex
- the index in the data arrayhashCode
- the hash code of the key to addkey
- the key to addvalue
- the value to add
public int size()
Gets the size of the map.
- Returns:
- the size
public String toString()
Gets the map as a String.
- Returns:
- a string version of the map
protected void updateEntry(AbstractHashedMap.HashEntry entry, Object newValue)
Updates an existing key-value mapping to change the value. This implementation callssetValue()
on the entry. Subclasses could override to handle changes to the map.
- Parameters:
entry
- the entry to updatenewValue
- the new value to store
public Collection values()
Gets the values view of the map. Changes made to the view affect this map. To simply iterate through the values, usemapIterator()
.
- Returns:
- the values view