org.apache.commons.collections4.map
Class AbstractReferenceMap<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>
All Implemented Interfaces:
Map<K,V>, Get<K,V>, IterableGet<K,V>, IterableMap<K,V>, Put<K,V>
Direct Known Subclasses:
ReferenceIdentityMap, ReferenceMap

public abstract class AbstractReferenceMap<K,V>
extends AbstractHashedMap<K,V>

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

Since:
3.1 (extracted from ReferenceMap in 3.0)
Version:
$Id: AbstractReferenceMap.java 1477799 2013-04-30 19:56:11Z tn $
See Also:
Reference

Nested Class Summary
protected static class AbstractReferenceMap.ReferenceEntry<K,V>
          A MapEntry implementation for the map.
static class AbstractReferenceMap.ReferenceStrength
          Reference type enum.
 
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
protected AbstractReferenceMap()
          Constructor used during deserialization.
protected AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)
          Constructs a new empty map with the specified reference types, load factor and initial capacity.
 
Method Summary
 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.
protected  AbstractReferenceMap.ReferenceEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)
          Creates a ReferenceEntry instead of a HashEntry.
protected  Iterator<Map.Entry<K,V>> createEntrySetIterator()
          Creates an entry set iterator.
protected  Iterator<K> createKeySetIterator()
          Creates an key set iterator.
protected  Iterator<V> createValuesIterator()
          Creates an values iterator.
protected  void doReadObject(ObjectInputStream in)
          Replaces the superclass method to read the state of this class.
protected  void doWriteObject(ObjectOutputStream out)
          Replaces the superclass method to store the state of this class.
 Set<Map.Entry<K,V>> entrySet()
          Returns a set view of this map's entries.
 V get(Object key)
          Gets the value mapped to the key specified.
protected  AbstractHashedMap.HashEntry<K,V> getEntry(Object key)
          Gets the entry mapped to the key specified.
protected  int hashEntry(Object key, Object value)
          Gets the hash code for a MapEntry.
protected  void init()
          Initialise this subclass during construction, cloning or deserialization.
 boolean isEmpty()
          Checks whether the map is currently empty.
protected  boolean isEqualKey(Object key1, Object key2)
          Compares two keys, in internal converted form, to see if they are equal.
protected  boolean isKeyType(AbstractReferenceMap.ReferenceStrength type)
          Provided protected read-only access to the key type.
 Set<K> keySet()
          Returns a set view of this map's keys.
 MapIterator<K,V> mapIterator()
          Gets a MapIterator over the reference map.
protected  void purge()
          Purges stale mappings from this map.
protected  void purge(Reference<?> ref)
          Purges the specified reference.
protected  void purgeBeforeRead()
          Purges stale mappings from this map before read operations.
protected  void purgeBeforeWrite()
          Purges stale mappings from this map before write operations.
 V put(K key, V value)
          Puts a key-value mapping into this map.
 V remove(Object key)
          Removes the specified mapping from this map.
 int size()
          Gets the size of the map.
 Collection<V> values()
          Returns a collection view of this map's 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

AbstractReferenceMap

protected AbstractReferenceMap()
Constructor used during deserialization.


AbstractReferenceMap

protected AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType,
                               AbstractReferenceMap.ReferenceStrength 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 AbstractReferenceMap.ReferenceStrength.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
Method Detail

init

protected void init()
Initialise this subclass during construction, cloning or deserialization.

Overrides:
init in class AbstractHashedMap<K,V>

size

public int size()
Gets the size of the map.

Specified by:
size in interface Map<K,V>
Specified by:
size in interface Get<K,V>
Overrides:
size in class AbstractHashedMap<K,V>
Returns:
the size
See Also:
Map.size()

isEmpty

public boolean isEmpty()
Checks whether the map is currently empty.

Specified by:
isEmpty in interface Map<K,V>
Specified by:
isEmpty in interface Get<K,V>
Overrides:
isEmpty in class AbstractHashedMap<K,V>
Returns:
true if the map is currently size zero
See Also:
Map.isEmpty()

containsKey

public boolean containsKey(Object key)
Checks whether the map contains the specified key.

Specified by:
containsKey in interface Map<K,V>
Specified by:
containsKey in interface Get<K,V>
Overrides:
containsKey in class AbstractHashedMap<K,V>
Parameters:
key - the key to search for
Returns:
true if the map contains the key
See Also:
Map.containsKey(Object)

containsValue

public boolean containsValue(Object value)
Checks whether the map contains the specified value.

Specified by:
containsValue in interface Map<K,V>
Specified by:
containsValue in interface Get<K,V>
Overrides:
containsValue in class AbstractHashedMap<K,V>
Parameters:
value - the value to search for
Returns:
true if the map contains the value
See Also:
Map.containsValue(Object)

get

public V get(Object key)
Gets the value mapped to the key specified.

