## org.apache.commons.collections.map
Class ReferenceIdentityMap

    java.lang.Object
      java.util.AbstractMap
          org.apache.commons.collections.map.AbstractHashedMap
              org.apache.commons.collections.map.AbstractReferenceMap
                  org.apache.commons.collections.map.ReferenceIdentityMap

All Implemented Interfaces:
  java.io.Serializable, java.util.Map, IterableMap

    public class ReferenceIdentityMap

extends AbstractReferenceMap
implements java.io.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)` to provide synchronized access to a `ReferenceIdentityMap`. Remember that synchronization will not stop the garbage collecter 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)`. This class may throw exceptions when accessed by concurrent threads without synchronization.

Since:
  Commons Collections 3.0 (previously in main package v2.1)
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Stephen Colebourne
See Also:
  `Reference`, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`AbstractReferenceMap.ReferenceEntry`

Nested classes/interfaces inherited from class org.apache.commons.collections.map.AbstractHashedMap
`AbstractHashedMap.EntrySet, AbstractHashedMap.EntrySetIterator, AbstractHashedMap.HashEntry, AbstractHashedMap.HashIterator, AbstractHashedMap.HashMapIterator, AbstractHashedMap.KeySet, AbstractHashedMap.KeySetIterator, AbstractHashedMap.Values, AbstractHashedMap.ValuesIterator`

Nested classes/interfaces inherited from interface java.util.Map
`java.util.Map.Entry`

Field Summary

Fields inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`HARD, keyType, purgeValues, SOFT, valueType, WEAK`

Fields inherited from class org.apache.commons.collections.map.AbstractHashedMap
`data, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, DEFAULT_THRESHOLD, entrySet, GETKEY_INVALID, GETVALUE_INVALID, keySet, loadFactor, MAXIMUM_CAPACITY, modCount, NO_NEXT_ENTRY, NO_PREVIOUS_ENTRY, NULL, REMOVE_INVALID, SETVALUE_INVALID, size, threshold, values`

Constructor Summary
`ReferenceIdentityMap()` Constructs a new `ReferenceIdentityMap` that will use hard references to keys and soft references to values.
`ReferenceIdentityMap(int keyType, int valueType)` Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
`ReferenceIdentityMap(int keyType, int valueType, boolean purgeValues)` Constructs a new `ReferenceIdentityMap` that will use the specified types of references.
`ReferenceIdentityMap(int keyType, int valueType, int capacity, float loadFactor)` Constructs a new `ReferenceIdentityMap` with the specified reference types, load factor and initial capacity.
`ReferenceIdentityMap(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)` Constructs a new `ReferenceIdentityMap` with the specified reference types, load factor and initial capacity.

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

Methods inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`clear, containsKey, containsValue, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, doReadObject, doWriteObject, entrySet, get, getEntry, init, isEmpty, keySet, mapIterator, purge, purge, purgeBeforeRead, purgeBeforeWrite, put, remove, size, values`

Methods inherited from class org.apache.commons.collections.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(int keyType,
                                int 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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`

### ReferenceIdentityMap

    public ReferenceIdentityMap(int keyType,
                                int 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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `purgeValues` - should the value be automatically purged when the key is garbage collected

### ReferenceIdentityMap

    public ReferenceIdentityMap(int keyType,
                                int 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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `capacity` - the initial capacity for the map
    `loadFactor` - the load factor for the map

### ReferenceIdentityMap

    public ReferenceIdentityMap(int keyType,
                                int 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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
    `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.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(java.lang.Object key)

  Gets the hash code for the key specified.

  This implementation uses the identity hash code.

  Overrides:
    `hash` in class `AbstractHashedMap`
  Parameters:
    `key` - the key to get a hash code for
  Returns:
    the hash code

### hashEntry

    protected int hashEntry(java.lang.Object key,
                            java.lang.Object value)

  Gets the hash code for a MapEntry.

  This implementation uses the identity hash code.

  Overrides:
    `hashEntry` in class `AbstractReferenceMap`
  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(java.lang.Object key1,
                                 java.lang.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`
  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(java.lang.Object value1,
                                   java.lang.Object value2)

  Compares two values for equals.

  This implementation uses `==`.

  Overrides:
    `isEqualValue` in class `AbstractHashedMap`
  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-2008 The Apache Software Foundation. All Rights Reserved.