public class

ReferenceMap

extends AbstractMap<K, V>
java.lang.Object
   ↳ java.util.AbstractMap<K, V>
     ↳ org.apache.commons.collections.ReferenceMap

This class is deprecated.
Moved to map subpackage. Due to be removed in v4.0.

Class Overview

Hash-based 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.

The algorithms used are basically the same as those in java.util.HashMap. In particular, you can specify a load factor and capacity to suit your needs. All optional Map operations are supported.

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

As usual, this implementation is not synchronized. You can use synchronizedMap(Map) to provide synchronized access to a ReferenceMap.

See Also
  • java.lang.ref.Reference

Summary

Constants
int HARD Constant indicating that hard references should be used.
int SOFT Constant indicating that soft references should be used.
int WEAK Constant indicating that weak references should be used.
Public Constructors
ReferenceMap()
Constructs a new ReferenceMap that will use hard references to keys and soft references to values.
ReferenceMap(int keyType, int valueType, boolean purgeValues)
Constructs a new ReferenceMap that will use the specified types of references.
ReferenceMap(int keyType, int valueType)
Constructs a new ReferenceMap that will use the specified types of references.
ReferenceMap(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)
Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
ReferenceMap(int keyType, int valueType, int capacity, float loadFactor)
Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
Public Methods
void clear()
Clears this map.
boolean containsKey(Object key)
Returns true if this map contains the given key.
Set entrySet()
Returns a set view of this map's entries.
Object get(Object key)
Returns the value associated with the given key, if any.
boolean isEmpty()
Returns true if this map is empty.
Set keySet()
Returns a set view of this map's keys.
Object put(Object key, Object value)
Associates the given key with the given value.
Object remove(Object key)
Removes the key and its associated value from this map.
int size()
Returns the size of this map.
Collection values()
Returns a collection view of this map's values.
[Expand]
Inherited Methods
From class java.util.AbstractMap
From class java.lang.Object
From interface java.util.Map

Constants

public static final int HARD

Constant indicating that hard references should be used.

Constant Value: 0 (0x00000000)

public static final int SOFT

Constant indicating that soft references should be used.

Constant Value: 1 (0x00000001)

public static final int WEAK

Constant indicating that weak references should be used.

Constant Value: 2 (0x00000002)

Public Constructors

public ReferenceMap ()

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

public ReferenceMap (int keyType, int 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

public ReferenceMap (int keyType, int 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

public ReferenceMap (int keyType, int 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

public ReferenceMap (int keyType, int 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

Public Methods

public void clear ()

Clears this map.

public boolean containsKey (Object key)

Returns true if this map contains the given key.

Returns
  • true if the given key is in this map

public Set entrySet ()

Returns a set view of this map's entries.

Returns
  • a set view of this map's entries

public Object get (Object key)

Returns the value associated with the given key, if any.

Returns
  • the value associated with the given key, or null if the key maps to no value

public boolean isEmpty ()

Returns true if this map is empty.

Returns
  • true if this map is empty

public Set keySet ()

Returns a set view of this map's keys.

Returns
  • a set view of this map's keys

public Object put (Object key, Object value)

Associates the given key with the given value.

Neither the key nor the value may be null.

Parameters
key the key of the mapping
value the value of the mapping
Returns
  • the last value associated with that key, or null if no value was associated with the key
Throws
NullPointerException if either the key or value is null

public Object remove (Object key)

Removes the key and its associated value from this map.

Parameters
key the key to remove
Returns
  • the value associated with that key, or null if the key was not in the map

public int size ()

Returns the size of this map.

Returns
  • the size of this map

public Collection values ()

Returns a collection view of this map's values.

Returns
  • a collection view of this map's values.