org.apache.commons.collections.map

Class ReferenceIdentityMap

Implemented Interfaces:
Map, Serializable, IterableMap

public class ReferenceIdentityMap
extends AbstractReferenceMap
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 java.util.Collections.synchronizedMap 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().

Version:
$Revision: 1.1 $ $Date: 2004/04/27 21:37:32 $
Author:
Stephen Colebourne
Since:
Commons Collections 3.0 (previously in main package v2.1)
See Also:
java.lang.ref.Reference

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

Field Summary

Fields inherited from class org.apache.commons.collections.map.AbstractReferenceMap

HARD, SOFT, WEAK, keyType, purgeValues, valueType

Fields inherited from class org.apache.commons.collections.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, data, entrySet, keySet, loadFactor, modCount, 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(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.collections.map.AbstractReferenceMap

clear, containsKey, containsValue, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, doReadObject, doWriteObject, entrySet, get, getEntry, hashEntry, init, isEmpty, isEqualKey, 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, clear, clone, containsKey, containsValue, convertKey, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, destroyEntry, doReadObject, doWriteObject, ensureCapacity, entryHashCode, entryKey, entryNext, entrySet, entryValue, equals, get, getEntry, hash, hashCode, hashIndex, init, isEmpty, isEqualKey, isEqualValue, keySet, mapIterator, put, putAll, remove, removeEntry, removeMapping, reuseEntry, size, toString, updateEntry, values

Constructor Details

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.

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 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 interface AbstractHashedMap
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 interface 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(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 interface 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(Object value1,
                               Object value2)
Compares two values for equals.

This implementation uses ==.

Overrides:
isEqualValue in interface 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-2006 Apache Software Foundation. All Rights Reserved.