Package 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

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private class	ReferenceMap.Entry	Deprecated.
private class	ReferenceMap.EntryIterator	Deprecated.
private class	ReferenceMap.KeyIterator	Deprecated.
private static class	ReferenceMap.SoftRef	Deprecated.
private class	ReferenceMap.ValueIterator	Deprecated.
private static class	ReferenceMap.WeakRef	Deprecated.

Nested classes/interfaces inherited from class java.util.AbstractMap

java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,V extends java.lang.Object>

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

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.