Package org.apache.commons.collections.map

Class AbstractReferenceMap

java.lang.Object
java.util.AbstractMap
org.apache.commons.collections.map.AbstractHashedMap
org.apache.commons.collections.map.AbstractReferenceMap
All Implemented Interfaces:
Map, IterableMap
Direct Known Subclasses:
ReferenceIdentityMap, ReferenceMap
public abstract class AbstractReferenceMap extends AbstractHashedMap
An abstract implementation of a hash-based map that allows the entries to be removed by the garbage collector.

This class implements all the features necessary for a subclass reference hash-based map. Key-value entries are stored in instances of the ReferenceEntry 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.

When you construct an AbstractReferenceMap, you can specify what kind of references are used to store the map's keys and values. If non-hard references are used, then the garbage collector can remove mappings if a key or value becomes unreachable, or if the JVM's memory is running low. For information on how the different reference types behave, see Reference.

Different types of references can be specified for keys and values. The keys can be configured to be weak but the values hard, in which case this class will behave like a WeakHashMap. However, you can also specify hard keys and weak values, or any other combination. The default constructor uses hard keys and soft values, providing a memory-sensitive cache.

This Map implementation does not allow null elements. Attempting to add a null key or value to the map will raise a NullPointerException.

All the available iterators can be reset back to the start by casting to ResettableIterator and calling reset().

This implementation is not synchronized. You can use Collections.synchronizedMap(java.util.Map<K, V>) to provide synchronized access to a ReferenceMap.

