Class ReferenceMap

  • All Implemented Interfaces:
    java.util.Map

    public class ReferenceMap
    extends java.util.AbstractMap
    Deprecated.
    Moved to map subpackage. Due to be removed in v4.0.
    Hash-based Map implementation that allows mappings to be removed by the garbage collector.

    When you construct a ReferenceMap, 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.

    The algorithms used are basically the same as those in HashMap. In particular, you can specify a load factor and capacity to suit your needs. All optional Map operations are supported.

    However, this Map implementation does not allow null elements. Attempting to add a null key or or a null value to the map will raise a NullPointerException.

    As usual, 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 2.1
    Version:
    $Revision: 646777 $ $Date: 2008-04-10 14:33:15 +0200 (Thu, 10 Apr 2008) $
    See Also:
    Reference
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.util.Set entrySet
      Deprecated.
      Cached entry set.
      static int HARD
      Deprecated.
      Constant indicating that hard references should be used.
      private java.util.Set keySet
      Deprecated.
      Cached key set.
      private int keyType
      Deprecated.
      The reference type for keys.
      private float loadFactor
      Deprecated.
      The threshold variable is calculated by multiplying table.length and loadFactor.
      private int modCount
      Deprecated.
      Number of times this map has been modified.
      private boolean purgeValues
      Deprecated.
      Should the value be automatically purged when the associated key has been collected?
      private java.lang.ref.ReferenceQueue queue
      Deprecated.
      ReferenceQueue used to eliminate stale mappings.
      private static long serialVersionUID
      Deprecated.
      For serialization.
      private int size
      Deprecated.
      Number of mappings in this map.
      static int SOFT
      Deprecated.
      Constant indicating that soft references should be used.
      private ReferenceMap.Entry[] table
      Deprecated.
      The hash table.
      private int threshold
      Deprecated.
      When size reaches threshold, the map is resized.
      private java.util.Collection values
      Deprecated.
      Cached values.
      private int valueType
      Deprecated.
      The reference type for values.
      static int WEAK
      Deprecated.
      Constant indicating that weak references should be used.
    • Constructor Summary

      Constructors 
      Constructor Description
      ReferenceMap()
      Deprecated.
      Constructs a new ReferenceMap that will use hard references to keys and soft references to values.
      ReferenceMap​(int keyType, int valueType)
      Deprecated.
      Constructs a new ReferenceMap that will use the specified types of references.
      ReferenceMap​(int keyType, int valueType, boolean purgeValues)
      Deprecated.
      Constructs a new ReferenceMap that will use the specified types of references.
      ReferenceMap​(int keyType, int valueType, int capacity, float loadFactor)
      Deprecated.
      Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
      ReferenceMap​(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)
      Deprecated.
      Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void clear()
      Deprecated.
      Clears this map.
      boolean containsKey​(java.lang.Object key)
      Deprecated.
      Returns true if this map contains the given key.
      java.util.Set entrySet()
      Deprecated.
      Returns a set view of this map's entries.
      java.lang.Object get​(java.lang.Object key)
      Deprecated.
      Returns the value associated with the given key, if any.
      private ReferenceMap.Entry getEntry​(java.lang.Object key)
      Deprecated.
      Returns the entry associated with the given key.
      private int indexFor​(int hash)
      Deprecated.
      Converts the given hash code into an index into the hash table.
      boolean isEmpty()
      Deprecated.
      Returns true if this map is empty.
      java.util.Set keySet()
      Deprecated.
      Returns a set view of this map's keys.
      private void purge()
      Deprecated.
      Purges stale mappings from this map.
      private void purge​(java.lang.ref.Reference ref)
      Deprecated.
       
      java.lang.Object put​(java.lang.Object key, java.lang.Object value)
      Deprecated.
      Associates the given key with the given value.
      private void readObject​(java.io.ObjectInputStream inp)
      Deprecated.
      Reads the contents of this object from the given input stream.
      java.lang.Object remove​(java.lang.Object key)
      Deprecated.
      Removes the key and its associated value from this map.
      private void resize()
      Deprecated.
      Resizes this hash table by doubling its capacity.
      int size()
      Deprecated.
      Returns the size of this map.
      private java.lang.Object toReference​(int type, java.lang.Object referent, int hash)
      Deprecated.
      Constructs a reference of the given type to the given referent.
      java.util.Collection values()
      Deprecated.
      Returns a collection view of this map's values.
      private static void verify​(java.lang.String name, int type)
      Deprecated.
       
      private void writeObject​(java.io.ObjectOutputStream out)
      Deprecated.
      Writes this object to the given output stream.
      • Methods inherited from class java.util.AbstractMap

        clone, containsValue, equals, hashCode, putAll, toString
      • Methods inherited from class java.lang.Object

        finalize, 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

      • serialVersionUID

        private static final long serialVersionUID
        Deprecated.
        For serialization.
        See Also:
        Constant Field Values
      • HARD

        public static final int HARD
        Deprecated.
        Constant indicating that hard references should be used.
        See Also:
        Constant Field Values
      • SOFT

        public static final int SOFT
        Deprecated.
        Constant indicating that soft references should be used.
        See Also:
        Constant Field Values
      • WEAK

        public static final int WEAK
        Deprecated.
        Constant indicating that weak references should be used.
        See Also:
        Constant Field Values
      • keyType

        private int keyType
        Deprecated.
        The reference type for keys. Must be HARD, SOFT, WEAK. Note: I originally marked this field as final, but then this class didn't compile under JDK1.2.2.
      • valueType

        private int valueType
        Deprecated.
        The reference type for values. Must be HARD, SOFT, WEAK. Note: I originally marked this field as final, but then this class didn't compile under JDK1.2.2.
      • loadFactor

        private float loadFactor
        Deprecated.
        The threshold variable is calculated by multiplying table.length and loadFactor. Note: I originally marked this field as final, but then this class didn't compile under JDK1.2.2.
      • purgeValues

        private boolean purgeValues
        Deprecated.
        Should the value be automatically purged when the associated key has been collected?
      • queue

        private transient java.lang.ref.ReferenceQueue queue
        Deprecated.
        ReferenceQueue used to eliminate stale mappings. See purge.
      • table

        private transient ReferenceMap.Entry[] table
        Deprecated.
        The hash table. Its length is always a power of two.
      • size

        private transient int size
        Deprecated.
        Number of mappings in this map.
      • threshold

        private transient int threshold
        Deprecated.
        When size reaches threshold, the map is resized. See resize().
      • modCount

        private transient volatile int modCount
        Deprecated.
        Number of times this map has been modified.
      • keySet

        private transient java.util.Set keySet
        Deprecated.
        Cached key set. May be null if key set is never accessed.
      • entrySet

        private transient java.util.Set entrySet
        Deprecated.
        Cached entry set. May be null if entry set is never accessed.
      • values

        private transient java.util.Collection values
        Deprecated.
        Cached values. May be null if values() is never accessed.
    • Constructor Detail

      • ReferenceMap

        public ReferenceMap()
        Deprecated.
        Constructs a new ReferenceMap that will use hard references to keys and soft references to values.
      • ReferenceMap

        public ReferenceMap​(int keyType,
                            int valueType,
                            boolean purgeValues)
        Deprecated.
        Constructs a new ReferenceMap that will use the specified types of references.
        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
        purgeValues - should the value be automatically purged when the key is garbage collected
      • ReferenceMap

        public ReferenceMap​(int keyType,
                            int valueType)
        Deprecated.
        Constructs a new ReferenceMap that will use the specified types of references.
        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
      • ReferenceMap

        public ReferenceMap​(int keyType,
                            int valueType,
                            int capacity,
                            float loadFactor,
                            boolean purgeValues)
        Deprecated.
        Constructs a new ReferenceMap 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 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
      • ReferenceMap

        public ReferenceMap​(int keyType,
                            int valueType,
                            int capacity,
                            float loadFactor)
        Deprecated.
        Constructs a new ReferenceMap 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 HARD, SOFT, WEAK
        capacity - the initial capacity for the map
        loadFactor - the load factor for the map
    • Method Detail

      • verify

        private static void verify​(java.lang.String name,
                                   int type)
        Deprecated.
      • writeObject

        private void writeObject​(java.io.ObjectOutputStream out)
                          throws java.io.IOException
        Deprecated.
        Writes this object to the given output stream.
        Parameters:
        out - the output stream to write to
        Throws:
        java.io.IOException - if the stream raises it
      • readObject

        private void readObject​(java.io.ObjectInputStream inp)
                         throws java.io.IOException,
                                java.lang.ClassNotFoundException
        Deprecated.
        Reads the contents of this object from the given input stream.
        Parameters:
        inp - the input stream to read from
        Throws:
        java.io.IOException - if the stream raises it
        java.lang.ClassNotFoundException - if the stream raises it
      • toReference

        private java.lang.Object toReference​(int type,
                                             java.lang.Object referent,
                                             int hash)
        Deprecated.
        Constructs a reference of the given type to the given referent. The reference is registered with the queue for later purging.
        Parameters:
        type - HARD, SOFT or WEAK
        referent - the object to refer to
        hash - the hash code of the key of the mapping; this number might be different from referent.hashCode() if the referent represents a value and not a key
      • getEntry

        private ReferenceMap.Entry getEntry​(java.lang.Object key)
        Deprecated.
        Returns the entry associated with the given key.
        Parameters:
        key - the key of the entry to look up
        Returns:
        the entry associated with that key, or null if the key is not in this map
      • indexFor

        private int indexFor​(int hash)
        Deprecated.
        Converts the given hash code into an index into the hash table.
      • resize

        private void resize()
        Deprecated.
        Resizes this hash table by doubling its capacity. This is an expensive operation, as entries must be copied from the old smaller table to the new bigger table.
      • purge

        private void purge()
        Deprecated.
        Purges stale mappings from this map.

        Ordinarily, stale mappings are only removed during a write operation, although this method is called for both read and write operations to maintain a consistent state.

        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

        private void purge​(java.lang.ref.Reference ref)
        Deprecated.
      • size

        public int size()
        Deprecated.
        Returns the size of this map.
        Specified by:
        size in interface java.util.Map
        Overrides:
        size in class java.util.AbstractMap
        Returns:
        the size of this map
      • isEmpty

        public boolean isEmpty()
        Deprecated.
        Returns true if this map is empty.
        Specified by:
        isEmpty in interface java.util.Map
        Overrides:
        isEmpty in class java.util.AbstractMap
        Returns:
        true if this map is empty
      • containsKey

        public boolean containsKey​(java.lang.Object key)
        Deprecated.
        Returns true if this map contains the given key.
        Specified by:
        containsKey in interface java.util.Map
        Overrides:
        containsKey in class java.util.AbstractMap
        Returns:
        true if the given key is in this map
      • get

        public java.lang.Object get​(java.lang.Object key)
        Deprecated.
        Returns the value associated with the given key, if any.
        Specified by:
        get in interface java.util.Map
        Overrides:
        get in class java.util.AbstractMap
        Returns:
        the value associated with the given key, or null if the key maps to no value
      • put

        public java.lang.Object put​(java.lang.Object key,
                                    java.lang.Object value)
        Deprecated.
        Associates the given key with the given value.

        Neither the key nor the value may be null.

        Specified by:
        put in interface java.util.Map
        Overrides:
        put in class java.util.AbstractMap
        Parameters:
        key - the key of the mapping
        value - the value of the mapping
        Returns:
        the last value associated with that key, or null if no value was associated with the key
        Throws:
        java.lang.NullPointerException - if either the key or value is null
      • remove

        public java.lang.Object remove​(java.lang.Object key)
        Deprecated.
        Removes the key and its associated value from this map.
        Specified by:
        remove in interface java.util.Map
        Overrides:
        remove in class java.util.AbstractMap
        Parameters:
        key - the key to remove
        Returns:
        the value associated with that key, or null if the key was not in the map
      • clear

        public void clear()
        Deprecated.
        Clears this map.
        Specified by:
        clear in interface java.util.Map
        Overrides:
        clear in class java.util.AbstractMap
      • entrySet

        public java.util.Set entrySet()
        Deprecated.
        Returns a set view of this map's entries.
        Specified by:
        entrySet in interface java.util.Map
        Specified by:
        entrySet in class java.util.AbstractMap
        Returns:
        a set view of this map's entries
      • keySet

        public java.util.Set keySet()
        Deprecated.
        Returns a set view of this map's keys.
        Specified by:
        keySet in interface java.util.Map
        Overrides:
        keySet in class java.util.AbstractMap
        Returns:
        a set view of this map's keys
      • values

        public java.util.Collection values()
        Deprecated.
        Returns a collection view of this map's values.
        Specified by:
        values in interface java.util.Map
        Overrides:
        values in class java.util.AbstractMap
        Returns:
        a collection view of this map's values.