Keel 2.1RC2

org.apache.commons.collections
Class ReferenceMap

java.lang.Object
  extended byjava.util.AbstractMap
      extended byorg.apache.commons.collections.ReferenceMap
All Implemented Interfaces:
java.util.Map

public class ReferenceMap
extends java.util.AbstractMap

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

Since:
2.1
Version:
$Id: ReferenceMap.java,v 1.7 2002/10/12 22:15:18 scolebourne Exp $
Author:
Paul Jack
See Also:
Reference

Nested Class Summary
private  class ReferenceMap.Entry
           
private  class ReferenceMap.EntryIterator
           
private  class ReferenceMap.KeyIterator
           
private static class ReferenceMap.SoftRef
           
private  class ReferenceMap.ValueIterator
           
private static class ReferenceMap.WeakRef
           
 
Nested classes inherited from class java.util.AbstractMap
 
Field Summary
private  java.util.Set entrySet
          Cached entry set.
static int HARD
          Constant indicating that hard references should be used.
private  java.util.Set keySet
          Cached key set.
private  int keyType
          The reference type for keys.
private  float loadFactor
          The threshold variable is calculated by multiplying table.length and loadFactor.
private  int modCount
          Number of times this map has been modified.
private  java.lang.ref.ReferenceQueue queue
          ReferenceQueue used to eliminate stale mappings.
private static long serialVersionUID
          For serialization.
private  int size
          Number of mappings in this map.
static int SOFT
          Constant indiciating that soft references should be used.
private  ReferenceMap.Entry[] table
          The hash table.
private  int threshold
          When size reaches threshold, the map is resized.
private  java.util.Collection values
          Cached values.
private  int valueType
          The reference type for values.
static int WEAK
          Constant indicating that weak references should be used.
 
Constructor Summary
ReferenceMap()
          Constructs a new ReferenceMap that will use hard references to keys and soft references to values.
ReferenceMap(int keyType, int valueType)
          Constructs a new ReferenceMap that will use the specified types of references.
ReferenceMap(int keyType, int valueType, int capacity, float loadFactor)
          Constructs a new ReferenceMap with the specified reference types, load factor and initial capacity.
 
Method Summary
 void clear()
          Clears this map.
 boolean containsKey(java.lang.Object key)
          Returns true if this map contains the given key.
 java.util.Set entrySet()
          Returns a set view of this map's entries.
 java.lang.Object get(java.lang.Object key)
          Returns the value associated with the given key, if any.
private  ReferenceMap.Entry getEntry(java.lang.Object key)
          Returns the entry associated with the given key.
private  int indexFor(int hash)
          Converts the given hash code into an index into the hash table.
 boolean isEmpty()
          Returns true if this map is empty.
 java.util.Set keySet()
          Returns a set view of this map's keys.
private  void purge()
          Purges stale mappings from this map.
private  void purge(java.lang.ref.Reference ref)
           
 java.lang.Object put(java.lang.Object key, java.lang.Object value)
          Associates the given key with the given value.
private  void readObject(java.io.ObjectInputStream inp)
          Reads the contents of this object from the given input stream.
 java.lang.Object remove(java.lang.Object key)
          Removes the key and its associated value from this map.
private  void resize()
          Resizes this hash table by doubling its capacity.
 int size()
          Returns the size of this map.
private  java.lang.Object toReference(int type, java.lang.Object referent, int hash)
          Constructs a reference of the given type to the given referent.
 java.util.Collection values()
          Returns a collection view of this map's values.
private static void verify(java.lang.String name, int type)
           
private  void writeObject(java.io.ObjectOutputStream out)
          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
 

Field Detail

serialVersionUID

private static final long serialVersionUID
For serialization.

See Also:
Constant Field Values

HARD

public static final int HARD
Constant indicating that hard references should be used.

See Also:
Constant Field Values

SOFT

public static final int SOFT
Constant indiciating that soft references should be used.

See Also:
Constant Field Values

WEAK

public static final int WEAK
Constant indicating that weak references should be used.

See Also:
Constant Field Values

keyType

private int keyType
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
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
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.


queue

private transient java.lang.ref.ReferenceQueue queue
ReferenceQueue used to eliminate stale mappings.

See Also:
purge()

table

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


size

private transient int size
Number of mappings in this map.


threshold

private transient int threshold
When size reaches threshold, the map is resized.

See Also:
resize

modCount

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


keySet

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


entrySet

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


values

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

Constructor Detail

ReferenceMap

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


ReferenceMap

public ReferenceMap(int keyType,
                    int valueType)
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)
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)

writeObject

private void writeObject(java.io.ObjectOutputStream out)
                  throws java.io.IOException
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
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)
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)
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)
Converts the given hash code into an index into the hash table.


resize

private void resize()
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()
Purges stale mappings from this map.

Ordinarily, stale mappings are only removed during a write operation; typically a write operation will occur often enough that you'll never need to manually invoke this method.

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)

size

public int size()
Returns the size of this map.

Returns:
the size of this map

isEmpty

public boolean isEmpty()
Returns true if this map is empty.

Returns:
true if this map is empty

containsKey

public boolean containsKey(java.lang.Object key)
Returns true if this map contains the given key.

Returns:
true if the given key is in this map

get

public java.lang.Object get(java.lang.Object key)
Returns the value associated with the given key, if any.

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)
Associates the given key with the given value.

Neither the key nor the value may be null.

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)
Removes the key and its associated value from this map.

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()
Clears this map.


entrySet

public java.util.Set entrySet()
Returns a set view of this map's entries.

Returns:
a set view of this map's entries

keySet

public java.util.Set keySet()
Returns a set view of this map's keys.

Returns:
a set view of this map's keys

values

public java.util.Collection values()
Returns a collection view of this map's values.

Returns:
a collection view of this map's values.

Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.