org.apache.commons.collections
Class ReferenceMap

java.lang.Object
  |
  +--java.util.AbstractMap
        |
        +--org.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 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) to provide synchronized access to a ReferenceMap.

Since:

2.1

Version:

$Id: ReferenceMap.java,v 1.7.2.1 2004/05/22 12:14:01 scolebourne Exp $

Author:

Paul Jack

See Also:

Reference

Field Summary

static int	HARD Constant indicating that hard references should be used.
static int	SOFT Constant indiciating that soft references should be used.
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.
boolean	isEmpty() Returns true if this map is empty.
java.util.Set	keySet() Returns a set view of this map's keys.
java.lang.Object	put(java.lang.Object key, java.lang.Object value) Associates the given key with the given value.
java.lang.Object	remove(java.lang.Object key) Removes the key and its associated value from this map.
int	size() Returns the size of this map.
java.util.Collection	values() Returns a collection view of this map's values.

Methods inherited from class java.util.AbstractMap

containsValue, equals, hashCode, putAll, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

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

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

size

public int size()

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()

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)

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)

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)

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)

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()

Clears this map.

Specified by:

clear in interface java.util.Map

Overrides:

clear in class java.util.AbstractMap

entrySet

public java.util.Set entrySet()

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()

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()

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.