## org.apache.commons.collections.map
Class ReferenceMap

    java.lang.Object
      java.util.AbstractMap
          org.apache.commons.collections.map.AbstractHashedMap
              org.apache.commons.collections.map.AbstractReferenceMap
                  org.apache.commons.collections.map.ReferenceMap

All Implemented Interfaces:
  IterableMap, Map, Serializable

public class ReferenceMap
extends AbstractReferenceMap
implements Serializable

A `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.

This map is similar to `ReferenceIdentityMap`. It differs in that keys and values in this class are compared using `equals()`.

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

This implementation is not synchronized. You can use `Collections.synchronizedMap(java.util.Map)` to provide synchronized access to a `ReferenceMap`. Remember that synchronization will not stop the garbage collecter removing entries.

All the available iterators can be reset back to the start by casting to `ResettableIterator` and calling `reset()`.

NOTE: As from Commons Collections 3.1 this map extends `AbstractReferenceMap` (previously it extended AbstractMap). As a result, the implementation is now extensible and provides a `MapIterator`.

Since:
  Commons Collections 3.0 (previously in main package v2.1)
Version:
  $Revision: 1.13 $ $Date: 2004/04/27 21:35:23 $
Author:
  Paul Jack, Stephen Colebourne
See Also:
  `Reference`, Serialized Form

Nested Class Summary

Nested classes inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`AbstractReferenceMap.ReferenceEntry`

Nested classes inherited from class org.apache.commons.collections.map.AbstractHashedMap
`AbstractHashedMap.EntrySet, AbstractHashedMap.EntrySetIterator, AbstractHashedMap.HashEntry, AbstractHashedMap.HashIterator, AbstractHashedMap.HashMapIterator, AbstractHashedMap.KeySet, AbstractHashedMap.KeySetIterator, AbstractHashedMap.Values, AbstractHashedMap.ValuesIterator`

Nested classes inherited from class java.util.Map
`Map.Entry`

Field Summary

Fields inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`HARD, keyType, purgeValues, SOFT, valueType, WEAK`

Fields inherited from class org.apache.commons.collections.map.AbstractHashedMap
`data, DEFAULT_CAPACITY, DEFAULT_LOAD_FACTOR, DEFAULT_THRESHOLD, entrySet, GETKEY_INVALID, GETVALUE_INVALID, keySet, loadFactor, MAXIMUM_CAPACITY, modCount, NO_NEXT_ENTRY, NO_PREVIOUS_ENTRY, NULL, REMOVE_INVALID, SETVALUE_INVALID, size, threshold, values`

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, boolean purgeValues)` 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.
`ReferenceMap(int keyType, int valueType, int capacity, float loadFactor, boolean purgeValues)` Constructs a new `ReferenceMap` with the specified reference types, load factor and initial capacity.

Methods inherited from class org.apache.commons.collections.map.AbstractReferenceMap
`clear, containsKey, containsValue, createEntry, createEntrySetIterator, createKeySetIterator, createValuesIterator, doReadObject, doWriteObject, entrySet, get, getEntry, hashEntry, init, isEmpty, isEqualKey, keySet, mapIterator, purge, purge, purgeBeforeRead, purgeBeforeWrite, put, remove, size, values`

Methods inherited from class org.apache.commons.collections.map.AbstractHashedMap
`addEntry, addMapping, calculateNewCapacity, calculateThreshold, checkCapacity, clone, convertKey, destroyEntry, ensureCapacity, entryHashCode, entryKey, entryNext, entryValue, equals, hash, hashCode, hashIndex, isEqualValue, putAll, removeEntry, removeMapping, reuseEntry, toString, updateEntry`

Methods inherited from class java.lang.Object
`finalize, getClass, notify, notifyAll, wait, wait, wait`

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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`

### ReferenceMap

    public ReferenceMap(int keyType,
                        int valueType,
                        boolean purgeValues)

  Constructs a new `ReferenceMap` that will use the specified types of references.

Parameters:
  `keyType` - the type of reference to use for keys; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `purgeValues` - should the value be automatically purged when the key is garbage collected

### 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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `capacity` - the initial capacity for the map
  `loadFactor` - the load factor for the map

### ReferenceMap

    public ReferenceMap(int keyType,
                        int valueType,
                        int capacity,
                        float loadFactor,
                        boolean purgeValues)

  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 `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.WEAK`
  `valueType` - the type of reference to use for values; must be `AbstractReferenceMap.HARD`, `AbstractReferenceMap.SOFT`, `AbstractReferenceMap.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

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.