Package org.apache.commons.collections4.map

# Class AbstractReferenceMap<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
org.apache.commons.collections4.map.AbstractHashedMap<K,V>
org.apache.commons.collections4.map.AbstractReferenceMap<K,V>

Type Parameters:
  `K` - the type of the keys in this map
  `V` - 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:
  `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 behavior, 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`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractReferenceMap.ReferenceEntry<K,V>`
  A MapEntry implementation for the map.
  `static enum`
  `AbstractReferenceMap.ReferenceStrength`
  Reference type enum.

  ## Nested classes/interfaces inherited from class org.apache.commons.collections4.map.AbstractHashedMap

  `AbstractHashedMap.EntrySet<K,V>, AbstractHashedMap.EntrySetIterator<K,V>, AbstractHashedMap.HashEntry<K,V>, AbstractHashedMap.HashIterator<K,V>, AbstractHashedMap.HashMapIterator<K,V>, AbstractHashedMap.KeySet<K>, AbstractHashedMap.KeySetIterator<K>, AbstractHashedMap.Values<V>, AbstractHashedMap.ValuesIterator<V>`

  ## Nested classes/interfaces inherited from class java.util.AbstractMap

  `AbstractMap.SimpleEntry<K extends Object,V extends Object>, AbstractMap.SimpleImmutableEntry<K extends Object,V extends Object>`

  ## Nested classes/interfaces inherited from interface java.util.Map

  `Map.Entry<K extends Object,V extends Object>`

- ## Field Summary

  ### Fields inherited from class org.apache.commons.collections4.map.AbstractHashedMap

  `DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, DEFAULT_THRESHOLD, GETKEY_INVALID, GETVALUE_INVALID, MAXIMUM_CAPACITY, NO_NEXT_ENTRY, NO_PREVIOUS_ENTRY, NULL, REMOVE_INVALID, SETVALUE_INVALID`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractReferenceMap()`
  Constructor used during deserialization.
  `protected`
  `AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)`
  Constructs a new empty map with the specified reference types, load factor and initial capacity.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  Clears this map.
  `boolean`
  `containsKey(Object key)`
  Checks whether the map contains the specified key.
  `boolean`
  `containsValue(Object value)`
  Checks whether the map contains the specified value.
  `protected AbstractReferenceMap.ReferenceEntry<K,V>`
  `createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)`
  Creates a ReferenceEntry instead of a HashEntry.
  `protected Iterator<Map.Entry<K,V>>`
  `createEntrySetIterator()`
  Creates an entry set iterator.
  `protected Iterator<K>`
  `createKeySetIterator()`
  Creates a key set iterator.
  `protected Iterator<V>`
  `createValuesIterator()`
  Creates a values iterator.
  `protected void`
  `doReadObject(ObjectInputStream in)`
  Replaces the superclass method to read the state of this class.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Replaces the superclass method to store the state of this class.
  `Set<Map.Entry<K,V>>`
  `entrySet()`
  Returns a set view of this map's entries.
  `V`
  `get(Object key)`
  Gets the value mapped to the key specified.
  `protected AbstractHashedMap.HashEntry<K,V>`
  `getEntry(Object key)`
  Gets the entry mapped to the key specified.
  `protected int`
  `hashEntry(Object key, Object value)`
  Gets the hash code for a MapEntry.
  `protected void`
  `init()`
  Initialize this subclass during construction, cloning or deserialization.
  `boolean`
  `isEmpty()`
  Checks whether the map is currently empty.
  `protected boolean`
  `isEqualKey(Object key1, Object key2)`
  Compares two keys, in internal converted form, to see if they are equal.
  `protected boolean`
  `isKeyType(AbstractReferenceMap.ReferenceStrength type)`
  Provided protected read-only access to the key type.
  `protected boolean`
  `isValueType(AbstractReferenceMap.ReferenceStrength type)`
  Provided protected read-only access to the value type.
  `Set<K>`
  `keySet()`
  Returns a set view of this map's keys.
  `MapIterator<K,V>`
  `mapIterator()`
  Gets a MapIterator over the reference map.
  `protected void`
  `purge()`
  Purges stale mappings from this map.
  `protected void`
  `purge(Reference<?> ref)`
  Purges the specified reference.
  `protected void`
  `purgeBeforeRead()`
  Purges stale mappings from this map before read operations.
  `protected void`
  `purgeBeforeWrite()`
  Purges stale mappings from this map before write operations.
  `V`
  `put(K key, V value)`
  Puts a key-value mapping into this map.
  `V`
  `remove(Object key)`
  Removes the specified mapping from this map.
  `int`
  `size()`
  Gets the size of the map.
  `Collection<V>`
  `values()`
  Returns a collection view of this map's values.

  ### Methods inherited from class org.apache.commons.collections4.map.AbstractHashedMap

  `addEntry, addMapping, calculateNewCapacity, calculateThreshold, checkCapacity, clone, convertKey, destroyEntry, ensureCapacity, entryHashCode, entryKey, entryNext, entryValue, equals, hash, hashCode, hashIndex, isEqualValue, putAll, removeEntry, removeMapping, reuseEntry, toString, updateEntry`

  ### Methods inherited from class java.lang.Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.util.Map

  `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- ## Constructor Details

  - ### AbstractReferenceMap

    protected AbstractReferenceMap()
    Constructor used during deserialization.

  - ### AbstractReferenceMap

    protected AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength 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 `AbstractReferenceMap.ReferenceStrength.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

  - ### clear

    public void clear()
    Clears this map.
    Specified by:
      `clear` in interface `Map<K,V>`
    Specified by:
      `clear` in interface `Put<K,V>`
    Overrides:
      `clear` in class `AbstractHashedMap<K,V>`
    See Also:
      - `Map.clear()`

  - ### containsKey

    public boolean containsKey(Object key)
    Checks whether the map contains the specified key.
    Specified by:
      `containsKey` in interface `Get<K,V>`
    Specified by:
      `containsKey` in interface `Map<K,V>`
    Overrides:
      `containsKey` in class `AbstractHashedMap<K,V>`
    Parameters:
      `key` - the key to search for
    Returns:
      true if the map contains the key
    See Also:
      - `Map.containsKey(Object)`

  - ### containsValue

    public boolean containsValue(Object value)
    Checks whether the map contains the specified value.
    Specified by:
      `containsValue` in interface `Get<K,V>`
    Specified by:
      `containsValue` in interface `Map<K,V>`
    Overrides:
      `containsValue` in class `AbstractHashedMap<K,V>`
    Parameters:
      `value` - the value to search for
    Returns:
      true if the map contains the value
    See Also:
      - `Map.containsValue(Object)`

  - ### createEntry

    protected AbstractReferenceMap.ReferenceEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)
    Creates a ReferenceEntry instead of a HashEntry.
    Overrides:
      `createEntry` in class `AbstractHashedMap<K,V>`
    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<Map.Entry<K,V>> createEntrySetIterator()
    Creates an entry set iterator.
    Overrides:
      `createEntrySetIterator` in class `AbstractHashedMap<K,V>`
    Returns:
      the entrySet iterator

  - ### createKeySetIterator

    protected Iterator<K> createKeySetIterator()
    Creates a key set iterator.
    Overrides:
      `createKeySetIterator` in class `AbstractHashedMap<K,V>`
    Returns:
      the keySet iterator

  - ### createValuesIterator

    protected Iterator<V> createValuesIterator()
    Creates a values iterator.
    Overrides:
      `createValuesIterator` in class `AbstractHashedMap<K,V>`
    Returns:
      the values iterator

  - ### 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 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()` 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

  - ### 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 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.

    Overrides:
      `doWriteObject` in class `AbstractHashedMap<K,V>`
    Parameters:
      `out` - the output stream
    Throws:
      `IOException` - if an error occurs while writing to the stream

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

  - ### get

    public V get(Object key)
    Gets the value mapped to the key specified.
    Specified by:
      `get` in interface `Get<K,V>`
    Specified by:
      `get` in interface `Map<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)`

  - ### getEntry

    protected AbstractHashedMap.HashEntry<K,V> getEntry(Object key)
    Gets the entry mapped to the key specified.
    Overrides:
      `getEntry` in class `AbstractHashedMap<K,V>`
    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

  - ### init

    protected void init()
    Initialize this subclass during construction, cloning or deserialization.
    Overrides:
      `init` in class `AbstractHashedMap<K,V>`

  - ### isEmpty

    public boolean isEmpty()
    Checks whether the map is currently empty.
    Specified by:
      `isEmpty` in interface `Get<K,V>`
    Specified by:
      `isEmpty` in interface `Map<K,V>`
    Overrides:
      `isEmpty` in class `AbstractHashedMap<K,V>`
    Returns:
      true if the map is currently size zero
    See Also:
      - `Map.isEmpty()`

  - ### 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

  - ### 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

  - ### isValueType

    protected boolean isValueType(AbstractReferenceMap.ReferenceStrength type)
    Provided protected read-only access to the value type.
    Parameters:
      `type` - the type to check against.
    Returns:
      true if valueType has the specified type

  - ### keySet

    public Set<K> keySet()
    Returns a set view of this map's keys.
    Specified by:
      `keySet` in interface `Get<K,V>`
    Specified by:
      `keySet` in interface `Map<K,V>`
    Overrides:
      `keySet` in class `AbstractHashedMap<K,V>`
    Returns:
      a set view of this map's keys
    See Also:
      - `Map.keySet()`

  - ### mapIterator

    public MapIterator<K,V> mapIterator()
    Gets a MapIterator over the reference map. The iterator only returns valid key/value pairs.
    Specified by:
      `mapIterator` in interface `IterableGet<K,V>`
    Overrides:
      `mapIterator` in class `AbstractHashedMap<K,V>`
    Returns:
      a map iterator

  - ### 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

  - ### 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.

  - ### 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 `Get<K,V>`
    Specified by:
      `remove` in interface `Map<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)`

  - ### size

    public int size()
    Gets the size of the map.
    Specified by:
      `size` in interface `Get<K,V>`
    Specified by:
      `size` in interface `Map<K,V>`
    Overrides:
      `size` in class `AbstractHashedMap<K,V>`
    Returns:
      the size
    See Also:
      - `Map.size()`

  - ### values

    public Collection<V> values()
    Returns a collection view of this map's values.
    Specified by:
      `values` in interface `Get<K,V>`
    Specified by:
      `values` in interface `Map<K,V>`
    Overrides:
      `values` in class `AbstractHashedMap<K,V>`
    Returns:
      a set view of this map's values
    See Also:
      - `Map.values()`