Package com.espertech.esper.common.internal.collection.apachecommons

Class AbstractHashedMap

java.lang.Object
java.util.AbstractMap
com.espertech.esper.common.internal.collection.apachecommons.AbstractHashedMap
All Implemented Interfaces:
IterableMap, Map
Direct Known Subclasses:
AbstractReferenceMap
public class AbstractHashedMap extends 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$ $Date$
Author:
java util HashMap, Stephen Colebourne, Christian Siefkes

  • Field Details

    • NO_NEXT_ENTRY

      protected static final String NO_NEXT_ENTRY
      Message.
      See Also:

    • NO_PREVIOUS_ENTRY

      protected static final String NO_PREVIOUS_ENTRY
      Message.
      See Also:

    • REMOVE_INVALID

      protected static final String REMOVE_INVALID
      Message.
      See Also:

    • GETKEY_INVALID

      protected static final String GETKEY_INVALID
      Message.
      See Also:

    • GETVALUE_INVALID

      protected static final String GETVALUE_INVALID
      Message.
      See Also:

    • SETVALUE_INVALID

      protected static final String SETVALUE_INVALID
      Message.
      See Also:

    • DEFAULT_CAPACITY

      protected static final int DEFAULT_CAPACITY
      The default capacity to use
      See Also:

    • DEFAULT_THRESHOLD

      protected static final int DEFAULT_THRESHOLD
      The default threshold to use
      See Also:

    • DEFAULT_LOAD_FACTOR

      protected static final float DEFAULT_LOAD_FACTOR
      The default load factor to use
      See Also:

    • MAXIMUM_CAPACITY

      protected static final int MAXIMUM_CAPACITY
      The maximum capacity allowed
      See Also:

    • NULL

      protected static final 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 Details

    • 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:
      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:
      IllegalArgumentException - if the initial capacity is less than one or if the load factor is less than or equal to zero

    • AbstractHashedMap

      protected AbstractHashedMap(Map map)
      Constructor copying elements from another map.
      Parameters:
      map - the map to copy
      Throws:
      NullPointerException - if the map is null

  • Method Details

    • init

      protected void init()
      Initialise subclasses during construction, cloning or deserialization.

    • get

      public Object get(Object key)
      Gets the value mapped to the key specified.
      Specified by:
      get in interface Map
      Overrides:
      get in class 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 Map
      Overrides:
      size in class AbstractMap
      Returns:
      the size

    • isEmpty

      public boolean isEmpty()
      Checks whether the map is currently empty.
      Specified by:
      isEmpty in interface Map
      Overrides:
      isEmpty in class AbstractMap
      Returns:
      true if the map is currently size zero

    • containsKey

      public boolean containsKey(Object key)
      Checks whether the map contains the specified key.
      Specified by:
      containsKey in interface Map
      Overrides:
      containsKey in class AbstractMap
      Parameters:
      key - the key to search for
      Returns:
      true if the map contains the key

    • containsValue

      public boolean containsValue(Object value)
      Checks whether the map contains the specified value.
      Specified by:
      containsValue in interface Map
      Overrides:
      containsValue in class AbstractMap
      Parameters:
      value - the value to search for
      Returns:
      true if the map contains the value

    • put

      public Object put(Object key, Object value)
      Puts a key-value mapping into this map.
      Specified by:
      put in interface Map
      Overrides:
      put in class 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(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 Map
      Overrides:
      putAll in class AbstractMap
      Parameters:
      map - the map to add
      Throws:
      NullPointerException - if the map is null

    • remove

      public Object remove(Object key)
      Removes the specified mapping from this map.
      Specified by:
      remove in interface Map
      Overrides:
      remove in class 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 Map
      Overrides:
      clear in class AbstractMap

    • convertKey

      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

    • hash

      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

    • isEqualKey

      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 outside
      key2 - the second key extracted from the entry via entry.key
      Returns:
      true if equal

    • isEqualValue

      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 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(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, 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, 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 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, Object key, 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, 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 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:
      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:
      NullPointerException - if the entry is null
      Since:
      Commons Collections 3.1

    • entryKey

      protected 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:
      NullPointerException - if the entry is null
      Since:
      Commons Collections 3.1

    • entryValue

      protected 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:
      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 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 Map
      Specified by:
      entrySet in class AbstractMap
      Returns:
      the entrySet view

    • createEntrySetIterator

      protected Iterator createEntrySetIterator()
      Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
      Returns:
      the entrySet iterator

    • keySet

      public 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 Map
      Overrides:
      keySet in class AbstractMap
      Returns:
      the keySet view

    • createKeySetIterator

      protected Iterator createKeySetIterator()
      Creates a key set iterator. Subclasses can override this to return iterators with different properties.
      Returns:
      the keySet iterator

    • values

      public 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 Map
      Overrides:
      values in class AbstractMap
      Returns:
      the values view

    • createValuesIterator

      protected Iterator createValuesIterator()
      Creates a values iterator. Subclasses can override this to return iterators with different properties.
      Returns:
      the values iterator

    • doWriteObject

      protected void doWriteObject(ObjectOutputStream outStream) throws 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:
      outStream - the output stream
      Throws:
      IOException - write error

    • doReadObject

      protected void doReadObject(ObjectInputStream input) throws IOException, 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:
      input - the input stream
      Throws:
      IOException - io error
      ClassNotFoundException - class not found

    • clone

      protected Object clone() throws CloneNotSupportedException
      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 AbstractMap
      Returns:
      a shallow clone
      Throws:
      CloneNotSupportedException

    • equals

      public boolean equals(Object obj)
      Compares this map with another.
      Specified by:
      equals in interface Map
      Overrides:
      equals in class 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 Map
      Overrides:
      hashCode in class AbstractMap
      Returns:
      the hash code defined in the Map interface

    • toString

      public String toString()
      Gets the map as a String.
      Overrides:
      toString in class AbstractMap
      Returns:
      a string version of the map