Java Doc for AbstractReferenceMap.java in  » Library » Apache-common-Collections » org » apache » commons » collections » map » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.
See Also:   java.lang.ref.Reference
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) $
author:
   Paul Jack
author:
   Stephen Colebourne

Serialization is not one of the JDK's nicest topics.

Serialization is not one of the JDK's nicest topics.

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

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
Parameters:
  key2 - the second key extracted from the entry via entry.key true if equal

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.

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

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