Package org.apache.commons.collections4.map

# Class ReferenceIdentityMap<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>
org.apache.commons.collections4.map.ReferenceIdentityMap<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:
  `Serializable`, `Map<K,V>`, `Get<K,V>`, `IterableGet<K,V>`, `IterableMap<K,V>`, `Put<K,V>`

public class ReferenceIdentityMap<K,V> extends AbstractReferenceMap<K,V> implements Serializable
A `Map` implementation that allows mappings to be removed by the garbage collector and matches keys and values based on `==` not `equals()`.

When you construct a `ReferenceIdentityMap`, 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 default constructor uses hard keys and soft values, providing a memory-sensitive cache.

This map is similar to `ReferenceMap`. It differs in that keys and values in this class are compared using `==`.

This map will violate the detail of various Map and map view contracts. As a general rule, don't compare this map to other maps.

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

This implementation is not synchronized. You can use `Collections.synchronizedMap(java.util.Map<K, V>)` to provide synchronized access to a `ReferenceIdentityMap`. Remember that synchronization will not stop the garbage collector removing entries.

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

Note that ReferenceIdentityMap is not synchronized and is not thread-safe. If you wish to use this map from multiple threads concurrently, you must use appropriate synchronization. The simplest approach is to wrap this map using `Collections.synchronizedMap(java.util.Map<K, V>)`. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since:
  3.0 (previously in main package v2.1)
See Also:
  - `Reference`
  - Serialized Form

- ## Nested Class Summary

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

  `AbstractReferenceMap.ReferenceEntry<K,V>, AbstractReferenceMap.ReferenceStrength`

  ## 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,V>, AbstractMap.SimpleImmutableEntry<K,V>`

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

  `Map.Entry<K,V>`

- ## 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
  Constructor
  Description
  `ReferenceIdentityMap()`
  Constructs a new `ReferenceIdentityMap` that will use hard references to keys and soft references to values.
  `ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType)`
  Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
  `ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, boolean purgeValues)`
  Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
  `ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor)`
  Constructs a new `ReferenceIdentityMap` with the specified reference types, load factor and initial capacity.
  `ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)`
  Constructs a new `ReferenceIdentityMap` with the specified reference types, load factor and initial capacity.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected int`
  `hash(Object key)`
  Gets the hash code for the key specified.
  `protected int`
  `hashEntry(Object key, Object value)`
  Gets the hash code for a MapEntry.
  `protected boolean`
  `isEqualKey(Object key1, Object key2)`
  Compares two keys for equals.
  `protected boolean`
  `isEqualValue(Object value1, Object value2)`
  Compares two values for equals.

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

  `clear, containsKey, containsValue, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, doReadObject, doWriteObject, entrySet, get, getEntry, init, isEmpty, isKeyType, isValueType, keySet, mapIterator, purge, purge, purgeBeforeRead, purgeBeforeWrite, put, remove, size, 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, hashCode, hashIndex, 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

  - ### ReferenceIdentityMap

    public ReferenceIdentityMap()
    Constructs a new `ReferenceIdentityMap` that will use hard references to keys and soft references to values.

  - ### ReferenceIdentityMap

    public ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType)
    Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
    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`

  - ### ReferenceIdentityMap

    public ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, boolean purgeValues)
    Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
    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`
      `purgeValues` - should the value be automatically purged when the key is garbage collected

  - ### ReferenceIdentityMap

    public ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor)
    Constructs a new `ReferenceIdentityMap` 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

  - ### ReferenceIdentityMap

    public ReferenceIdentityMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)
    Constructs a new `ReferenceIdentityMap` 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

  - ### hash

    protected int hash(Object key)
    Gets the hash code for the key specified.

    This implementation uses the identity hash code.

    Overrides:
      `hash` in class `AbstractHashedMap<K,V>`
    Parameters:
      `key` - the key to get a hash code for
    Returns:
      the hash code

  - ### hashEntry

    protected int hashEntry(Object key, Object value)
    Gets the hash code for a MapEntry.

    This implementation uses the identity hash code.

    Overrides:
      `hashEntry` in class `AbstractReferenceMap<K,V>`
    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 for equals.

    This implementation converts the key from the entry to a real reference before comparison and uses `==`.

    Overrides:
      `isEqualKey` in class `AbstractReferenceMap<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 by identity

  - ### isEqualValue

    protected boolean isEqualValue(Object value1, Object value2)
    Compares two values for equals.

    This implementation uses `==`.

    Overrides:
      `isEqualValue` in class `AbstractHashedMap<K,V>`
    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 by identity