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
java.util.Collections.synchronizedMap
to
provide synchronized access to a
ReferenceMap
.
containsKey
public boolean containsKey(Object key)
Checks whether the map contains the specified key.
- containsKey in interface AbstractHashedMap
key
- the key to search for
- true if the map contains the key
containsValue
public boolean containsValue(Object value)
Checks whether the map contains the specified value.
- containsValue in interface AbstractHashedMap
value
- the value to search for
- true if the map contains the value
doReadObject
protected void doReadObject(ObjectInputStream in)
throws IOException,
ClassNotFoundException
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.
- doReadObject in interface AbstractHashedMap
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.
- doWriteObject in interface AbstractHashedMap
entrySet
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.
- entrySet in interface AbstractHashedMap
- a set view of this map's entries
get
public Object get(Object key)
Gets the value mapped to the key specified.
- get in interface AbstractHashedMap
- the mapped value, 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.
key
- the key to get a hash code for, may be nullvalue
- the value to get a hash code for, may be null
- the hash code, as per the MapEntry specification
init
protected void init()
Initialise this subclass during construction, cloning or deserialization.
- init in interface AbstractHashedMap
isEmpty
public boolean isEmpty()
Checks whether the map is currently empty.
- isEmpty in interface AbstractHashedMap
- true if the map is currently size zero
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.
- isEqualKey in interface AbstractHashedMap
key1
- the first key to compare passed in from outsidekey2
- the second key extracted from the entry via entry.key
keySet
public Set keySet()
Returns a set view of this map's keys.
- keySet in interface AbstractHashedMap
- a set view of this map's keys
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.
ref
- the reference to purge
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.
put
public Object put(Object key,
Object value)
Puts a key-value mapping into this map.
Neither the key nor the value may be null.
- put in interface AbstractHashedMap
key
- the key to add, must not be nullvalue
- the value to add, must not be null
- the value previously mapped to this key, null if none
remove
public Object remove(Object key)
Removes the specified mapping from this map.
- remove in interface AbstractHashedMap
key
- the mapping to remove
- the value mapped to the removed key, null if key not in map
values
public Collection values()
Returns a collection view of this map's values.
- values in interface AbstractHashedMap
- a set view of this map's values