Since:
Commons Collections 3.1 (extracted from ReferenceMap in 3.0)
Version:
$Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
Author:
Paul Jack, Stephen Colebourne
See Also:

  • Field Details

    • HARD

      public static final int HARD
      Constant indicating that hard references should be used
      See Also:

    • SOFT

      public static final int SOFT
      Constant indicating that soft references should be used
      See Also:

    • WEAK

      public static final int WEAK
      Constant indicating that weak references should be used
      See Also:

    • keyType

      protected int keyType
      The reference type for keys. Must be HARD, SOFT, WEAK.

    • valueType

      protected int valueType
      The reference type for values. Must be HARD, SOFT, WEAK.

    • purgeValues

      protected boolean purgeValues
      Should the value be automatically purged when the associated key has been collected?

  • Constructor Details

    • AbstractReferenceMap

      protected AbstractReferenceMap()
      Constructor used during deserialization.

    • AbstractReferenceMap

      protected AbstractReferenceMap(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)
      Constructs a new empty map with the specified reference types, load factor and initial capacity.
      Parameters:
      keyType - the type of reference to use for keys; must be HARD, SOFT, WEAK
      valueType - the type of reference to use for values; must be HARD, SOFT, WEAK
      capacity - the initial capacity for the map
      loadFactor - the load factor for the map
      purgeValues - should the value be automatically purged when the key is garbage collected

  • Method Details

    • init

      protected void init()
      Initialise this subclass during construction, cloning or deserialization.
      Overrides:
      init in class AbstractHashedMap

    • size

      public int size()
      Gets the size of the map.
      Specified by:
      size in interface Map
      Overrides:
      size in class AbstractHashedMap
      Returns:
      the size

    • isEmpty

      public boolean isEmpty()
      Checks whether the map is currently empty.
      Specified by:
      isEmpty in interface Map
      Overrides:
      isEmpty in class AbstractHashedMap
      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 AbstractHashedMap
      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 AbstractHashedMap
      Parameters:
      value - the value to search for
      Returns:
      true if the map contains the value

    • get

      public Object get(Object key)
      Gets the value mapped to the key specified.
      Specified by:
      get in interface Map
      Overrides:
      get in class AbstractHashedMap
      Parameters:
      key - the key
      Returns:
      the mapped value, null if no match

    • put

      public Object put(Object key, Object value)
      Puts a key-value mapping into this map. Neither the key nor the value may be null.
      Specified by:
      put in interface Map
      Overrides:
      put in class AbstractHashedMap
      Parameters:
      key - the key to add, must not be null
      value - the value to add, must not be null
      Returns:
      the value previously mapped to this key, null if none
      Throws:
      NullPointerException - if either the key or value 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 AbstractHashedMap
      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 this map.
      Specified by:
      clear in interface Map
      Overrides:
      clear in class AbstractHashedMap

    • mapIterator

      public MapIterator mapIterator()
      Gets a MapIterator over the reference map. The iterator only returns valid key/value pairs.
      Specified by:
      mapIterator in interface IterableMap
      Overrides:
      mapIterator in class AbstractHashedMap
      Returns:
      a map iterator

    • entrySet

      public Set entrySet()
      Returns a set view of this map's entries. An iterator returned entry is valid until next() is called again. The setValue() method on the toArray entries has no effect.
      Specified by:
      entrySet in interface Map
      Overrides:
      entrySet in class AbstractHashedMap
      Returns:
      a set view of this map's entries

    • keySet

      public Set keySet()
      Returns a set view of this map's keys.
      Specified by:
      keySet in interface Map
      Overrides:
      keySet in class AbstractHashedMap
      Returns:
      a set view of this map's keys

    • values

      public Collection values()
      Returns a collection view of this map's values.
      Specified by:
      values in interface Map
      Overrides:
      values in class AbstractHashedMap
      Returns:
      a set view of this map's values

    • purgeBeforeRead

      protected void purgeBeforeRead()
      Purges stale mappings from this map before read operations.

      This implementation calls purge() to maintain a consistent state.

    • purgeBeforeWrite

      protected void purgeBeforeWrite()
      Purges stale mappings from this map before write operations.

      This implementation calls purge() to maintain a consistent state.

    • purge

      protected void purge()
      Purges stale mappings from this map.

      Note that this method is not synchronized! Special care must be taken if, for instance, you want stale mappings to be removed on a periodic basis by some background thread.

    • purge

      protected void purge(Reference ref)
      Purges the specified reference.
      Parameters:
      ref - the reference to purge

    • getEntry

      protected AbstractHashedMap.HashEntry getEntry(Object key)
      Gets the entry mapped to the key specified.
      Overrides:
      getEntry in class AbstractHashedMap
      Parameters:
      key - the key
      Returns:
      the entry, null if no match

    • hashEntry

      protected int hashEntry(Object key, Object value)
      Gets the hash code for a MapEntry. Subclasses can override this, for example to use the identityHashCode.
      Parameters:
      key - the key to get a hash code for, may be null
      value - the value to get a hash code for, may be null
      Returns:
      the hash code, as per the MapEntry specification

    • isEqualKey

      protected boolean isEqualKey(Object key1, Object key2)
      Compares two keys, in internal converted form, to see if they are equal.

      This implementation converts the key from the entry to a real reference before comparison.

      Overrides:
      isEqualKey in class AbstractHashedMap
      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

    • createEntry

      protected AbstractHashedMap.HashEntry createEntry(AbstractHashedMap.HashEntry next, int hashCode, Object key, Object value)
      Creates a ReferenceEntry instead of a HashEntry.
      Overrides:
      createEntry in class AbstractHashedMap
      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

    • createEntrySetIterator

      protected Iterator createEntrySetIterator()
      Creates an entry set iterator.
      Overrides:
      createEntrySetIterator in class AbstractHashedMap
      Returns:
      the entrySet iterator

    • createKeySetIterator

      protected Iterator createKeySetIterator()
      Creates an key set iterator.
      Overrides:
      createKeySetIterator in class AbstractHashedMap
      Returns:
      the keySet iterator

    • createValuesIterator

      protected Iterator createValuesIterator()
      Creates an values iterator.
      Overrides:
      createValuesIterator in class AbstractHashedMap
      Returns:
      the values iterator

    • doWriteObject

      protected void doWriteObject(ObjectOutputStream out) throws IOException
      Replaces the superclass method to store the state of this class.

      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.

      Overrides:
      doWriteObject in class AbstractHashedMap
      Parameters:
      out - the output stream
      Throws:
      IOException

    • doReadObject

      protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
      Replaces the superclassm method to read the state of this class.

      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.

      Overrides:
      doReadObject in class AbstractHashedMap
      Parameters:
      in - the input stream
      Throws:
      IOException
      ClassNotFoundException