org.apache.commons.collections4.map
Class ReferenceMap<K,V>

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by org.apache.commons.collections4.map.AbstractHashedMap<K,V>
          extended by org.apache.commons.collections4.map.AbstractReferenceMap<K,V>
              extended by org.apache.commons.collections4.map.ReferenceMap<K,V>
All Implemented Interfaces:
Serializable, Map<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, Put<K,V>

public class ReferenceMap<K,V>
extends AbstractReferenceMap<K,V>
implements Serializable

A Map implementation that allows mappings to be removed by the garbage collector.

When you construct a ReferenceMap, 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 is similar to ReferenceIdentityMap. It differs in that keys and values in this class are compared using equals().

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

NOTE: As from Commons Collections 3.1 this map extends AbstractReferenceMap (previously it extended AbstractMap). As a result, the implementation is now extensible and provides a MapIterator.

Since:
3.0 (previously in main package v2.1)
Version:
$Id: ReferenceMap.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 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
ReferenceMap()
          Constructs a new ReferenceMap that will use hard references to keys and soft references to values.
ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType)
          Constructs a new ReferenceMap that will use the specified types of references.
ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, boolean purgeValues)
          Constructs a new ReferenceMap that will use the specified types of references.
ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor)
          Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)
          Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
 
Method Summary
 
Methods inherited from class org.apache.commons.collections4.map.AbstractReferenceMap
clear, containsKey, containsValue, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, doReadObject, doWriteObject, entrySet, get, getEntry, hashEntry, init, isEmpty, isEqualKey, 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, hash, hashCode, hashIndex, isEqualValue, putAll, removeEntry, removeMapping, reuseEntry, toString, updateEntry
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ReferenceMap

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


ReferenceMap

public ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType,
                    AbstractReferenceMap.ReferenceStrength valueType)
Constructs a new ReferenceMap 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

ReferenceMap

public ReferenceMap(AbstractReferenceMap.ReferenceStrength keyType,
                    AbstractReferenceMap.ReferenceStrength valueType,
                    boolean purgeValues)
Constructs a new ReferenceMap 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

ReferenceMap

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

ReferenceMap

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


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