public abstract class

AbstractReferenceMap

extends AbstractHashedMap
java.lang.Object
   ↳ java.util.AbstractMap<K, V>
     ↳ org.apache.commons.collections.map.AbstractHashedMap
       ↳ org.apache.commons.collections.map.AbstractReferenceMap
Known Direct Subclasses

Class Overview

An abstract implementation of a hash-based map that allows the entries to be removed by the garbage collector.

This class implements all the features necessary for a subclass reference hash-based map. Key-value entries are stored in instances of the ReferenceEntry class which can be overridden and replaced. The iterators can similarly be replaced, without the need to replace the KeySet, EntrySet and Values view classes.

Overridable methods are provided to change the default hashing behaviour, and to change how entries are added to and removed from the map. Hopefully, all you need for unusual subclasses is here.

When you construct an AbstractReferenceMap, 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 implementation does not allow null elements. Attempting to add a null key or value to the map will raise a NullPointerException.

All the available iterators can be reset back to the start by casting to ResettableIterator and calling reset().

This implementation is not synchronized. You can use synchronizedMap(Map) to provide synchronized access to a ReferenceMap.

See Also
  • java.lang.ref.Reference

Summary

Nested Classes
class AbstractReferenceMap.ReferenceEntry A MapEntry implementation for the map. 
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
[Expand]
Inherited Constants
From class org.apache.commons.collections.map.AbstractHashedMap
Fields
protected int keyType The reference type for keys.
protected boolean purgeValues Should the value be automatically purged when the associated key has been collected?
protected int valueType The reference type for values.
[Expand]
Inherited Fields
From class org.apache.commons.collections.map.AbstractHashedMap
Protected Constructors
AbstractReferenceMap()
Constructor used during deserialization.
AbstractReferenceMap(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)
Constructs a new empty map with the specified reference types, load factor and initial capacity.
Public Methods
void clear()
Clears this map.
boolean containsKey(Object key)
Checks whether the map contains the specified key.
boolean containsValue(Object value)
Checks whether the map contains the specified value.
Set entrySet()
Returns a set view of this map's entries.
Object get(Object key)
Gets the value mapped to the key specified.
boolean isEmpty()
Checks whether the map is currently empty.
Set keySet()
Returns a set view of this map's keys.
MapIterator mapIterator()
Gets a MapIterator over the reference map.
Object put(Object key, Object value)
Puts a key-value mapping into this map.
Object remove(Object key)
Removes the specified mapping from this map.
int size()
Gets the size of the map.
Collection values()
Returns a collection view of this map's values.
Protected Methods
AbstractHashedMap.HashEntry createEntry(AbstractHashedMap.HashEntry next, int hashCode, Object key, Object value)
Creates a ReferenceEntry instead of a HashEntry.
Iterator createEntrySetIterator()
Creates an entry set iterator.
Iterator createKeySetIterator()
Creates an key set iterator.
Iterator createValuesIterator()
Creates an values iterator.
void doReadObject(ObjectInputStream in)
Replaces the superclassm method to read the state of this class.
void doWriteObject(ObjectOutputStream out)
Replaces the superclass method to store the state of this class.
AbstractHashedMap.HashEntry getEntry(Object key)
Gets the entry mapped to the key specified.
int hashEntry(Object key, Object value)
Gets the hash code for a MapEntry.
void init()
Initialise this subclass during construction, cloning or deserialization.
boolean isEqualKey(Object key1, Object key2)
Compares two keys, in internal converted form, to see if they are equal.
void purge()
Purges stale mappings from this map.
void purge(Reference ref)
Purges the specified reference.
void purgeBeforeRead()
Purges stale mappings from this map before read operations.
void purgeBeforeWrite()
Purges stale mappings from this map before write operations.
[Expand]
Inherited Methods
From class org.apache.commons.collections.map.AbstractHashedMap
From class java.util.AbstractMap
From class java.lang.Object
From interface java.util.Map
From interface org.apache.commons.collections.IterableMap

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)

Fields

protected int keyType

The reference type for keys. Must be HARD, SOFT, WEAK.

protected boolean purgeValues

Should the value be automatically purged when the associated key has been collected?

protected int valueType

The reference type for values. Must be HARD, SOFT, WEAK.

Protected Constructors

protected AbstractReferenceMap ()

Constructor used during deserialization.

protected AbstractReferenceMap (int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)

Constructs a new empty map 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 Methods