Specified by:
get in interface Map<K,V>
Specified by:
get in interface Get<K,V>
Overrides:
get in class AbstractHashedMap<K,V>
Parameters:
key - the key
Returns:
the mapped value, null if no match
See Also:
Map.get(Object)

put

public V put(K key,
             V value)
Puts a key-value mapping into this map. Neither the key nor the value may be null.

Specified by:
put in interface Map<K,V>
Specified by:
put in interface Put<K,V>
Overrides:
put in class AbstractHashedMap<K,V>
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
See Also:
Map.put(Object, Object)

remove

public V remove(Object key)
Removes the specified mapping from this map.

Specified by:
remove in interface Map<K,V>
Specified by:
remove in interface Get<K,V>
Overrides:
remove in class AbstractHashedMap<K,V>
Parameters:
key - the mapping to remove
Returns:
the value mapped to the removed key, null if key not in map
See Also:
Map.remove(Object)

clear

public void clear()
Clears this map.

Specified by:
clear in interface Map<K,V>
Specified by:
clear in interface Put<K,V>
Overrides:
clear in class AbstractHashedMap<K,V>
See Also:
Map.clear()

mapIterator

public MapIterator<K,V> mapIterator()
Gets a MapIterator over the reference map. The iterator only returns valid key/value pairs.

Specified by:
mapIterator in interface IterableGet<K,V>
Overrides:
mapIterator in class AbstractHashedMap<K,V>
Returns:
a map iterator

entrySet

public Set<Map.Entry<K,V>> 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 Map<K,V>
Specified by:
entrySet in interface Get<K,V>
Overrides:
entrySet in class AbstractHashedMap<K,V>
Returns:
a set view of this map's entries
See Also:
Map.entrySet()

keySet

public Set<K> keySet()
Returns a set view of this map's keys.

Specified by:
keySet in interface Map<K,V>
Specified by:
keySet in interface Get<K,V>
Overrides:
keySet in class AbstractHashedMap<K,V>
Returns:
a set view of this map's keys
See Also:
Map.keySet()

values

public Collection<V> values()
Returns a collection view of this map's values.

Specified by:
values in interface Map<K,V>
Specified by:
values in interface Get<K,V>
Overrides:
values in class AbstractHashedMap<K,V>
Returns:
a set view of this map's values
See Also:
Map.values()

purgeBeforeRead

protected void purgeBeforeRead()
Purges stale mappings from this map before read operations.

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


purgeBeforeWrite

protected void purgeBeforeWrite()
Purges stale mappings from this map before write operations.

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


purge

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.


purge

protected void purge(Reference<?> ref)
Purges the specified reference.

Parameters:
ref - the reference to purge

getEntry

protected AbstractHashedMap.HashEntry<K,V> getEntry(Object key)
Gets the entry mapped to the key specified.

Overrides:
getEntry in class AbstractHashedMap<K,V>
Parameters:
key - the key
Returns:
the entry, null if no match

hashEntry

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

isEqualKey

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.

Overrides:
isEqualKey in class AbstractHashedMap<K,V>
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

createEntry

protected AbstractReferenceMap.ReferenceEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K,V> next,
                                                               int hashCode,
                                                               K key,
                                                               V value)
Creates a ReferenceEntry instead of a HashEntry.

Overrides:
createEntry in class AbstractHashedMap<K,V>
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

createEntrySetIterator

protected Iterator<Map.Entry<K,V>> createEntrySetIterator()
Creates an entry set iterator.

Overrides:
createEntrySetIterator in class AbstractHashedMap<K,V>
Returns:
the entrySet iterator

createKeySetIterator

protected Iterator<K> createKeySetIterator()
Creates an key set iterator.

Overrides:
createKeySetIterator in class AbstractHashedMap<K,V>
Returns:
the keySet iterator

createValuesIterator

protected Iterator<V> createValuesIterator()
Creates an values iterator.

Overrides:
createValuesIterator in class AbstractHashedMap<K,V>
Returns:
the values iterator

doWriteObject

protected void doWriteObject(ObjectOutputStream out)
                      throws IOException
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.

Overrides:
doWriteObject in class AbstractHashedMap<K,V>
Parameters:
out - the output stream
Throws:
IOException - if an error occurs while writing to the stream

doReadObject

protected void doReadObject(ObjectInputStream in)
                     throws IOException,
                            ClassNotFoundException
Replaces the superclass 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.

Overrides:
doReadObject in class AbstractHashedMap<K,V>
Parameters:
in - the input stream
Throws:
IOException - if an error occurs while reading from the stream
ClassNotFoundException - if an object read from the stream can not be loaded

isKeyType

protected boolean isKeyType(AbstractReferenceMap.ReferenceStrength type)
Provided protected read-only access to the key type.

Parameters:
type - the type to check against.
Returns:
true if keyType has the specified type


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