org.apache.commons.collections4.map

Class AbstractReferenceMap<K,V>

  • All Implemented Interfaces:
    Map<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, Put<K,V>
    Direct Known Subclasses:
    ReferenceIdentityMap, ReferenceMap 

    public abstract class AbstractReferenceMap<K,V>
extends AbstractHashedMap<K,V>
    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:
    3.1 (extracted from ReferenceMap in 3.0)
    See Also:
    Reference

    • Constructor Detail

      • AbstractReferenceMap

        protected AbstractReferenceMap()
        Constructor used during deserialization.

    • Method Detail

      • init

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

      • get

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

      • put

        public V put(K key,
             V value)
        Puts a key-value mapping into this map. Neither the key nor the value may be null.
        Specified by:
        put in interface  Map<K,V>
        Specified by:
        put in interface  Put<K,V>
        Overrides:
        put in class  AbstractHashedMap<K,V>
        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
        See Also:
        Map.put(Object, Object)

      • remove

        public V remove(Object key)
        Removes the specified mapping from this map.
        Specified by:
        remove in interface  Map<K,V>
        Specified by:
        remove in interface  Get<K,V>
        Overrides:
        remove in class  AbstractHashedMap<K,V>
        Parameters:
        key - the mapping to remove
        Returns:
        the value mapped to the removed key, null if key not in map
        See Also:
        Map.remove(Object)

      • entrySet

        public Set<Map.Entry<K,V>> 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<K,V>
        Specified by:
        entrySet in interface  Get<K,V>
        Overrides:
        entrySet in class  AbstractHashedMap<K,V>
        Returns:
        a set view of this map's entries
        See Also:
        Map.entrySet()

      • 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

      • 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<K,V>
        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

      • 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<K,V>
        Parameters:
        out - the output stream
        Throws:
        IOException - if an error occurs while writing to the stream

      • doReadObject

        protected void doReadObject(ObjectInputStream in)
                     throws IOException,
                            ClassNotFoundException
        Replaces the superclass 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<K,V>
        Parameters:
        in - the input stream
        Throws:
        IOException - if an error occurs while reading from the stream
        ClassNotFoundException - if an object read from the stream can not be loaded

      • isKeyType

        protected boolean isKeyType(AbstractReferenceMap.ReferenceStrength type)
        Provided protected read-only access to the key type.
        Parameters:
        type - the type to check against.
        Returns:
        true if keyType has the specified type