public void clear ()

Clears this map.

public boolean containsKey (Object key)

Checks whether the map contains the specified key.

Parameters
key the key to search for
Returns
  • true if the map contains the key

public boolean containsValue (Object value)

Checks whether the map contains the specified value.

Parameters
value the value to search for
Returns
  • true if the map contains the value

public Set entrySet ()

Returns a set view of this map's entries. An iterator returned entry is valid until next() is called again. The setValue() method on the toArray entries has no effect.

Returns
  • a set view of this map's entries

public Object get (Object key)

Gets the value mapped to the key specified.

Parameters
key the key
Returns
  • the mapped value, null if no match

public boolean isEmpty ()

Checks whether the map is currently empty.

Returns
  • true if the map is currently size zero

public Set keySet ()

Returns a set view of this map's keys.

Returns
  • a set view of this map's keys

public MapIterator mapIterator ()

Gets a MapIterator over the reference map. The iterator only returns valid key/value pairs.

Returns
  • a map iterator

public Object put (Object key, Object value)

Puts a key-value mapping into this map. Neither the key nor the value may be null.

Parameters
key the key to add, must not be null
value the value to add, must not be null
Returns
  • the value previously mapped to this key, null if none
Throws
NullPointerException if either the key or value is null

public Object remove (Object key)

Removes the specified mapping from this map.

Parameters
key the mapping to remove
Returns
  • the value mapped to the removed key, null if key not in map

public int size ()

Gets the size of the map.

Returns
  • the size

public Collection values ()

Returns a collection view of this map's values.

Returns
  • a set view of this map's values

Protected Methods

protected AbstractHashedMap.HashEntry createEntry (AbstractHashedMap.HashEntry next, int hashCode, Object key, Object value)

Creates a ReferenceEntry instead of a HashEntry.

Parameters
next the next entry in sequence
hashCode the hash code to use
key the key to store
value the value to store
Returns
  • the newly created entry

protected Iterator createEntrySetIterator ()

Creates an entry set iterator.

Returns
  • the entrySet iterator

protected Iterator createKeySetIterator ()

Creates an key set iterator.

Returns
  • the keySet iterator

protected Iterator createValuesIterator ()

Creates an values iterator.

Returns
  • the values iterator

protected void doReadObject (ObjectInputStream in)

Replaces the superclassm method to read the state of this class.

Serialization is not one of the JDK's nicest topics. Normal serialization will initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the put() method on read can be affected by subclass state.

The solution adopted here is to deserialize the state data of this class in this protected method. This method must be called by the readObject() of the first serializable subclass.

Subclasses may override if the subclass has a specific field that must be present before put() or calculateThreshold() will work correctly.

Parameters
in the input stream
Throws
IOException
ClassNotFoundException

protected void doWriteObject (ObjectOutputStream out)

Replaces the superclass method to store the state of this class.

Serialization is not one of the JDK's nicest topics. Normal serialization will initialise the superclass before the subclass. Sometimes however, this isn't what you want, as in this case the put() method on read can be affected by subclass state.

The solution adopted here is to serialize the state data of this class in this protected method. This method must be called by the writeObject() of the first serializable subclass.

Subclasses may override if they have a specific field that must be present on read before this implementation will work. Generally, the read determines what must be serialized here, if anything.

Parameters
out the output stream
Throws
IOException

protected AbstractHashedMap.HashEntry getEntry (Object key)

Gets the entry mapped to the key specified.

Parameters
key the key
Returns
  • the entry, null if no match

protected int hashEntry (Object key, Object value)

Gets the hash code for a MapEntry. Subclasses can override this, for example to use the identityHashCode.

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

protected void init ()

Initialise this subclass during construction, cloning or deserialization.

protected boolean isEqualKey (Object key1, Object key2)

Compares two keys, in internal converted form, to see if they are equal.

This implementation converts the key from the entry to a real reference before comparison.

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

protected void purge ()

Purges stale mappings from this map.

Note that this method is not synchronized! Special care must be taken if, for instance, you want stale mappings to be removed on a periodic basis by some background thread.

protected void purge (Reference ref)

Purges the specified reference.

Parameters
ref the reference to purge

protected void purgeBeforeRead ()

Purges stale mappings from this map before read operations.

This implementation calls purge() to maintain a consistent state.

protected void purgeBeforeWrite ()

Purges stale mappings from this map before write operations.

This implementation calls purge() to maintain a consistent state.