org.apache.commons.collections.map
public abstract class AbstractReferenceMap extends AbstractHashedMap
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 java.util.Collections#synchronizedMap to
provide synchronized access to a ReferenceMap
.
Since: Commons Collections 3.1 (extracted from ReferenceMap in 3.0)
Version: $Revision: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
See Also: java.lang.ref.Reference
Nested Class Summary | |
---|---|
protected static class | AbstractReferenceMap.ReferenceEntry
A MapEntry implementation for the map.
|
Field Summary | |
---|---|
static int | HARD Constant indicating that hard references should be used |
protected int | keyType
The reference type for keys. |
protected boolean | purgeValues
Should the value be automatically purged when the associated key has been collected? |
static int | SOFT Constant indicating that soft references should be used |
protected int | valueType
The reference type for values. |
static int | WEAK Constant indicating that weak references should be used |
Constructor Summary | |
---|---|
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.
|
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 HashEntry | createEntry(HashEntry next, int hashCode, Object key, Object value)
Creates a ReferenceEntry instead of a HashEntry.
|
protected Iterator | createEntrySetIterator()
Creates an entry set iterator.
|
protected Iterator | createKeySetIterator()
Creates an key set iterator.
|
protected Iterator | createValuesIterator()
Creates an values iterator.
|
protected void | doReadObject(ObjectInputStream in)
Replaces the superclassm 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 | entrySet()
Returns a set view of this map's entries.
|
Object | get(Object key)
Gets the value mapped to the key specified.
|
protected HashEntry | 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.
|
Set | keySet()
Returns a set view of this map's keys.
|
MapIterator | 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.
|
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.
|
Serial:
Serial:
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
Parameters: key the key to search for
Returns: true if the map contains the key
Parameters: value the value to search for
Returns: true if the map contains the value
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
Returns: the entrySet iterator
Returns: the keySet iterator
Returns: the values iterator
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
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
next()
is called again.
The setValue()
method on the toArray
entries has no effect.
Returns: a set view of this map's entries
Parameters: key the key
Returns: the mapped value, null if no match
Parameters: key the key
Returns: the entry, null if no match
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
Returns: true if the map is currently size zero
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
Returns: a set view of this map's keys
Returns: a map iterator
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.
Parameters: ref the reference to purge
This implementation calls purge to maintain a consistent state.
This implementation calls purge to maintain a consistent state.
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
Parameters: key the mapping to remove
Returns: the value mapped to the removed key, null if key not in map
Returns: the size
Returns: a set view of this map's values