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>

- 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)
  Version:
    $Id: ReferenceIdentityMap.java 1477799 2013-04-30 19:56:11Z tn $
  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 and 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

    Methods
    Modifier and Type | Method and 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, 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`

- - ### Constructor Detail

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

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

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.