org.apache.commons.collections.map

Class AbstractReferenceMap

java.lang.Object

java.util.AbstractMap

org.apache.commons.collections.map.AbstractHashedMap

org.apache.commons.collections.map.AbstractReferenceMap

All Implemented Interfaces:

java.util.Map, IterableMap

Direct Known Subclasses:

ReferenceIdentityMap, ReferenceMap

public abstract class AbstractReferenceMap
extends AbstractHashedMap

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 Collections.synchronizedMap(java.util.Map<K, V>) to provide synchronized access to a ReferenceMap.

Since:

Commons Collections 3.1 (extracted from ReferenceMap in 3.0)

See Also:

Reference

Nested Class Summary

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K,V>, java.util.AbstractMap.SimpleImmutableEntry<K,V>

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
static int	HARD Constant indicating that hard references should be used
static int	SOFT Constant indicating that soft references should be used
static int	WEAK Constant indicating that weak references should be used

Method Summary

Modifier and Type	Method and Description
void	clear() Clears this map.
boolean	containsKey(java.lang.Object key) Checks whether the map contains the specified key.
boolean	containsValue(java.lang.Object value) Checks whether the map contains the specified value.
java.util.Set	entrySet() Returns a set view of this map's entries.
java.lang.Object	get(java.lang.Object key) Gets the value mapped to the key specified.
boolean	isEmpty() Checks whether the map is currently empty.
java.util.Set	keySet() Returns a set view of this map's keys.
MapIterator	mapIterator() Gets a MapIterator over the reference map.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Puts a key-value mapping into this map.
java.lang.Object	remove(java.lang.Object key) Removes the specified mapping from this map.
int	size() Gets the size of the map.
java.util.Collection	values() Returns a collection view of this map's values.

Methods inherited from class org.apache.commons.collections.map.AbstractHashedMap

equals, hashCode, putAll, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Field Detail

HARD

public static final int HARD

Constant indicating that hard references should be used

See Also:

Constant Field Values

SOFT

public static final int SOFT

Constant indicating that soft references should be used

See Also:

Constant Field Values

WEAK

public static final int WEAK

Constant indicating that weak references should be used

See Also:

Constant Field Values

Method Detail

size

public int size()

Gets the size of the map.

Specified by:

size in interface java.util.Map

Overrides:

size in class AbstractHashedMap

Returns:

the size

isEmpty

public boolean isEmpty()

Checks whether the map is currently empty.

Specified by:

isEmpty in interface java.util.Map

Overrides:

isEmpty in class AbstractHashedMap

Returns:

true if the map is currently size zero

containsKey

public boolean containsKey(java.lang.Object key)

Checks whether the map contains the specified key.

Specified by:

containsKey in interface java.util.Map

Overrides:

containsKey in class AbstractHashedMap

Parameters:

key - the key to search for

Returns:

true if the map contains the key

containsValue

public boolean containsValue(java.lang.Object value)

Checks whether the map contains the specified value.

Specified by:

containsValue in interface java.util.Map

Overrides:

containsValue in class AbstractHashedMap

Parameters:

value - the value to search for

Returns:

true if the map contains the value

get

public java.lang.Object get(java.lang.Object key)

Gets the value mapped to the key specified.

Specified by:

get in interface java.util.Map

Overrides:

get in class AbstractHashedMap

Parameters:

key - the key

Returns:

the mapped value, null if no match

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

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

Specified by:

put in interface java.util.Map

Overrides:

put in class AbstractHashedMap

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:

java.lang.NullPointerException - if either the key or value is null

remove

public java.lang.Object remove(java.lang.Object key)

Removes the specified mapping from this map.

Specified by:

remove in interface java.util.Map

Overrides:

remove in class AbstractHashedMap

Parameters:

key - the mapping to remove

Returns:

the value mapped to the removed key, null if key not in map

clear

public void clear()

Clears this map.

Specified by:

clear in interface java.util.Map

Overrides:

clear in class AbstractHashedMap

mapIterator

public MapIterator mapIterator()

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

Specified by:

mapIterator in interface IterableMap

Overrides:

mapIterator in class AbstractHashedMap

Returns:

a map iterator

entrySet

public java.util.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.

Specified by:

entrySet in interface java.util.Map

Overrides:

entrySet in class AbstractHashedMap

Returns:

a set view of this map's entries

keySet

public java.util.Set keySet()

Returns a set view of this map's keys.

Specified by:

keySet in interface java.util.Map

Overrides:

keySet in class AbstractHashedMap

Returns:

a set view of this map's keys

values

public java.util.Collection values()

Returns a collection view of this map's values.

Specified by:

values in interface java.util.Map

Overrides:

values in class AbstractHashedMap

Returns:

a set view of this map's values