ReferenceMap

Class Overview

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 synchronizedMap(Map) to provide synchronized access to a ReferenceMap. 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 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 synchronizedMap(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.

Summary

[Expand] Inherited Constants
From class org.apache.commons.collections.map.AbstractReferenceMap 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
From class org.apache.commons.collections.map.AbstractHashedMap int DEFAULT_CAPACITY The default capacity to use float DEFAULT_LOAD_FACTOR The default load factor to use int DEFAULT_THRESHOLD The default threshold to use String GETKEY_INVALID String GETVALUE_INVALID int MAXIMUM_CAPACITY The maximum capacity allowed String NO_NEXT_ENTRY String NO_PREVIOUS_ENTRY String REMOVE_INVALID String SETVALUE_INVALID

[Expand] Inherited Fields
From class org.apache.commons.collections.map.AbstractReferenceMap 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.
From class org.apache.commons.collections.map.AbstractHashedMap protected static final Object NULL An object for masking null protected HashEntry[] data Map entries protected AbstractHashedMap.EntrySet entrySet Entry set protected AbstractHashedMap.KeySet keySet Key set protected float loadFactor Load factor, normally 0.75 protected int modCount Modification count for iterators protected int size The size of the map protected int threshold Size at which to rehash protected AbstractHashedMap.Values values Values

[Expand] Inherited Methods
From class org.apache.commons.collections.map.AbstractReferenceMap 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. 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. Set entrySet() Returns a set view of this map's entries. Object get(Object key) Gets the value mapped to the key specified. 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 isEmpty() Checks whether the map is currently empty. boolean isEqualKey(Object key1, Object key2) Compares two keys, in internal converted form, to see if they are equal. Set keySet() Returns a set view of this map's keys. MapIterator mapIterator() Gets a MapIterator over the reference map. 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. 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.
From class org.apache.commons.collections.map.AbstractHashedMap void addEntry(AbstractHashedMap.HashEntry entry, int hashIndex) Adds an entry into this map. void addMapping(int hashIndex, int hashCode, Object key, Object value) Adds a new key-value mapping into this map. int calculateNewCapacity(int proposedCapacity) Calculates the new capacity of the map. int calculateThreshold(int newCapacity, float factor) Calculates the new threshold of the map, where it will be resized. void checkCapacity() Checks the capacity of the map and enlarges it if necessary. void clear() Clears the map, resetting the size to zero and nullifying references to avoid garbage collection issues. Object clone() Clones the map without cloning the keys or values. boolean containsKey(Object key) Checks whether the map contains the specified key. boolean containsValue(Object value) Checks whether the map contains the specified value. Object convertKey(Object key) Converts input keys to another object for storage in the map. AbstractHashedMap.HashEntry createEntry(AbstractHashedMap.HashEntry next, int hashCode, Object key, Object value) Creates an entry to store the key-value data. Iterator createEntrySetIterator() Creates an entry set iterator. Iterator createKeySetIterator() Creates a key set iterator. Iterator createValuesIterator() Creates a values iterator. void destroyEntry(AbstractHashedMap.HashEntry entry) Kills an entry ready for the garbage collector. void doReadObject(ObjectInputStream in) Reads the map data from the stream. void doWriteObject(ObjectOutputStream out) Writes the map data to the stream. void ensureCapacity(int newCapacity) Changes the size of the data structure to the capacity proposed. int entryHashCode(AbstractHashedMap.HashEntry entry) Gets the hashCode field from a HashEntry. Object entryKey(AbstractHashedMap.HashEntry entry) Gets the key field from a HashEntry. AbstractHashedMap.HashEntry entryNext(AbstractHashedMap.HashEntry entry) Gets the next field from a HashEntry. Set entrySet() Gets the entrySet view of the map. Object entryValue(AbstractHashedMap.HashEntry entry) Gets the value field from a HashEntry. boolean equals(Object obj) Compares this map with another. Object get(Object key) Gets the value mapped to the key specified. AbstractHashedMap.HashEntry getEntry(Object key) Gets the entry mapped to the key specified. int hash(Object key) Gets the hash code for the key specified. int hashCode() Gets the standard Map hashCode. int hashIndex(int hashCode, int dataSize) Gets the index into the data storage for the hashCode specified. void init() Initialise subclasses during construction, cloning or deserialization. boolean isEmpty() Checks whether the map is currently empty. boolean isEqualKey(Object key1, Object key2) Compares two keys, in internal converted form, to see if they are equal. boolean isEqualValue(Object value1, Object value2) Compares two values, in external form, to see if they are equal. Set keySet() Gets the keySet view of the map. MapIterator mapIterator() Gets an iterator over the map. Object put(Object key, Object value) Puts a key-value mapping into this map. void putAll(Map map) Puts all the values from the specified map into this map. Object remove(Object key) Removes the specified mapping from this map. void removeEntry(AbstractHashedMap.HashEntry entry, int hashIndex, AbstractHashedMap.HashEntry previous) Removes an entry from the chain stored in a particular index. void removeMapping(AbstractHashedMap.HashEntry entry, int hashIndex, AbstractHashedMap.HashEntry previous) Removes a mapping from the map. void reuseEntry(AbstractHashedMap.HashEntry entry, int hashIndex, int hashCode, Object key, Object value) Reuses an existing key-value mapping, storing completely new data. int size() Gets the size of the map. String toString() Gets the map as a String. void updateEntry(AbstractHashedMap.HashEntry entry, Object newValue) Updates an existing key-value mapping to change the value. Collection values() Gets the values view of the map.
From class java.util.AbstractMap void clear() Object clone() boolean containsKey(Object arg0) boolean containsValue(Object arg0) abstract Set<Entry<K, V>> entrySet() boolean equals(Object arg0) V get(Object arg0) int hashCode() boolean isEmpty() Set<K> keySet() V put(K arg0, V arg1) void putAll(Map<? extends K, ? extends V> arg0) V remove(Object arg0) int size() String toString() Collection<V> values()
From class java.lang.Object Object clone() boolean equals(Object arg0) void finalize() final Class<?> getClass() int hashCode() final void notify() final void notifyAll() String toString() final void wait() final void wait(long arg0, int arg1) final void wait(long arg0)
From interface java.util.Map abstract void clear() abstract boolean containsKey(Object arg0) abstract boolean containsValue(Object arg0) abstract Set<Entry<K, V>> entrySet() abstract boolean equals(Object arg0) abstract V get(Object arg0) abstract int hashCode() abstract boolean isEmpty() abstract Set<K> keySet() abstract V put(K arg0, V arg1) abstract void putAll(Map<? extends K, ? extends V> arg0) abstract V remove(Object arg0) abstract int size() abstract Collection<V> values()
From interface org.apache.commons.collections.IterableMap abstract MapIterator mapIterator() Obtains a MapIterator over the map.