K
- the type of the keys in this mapV
- the type of the values in this mappublic abstract class AbstractReferenceMap<K,V> extends AbstractHashedMap<K,V>
This class implements all the features necessary for a subclass reference
hash-based map. Key-value entries are stored in instances of the
ReferenceEntry
class which can be overridden and replaced.
The iterators can similarly be replaced, without the need to replace the KeySet,
EntrySet and Values view classes.
Overridable methods are provided to change the default hashing behaviour, and to change how entries are added to and removed from the map. Hopefully, all you need for unusual subclasses is here.
When you construct an AbstractReferenceMap
, 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
implementation does not allow null elements.
Attempting to add a null key or value to the map will raise a
NullPointerException
.
All the available iterators can be reset back to the start by casting to
ResettableIterator
and calling reset()
.
This implementation is not synchronized.
You can use Collections.synchronizedMap(java.util.Map<K, V>)
to
provide synchronized access to a ReferenceMap
.
Reference
Modifier and Type | Class and Description |
---|---|
(package private) static class |
AbstractReferenceMap.ReferenceBaseIterator<K,V>
Base iterator class.
|
protected static class |
AbstractReferenceMap.ReferenceEntry<K,V>
A MapEntry implementation for the map.
|
(package private) static class |
AbstractReferenceMap.ReferenceEntrySet<K,V>
EntrySet implementation.
|
(package private) static class |
AbstractReferenceMap.ReferenceEntrySetIterator<K,V>
The EntrySet iterator.
|
(package private) static class |
AbstractReferenceMap.ReferenceKeySet<K>
KeySet implementation.
|
(package private) static class |
AbstractReferenceMap.ReferenceKeySetIterator<K>
The keySet iterator.
|
(package private) static class |
AbstractReferenceMap.ReferenceMapIterator<K,V>
The MapIterator implementation.
|
static class |
AbstractReferenceMap.ReferenceStrength
Reference type enum.
|
(package private) static class |
AbstractReferenceMap.ReferenceValues<V>
Values implementation.
|
(package private) static class |
AbstractReferenceMap.ReferenceValuesIterator<V>
The values iterator.
|
(package private) static class |
AbstractReferenceMap.SoftRef<T>
A soft reference holder.
|
(package private) static class |
AbstractReferenceMap.WeakRef<T>
A weak reference holder.
|
AbstractHashedMap.EntrySet<K,V>, AbstractHashedMap.EntrySetIterator<K,V>, AbstractHashedMap.HashEntry<K,V>, AbstractHashedMap.HashIterator<K,V>, AbstractHashedMap.HashMapIterator<K,V>, AbstractHashedMap.KeySet<K>, AbstractHashedMap.KeySetIterator<K>, AbstractHashedMap.Values<V>, AbstractHashedMap.ValuesIterator<V>
Modifier and Type | Field and Description |
---|---|
private AbstractReferenceMap.ReferenceStrength |
keyType
The reference type for keys.
|
private boolean |
purgeValues
Should the value be automatically purged when the associated key has been collected?
|
private java.lang.ref.ReferenceQueue<java.lang.Object> |
queue
ReferenceQueue used to eliminate stale mappings.
|
private AbstractReferenceMap.ReferenceStrength |
valueType
The reference type for values.
|
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
Modifier | Constructor and Description |
---|---|
protected |
AbstractReferenceMap()
Constructor used during deserialization.
|
protected |
AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType,
AbstractReferenceMap.ReferenceStrength valueType,
int capacity,
float loadFactor,
boolean purgeValues)
Constructs a new empty map with the specified reference types,
load factor and initial capacity.
|
Modifier and Type | Method and Description |
---|---|
void |
clear()
Clears this map.
|
boolean |
containsKey(java.lang.Object key)
Checks whether the map contains the specified key.
|
boolean |
containsValue(java.lang.Object value)
Checks whether the map contains the specified value.
|
protected AbstractReferenceMap.ReferenceEntry<K,V> |
createEntry(AbstractHashedMap.HashEntry<K,V> next,
int hashCode,
K key,
V value)
Creates a ReferenceEntry instead of a HashEntry.
|
protected java.util.Iterator<java.util.Map.Entry<K,V>> |
createEntrySetIterator()
Creates an entry set iterator.
|
protected java.util.Iterator<K> |
createKeySetIterator()
Creates an key set iterator.
|
protected java.util.Iterator<V> |
createValuesIterator()
Creates an values iterator.
|
protected void |
doReadObject(java.io.ObjectInputStream in)
Replaces the superclass method to read the state of this class.
|
protected void |
doWriteObject(java.io.ObjectOutputStream out)
Replaces the superclass method to store the state of this class.
|
java.util.Set<java.util.Map.Entry<K,V>> |
entrySet()
Returns a set view of this map's entries.
|
V |
get(java.lang.Object key)
Gets the value mapped to the key specified.
|
protected AbstractHashedMap.HashEntry<K,V> |
getEntry(java.lang.Object key)
Gets the entry mapped to the key specified.
|
protected int |
hashEntry(java.lang.Object key,
java.lang.Object value)
Gets the hash code for a MapEntry.
|
protected void |
init()
Initialise this subclass during construction, cloning or deserialization.
|
boolean |
isEmpty()
Checks whether the map is currently empty.
|
protected boolean |
isEqualKey(java.lang.Object key1,
java.lang.Object key2)
Compares two keys, in internal converted form, to see if they are equal.
|
protected boolean |
isKeyType(AbstractReferenceMap.ReferenceStrength type)
Provided protected read-only access to the key type.
|
protected boolean |
isValueType(AbstractReferenceMap.ReferenceStrength type)
Provided protected read-only access to the value type.
|
java.util.Set<K> |
keySet()
Returns a set view of this map's keys.
|
MapIterator<K,V> |
mapIterator()
Gets a MapIterator over the reference map.
|
protected void |
purge()
Purges stale mappings from this map.
|
protected void |
purge(java.lang.ref.Reference<?> ref)
Purges the specified reference.
|
protected void |
purgeBeforeRead()
Purges stale mappings from this map before read operations.
|
protected void |
purgeBeforeWrite()
Purges stale mappings from this map before write operations.
|
V |
put(K key,
V value)
Puts a key-value mapping into this map.
|
V |
remove(java.lang.Object key)
Removes the specified mapping from this map.
|
int |
size()
Gets the size of the map.
|
java.util.Collection<V> |
values()
Returns a collection view of this map's values.
|
addEntry, addMapping, calculateNewCapacity, calculateThreshold, checkCapacity, clone, convertKey, destroyEntry, ensureCapacity, entryHashCode, entryKey, entryNext, entryValue, equals, hash, hashCode, hashIndex, isEqualValue, putAll, removeEntry, removeMapping, reuseEntry, toString, updateEntry
private AbstractReferenceMap.ReferenceStrength keyType
private AbstractReferenceMap.ReferenceStrength valueType
private boolean purgeValues
private transient java.lang.ref.ReferenceQueue<java.lang.Object> queue
protected AbstractReferenceMap()
protected AbstractReferenceMap(AbstractReferenceMap.ReferenceStrength keyType, AbstractReferenceMap.ReferenceStrength valueType, int capacity, float loadFactor, boolean purgeValues)
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 AbstractReferenceMap.ReferenceStrength.HARD
,
SOFT
,
WEAK
capacity
- the initial capacity for the maploadFactor
- the load factor for the mappurgeValues
- should the value be automatically purged when the
key is garbage collectedprotected void init()
init
in class AbstractHashedMap<K,V>
public int size()
public boolean isEmpty()
public boolean containsKey(java.lang.Object key)
containsKey
in interface java.util.Map<K,V>
containsKey
in interface Get<K,V>
containsKey
in class AbstractHashedMap<K,V>
key
- the key to search forMap.containsKey(Object)
public boolean containsValue(java.lang.Object value)
containsValue
in interface java.util.Map<K,V>
containsValue
in interface Get<K,V>
containsValue
in class AbstractHashedMap<K,V>
value
- the value to search forMap.containsValue(Object)
public V get(java.lang.Object key)
public V put(K key, V value)
put
in interface java.util.Map<K,V>
put
in interface Put<K,V>
put
in class AbstractHashedMap<K,V>
key
- the key to add, must not be nullvalue
- the value to add, must not be nulljava.lang.NullPointerException
- if either the key or value is nullMap.put(Object, Object)
public V remove(java.lang.Object key)
public void clear()
public MapIterator<K,V> mapIterator()
mapIterator
in interface IterableGet<K,V>
mapIterator
in class AbstractHashedMap<K,V>
public java.util.Set<java.util.Map.Entry<K,V>> entrySet()
next()
is called again.
The setValue()
method on the toArray
entries has no effect.public java.util.Set<K> keySet()
public java.util.Collection<V> values()
protected void purgeBeforeRead()
This implementation calls purge()
to maintain a consistent state.
protected void purgeBeforeWrite()
This implementation calls purge()
to maintain a consistent state.
protected void purge()
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.
protected void purge(java.lang.ref.Reference<?> ref)
ref
- the reference to purgeprotected AbstractHashedMap.HashEntry<K,V> getEntry(java.lang.Object key)
getEntry
in class AbstractHashedMap<K,V>
key
- the keyprotected int hashEntry(java.lang.Object key, java.lang.Object value)
key
- the key to get a hash code for, may be nullvalue
- the value to get a hash code for, may be nullprotected boolean isEqualKey(java.lang.Object key1, java.lang.Object key2)
This implementation converts the key from the entry to a real reference before comparison.
isEqualKey
in class AbstractHashedMap<K,V>
key1
- the first key to compare passed in from outsidekey2
- the second key extracted from the entry via entry.key
protected AbstractReferenceMap.ReferenceEntry<K,V> createEntry(AbstractHashedMap.HashEntry<K,V> next, int hashCode, K key, V value)
createEntry
in class AbstractHashedMap<K,V>
next
- the next entry in sequencehashCode
- the hash code to usekey
- the key to storevalue
- the value to storeprotected java.util.Iterator<java.util.Map.Entry<K,V>> createEntrySetIterator()
createEntrySetIterator
in class AbstractHashedMap<K,V>
protected java.util.Iterator<K> createKeySetIterator()
createKeySetIterator
in class AbstractHashedMap<K,V>
protected java.util.Iterator<V> createValuesIterator()
createValuesIterator
in class AbstractHashedMap<K,V>
protected void doWriteObject(java.io.ObjectOutputStream out) throws java.io.IOException
Serialization is not one of the JDK's nicest topics. Normal serialization will
initialise the superclass before the subclass. Sometimes however, this isn't
what you want, as in this case the put()
method on read can be
affected by subclass state.
The solution adopted here is to serialize the state data of this class in
this protected method. This method must be called by the
writeObject()
of the first serializable subclass.
Subclasses may override if they have a specific field that must be present on read before this implementation will work. Generally, the read determines what must be serialized here, if anything.
doWriteObject
in class AbstractHashedMap<K,V>
out
- the output streamjava.io.IOException
- if an error occurs while writing to the streamprotected void doReadObject(java.io.ObjectInputStream in) throws java.io.IOException, java.lang.ClassNotFoundException
Serialization is not one of the JDK's nicest topics. Normal serialization will
initialise the superclass before the subclass. Sometimes however, this isn't
what you want, as in this case the put()
method on read can be
affected by subclass state.
The solution adopted here is to deserialize the state data of this class in
this protected method. This method must be called by the
readObject()
of the first serializable subclass.
Subclasses may override if the subclass has a specific field that must be present
before put()
or calculateThreshold()
will work correctly.
doReadObject
in class AbstractHashedMap<K,V>
in
- the input streamjava.io.IOException
- if an error occurs while reading from the streamjava.lang.ClassNotFoundException
- if an object read from the stream can not be loadedprotected boolean isKeyType(AbstractReferenceMap.ReferenceStrength type)
type
- the type to check against.protected boolean isValueType(AbstractReferenceMap.ReferenceStrength type)
type
- the type to check against.