oracle.javatools.util
Class Maps.CacheMap<K,V>

java.lang.Object
  oracle.javatools.util.Maps.AbstractHashMap<K,V,E>
      oracle.javatools.util.Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>
          oracle.javatools.util.Maps.CacheMap<K,V>

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map<K,V>

Direct Known Subclasses:

Maps.ManagedCacheMap

Enclosing class:

Maps

public static class Maps.CacheMap<K,V>
extends Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

See Also:

Serialized Form

Nested Class Summary

static class	Maps.CacheMap.Canonicity The canonicity of a mapping.
static class	Maps.CacheMap.Strength The types of references to values supported.

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Field Summary

static Maps.CacheMap.Canonicity	CANONICAL
static Maps.CacheMap.Strength	HARD
static Maps.CacheMap.Canonicity	NONCANONICAL Deprecated. Use NOT_CANONICAL.
static Maps.CacheMap.Canonicity	NOT_CANONICAL
static Maps.CacheMap.Strength	SOFT
static Maps.CacheMap.Strength	STRONG
static Maps.CacheMap.Strength	WEAK

Fields inherited from class oracle.javatools.util.Maps.AbstractHashMap

DEFAULT_INITIAL_CAPACITY, DEFAULT_LOAD_FACTOR, MAXIMUM_CAPACITY

Constructor Summary

Maps.CacheMap()
Constructs an unbounded, non-canonical cache map with strongly- referenced values.

Maps.CacheMap(int bound)
Constructs a bounded LRU (least recently used), canonical cache map with strongly-referenced values.

Maps.CacheMap(int bound, Maps.CacheMap.Canonicity canonicity)
Constructs a bounded LRU (least recently used) cache map with strongly-referenced values.

Maps.CacheMap(int bound, Maps.CacheMap.Strength strength)
Constructs a bounded LRU (least recently used), canonical cache map.

Maps.CacheMap(Maps.CacheMap.Strength strength)
Constructs an unbounded, non-canonical cache map.

Maps.CacheMap(Maps.CacheStrategy<K,V> strategy)
Constructs a cache map with specified Maps.CacheStrategy.

Method Summary

void	clear() Removes all mappings from this map.
protected Maps.LinkedEntry<K,V>	createEntry(int hashCode, K key, V value, Maps.LinkedEntry<K,V> next) Creates an entry for this map.
protected Maps.CacheStrategy<K,V>	decoratedStrategy(Maps.CacheStrategy<K,V> strategy) Invoked by the Maps.CacheMap constructor to allow a subclass to replace the strategy passed to the constructor.
protected void	entryAccessed(Maps.LinkedEntry<K,V> entry) Invoked when the value of an existing entry is accessed by Maps.AbstractHashMap.get(java.lang.Object).
protected void	entryAdded(Maps.LinkedEntry<K,V> entry) Invoked when a new entry is added to this map.
protected void	entryChanged(Maps.LinkedEntry<K,V> oldEntry, V oldValue, Maps.LinkedEntry<K,V> newEntry) Invoked when the value of an existing entry is changed.
protected void	entryEvicted(Maps.LinkedEntry<K,V> entry) Invoked when an existing entry is evicted by Maps.AbstractLinkedHashMap.evictEntry(E), e.g., because Maps.AbstractLinkedHashMap.removeEldestEntry(E) returned true.
protected void	entryPurged(Maps.LinkedEntry<K,V> entry) Invoked when an existing entry is purged by Maps.AbstractHashMap.purgeEntry(E) after its value has been garbage collected.
protected void	entryRemoved(Maps.LinkedEntry<K,V> entry) Invoked when an existing entry is removed by a remove method of this map, of a view collection of this map, or of an iterator of a view collection of this map
protected boolean	evictEntry(Maps.LinkedEntry<K,V> entry) Evicts an existing entry from this map.
protected Maps.LinkedEntry<K,V>	getEldestEntry() Gets the eldest entry in this map, or null if the map is empty.
protected void	mapChanged() Invoked when the map has changed.
protected boolean	removeEldestEntry(Maps.LinkedEntry<K,V> eldest) Gets whether to evict the eldest entry from this map.

Methods inherited from class oracle.javatools.util.Maps.AbstractLinkedHashMap

createEntryIterator, createEntrySetIterator, createKeySetIterator, createValuesIterator

Methods inherited from class oracle.javatools.util.Maps.AbstractHashMap

addEntry, capacity, change, clone, containsKey, containsValue, entrySet, equals, get, getChangeCount, getEntry, getQueue, hashCode, isEmpty, keyEquals, keyHashCode, keySet, loadFactor, mapConstructed, mapInitialized, purge, purgeEntry, put, putAll, remove, removeExistingEntry, removeKey, size, toString, valueEquals, valueHashCode, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

STRONG

public static final Maps.CacheMap.Strength STRONG

HARD

public static final Maps.CacheMap.Strength HARD

SOFT

public static final Maps.CacheMap.Strength SOFT

WEAK

public static final Maps.CacheMap.Strength WEAK

CANONICAL

public static final Maps.CacheMap.Canonicity CANONICAL

NOT_CANONICAL

public static final Maps.CacheMap.Canonicity NOT_CANONICAL

NONCANONICAL

public static final Maps.CacheMap.Canonicity NONCANONICAL

Deprecated. Use NOT_CANONICAL.

Constructor Detail

Maps.CacheMap

public Maps.CacheMap()

Constructs an unbounded, non-canonical cache map with strongly- referenced values. The initial capacity and load factor are set to Maps.AbstractHashMap.DEFAULT_INITIAL_CAPACITY and Maps.AbstractHashMap.DEFAULT_LOAD_FACTOR, respectively.

Maps.CacheMap

public Maps.CacheMap(Maps.CacheMap.Strength strength)

Constructs an unbounded, non-canonical cache map. The initial capacity and load factor are set to Maps.AbstractHashMap.DEFAULT_INITIAL_CAPACITY and Maps.AbstractHashMap.DEFAULT_LOAD_FACTOR, respectively.

Maps.CacheMap

public Maps.CacheMap(int bound)

Constructs a bounded LRU (least recently used), canonical cache map with strongly-referenced values. The initial capacity and load factor are set to default values.

Parameters:

bound - The maximum number of entries allowed in the cache.

Maps.CacheMap

public Maps.CacheMap(int bound,
                     Maps.CacheMap.Strength strength)

Constructs a bounded LRU (least recently used), canonical cache map. The initial capacity and load factor are set to default values.

Parameters:

bound - The maximum number of entries allowed in the cache.

strength - The strength of value references.

Maps.CacheMap

public Maps.CacheMap(int bound,
                     Maps.CacheMap.Canonicity canonicity)

Constructs a bounded LRU (least recently used) cache map with strongly-referenced values. The initial capacity and load factor are set to default values.

Parameters:

bound - The maximum number of entries allowed in the cache.

canonicity - Canonicity of this cache.

Maps.CacheMap

public Maps.CacheMap(Maps.CacheStrategy<K,V> strategy)

Constructs a cache map with specified Maps.CacheStrategy.

Method Detail

decoratedStrategy

protected Maps.CacheStrategy<K,V> decoratedStrategy(Maps.CacheStrategy<K,V> strategy)

Invoked by the Maps.CacheMap constructor to allow a subclass to replace the strategy passed to the constructor. The default Maps.CacheMap implementation returns the strategy passed to it.

This hook is provided to allow a subclass to decorate a strategy given to its constructor without running afoul of superclass-not- initialized issues.

Parameters:

strategy - The strategy passed to the CacheMap constructor.

Returns:

the strategy passed to the constructor or a subclass-provided replacement.

createEntry

protected final Maps.LinkedEntry<K,V> createEntry(int hashCode,
                                                  K key,
                                                  V value,
                                                  Maps.LinkedEntry<K,V> next)

Creates an entry for this map.

The Maps.CacheMap implementation delegates to Maps.CacheStrategy.createEntry(int, K, V, oracle.javatools.util.Maps.LinkedEntry, java.lang.ref.ReferenceQueue).

Specified by:

createEntry in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

Parameters:

hashCode - The hashCode of the key for this entry.

key - The key for this entry.

value - The value for this entry.

next - The entry to follow this entry in the entry chain.

mapChanged

protected final void mapChanged()

Description copied from class: Maps.AbstractLinkedHashMap

Invoked when the map has changed. After the map is initialized (see Maps.AbstractHashMap.mapInitialized()), it only changes when the map is cleared or when entries are added, removed, or purged. In the latter cases, this method is invoked before the corresponding Maps.AbstractHashMap.entryAdded(E), Maps.AbstractHashMap.entryRemoved(E) or Maps.AbstractHashMap.entryPurged(E) method.

The Maps.AbstractHashMap implementation does nothing.

For subclasses of Maps.AbstractLinkedHashMap, this method is also invoked when iteration order is by access and an entry is accessed. This method is invoked before the associated Maps.AbstractHashMap.entryAccessed(E) method is invoked.

The Maps.AbstractLinkedHashMap implementation does nothing.

Overrides:

mapChanged in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

entryAdded

protected final void entryAdded(Maps.LinkedEntry<K,V> entry)

Description copied from class: Maps.AbstractHashMap

Invoked when a new entry is added to this map. After the map is initialized (see Maps.AbstractHashMap.mapInitialized()), entries are only added by Maps.AbstractHashMap.put(K, V).

The Maps.AbstractHashMap implementation does nothing.

Overrides:

entryAdded in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

entryChanged

protected final void entryChanged(Maps.LinkedEntry<K,V> oldEntry,
                                  V oldValue,
                                  Maps.LinkedEntry<K,V> newEntry)

Description copied from class: Maps.AbstractHashMap

Invoked when the value of an existing entry is changed. After the map is initialized (see Maps.AbstractHashMap.mapInitialized()), entries are only changed by Maps.AbstractHashMap.put(K, V).

If the entry to change was mutable, its value is changed with Map.Entry#setValue and oldEntry and newEntry are the same object. If the entry to change was not mutable, a new entry must be created and oldEntry and newEntry are different objects.

When a client directly invokes the Map.Entry#setValue method of any of the Map.Entry implementations provided in this class, this method is not invoked (while this could be addressed, it would require each entry instance to hold a reference to its map).

The Maps.AbstractHashMap implementation does nothing.

Overrides:

entryChanged in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

Parameters:

oldEntry - The existing entry that changed.

oldValue - The old value of the entry.

newEntry - The new entry, which may be the same as the old.

entryAccessed

protected final void entryAccessed(Maps.LinkedEntry<K,V> entry)

Description copied from class: Maps.AbstractHashMap

Invoked when the value of an existing entry is accessed by Maps.AbstractHashMap.get(java.lang.Object). Access to an entry by iterating a view collection of this map does not cause this method to be invoked.

The Maps.AbstractHashMap implementation does nothing.

Overrides:

entryAccessed in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

entryRemoved

protected final void entryRemoved(Maps.LinkedEntry<K,V> entry)

Description copied from class: Maps.AbstractHashMap

Invoked when an existing entry is removed by a remove method of this map, of a view collection of this map, or of an iterator of a view collection of this map

The Maps.AbstractHashMap implementation never invokes Maps.AbstractHashMap.entryRemoved(E) when entries are removed by the Maps.AbstractHashMap.clear() method of this map, or of a view collection of this map.

The Maps.AbstractHashMap implementation does nothing.

Overrides:

entryRemoved in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

entryPurged

protected final void entryPurged(Maps.LinkedEntry<K,V> entry)

Description copied from class: Maps.AbstractHashMap

Invoked when an existing entry is purged by Maps.AbstractHashMap.purgeEntry(E) after its value has been garbage collected.

The Maps.AbstractHashMap implementation only ever invokes Maps.AbstractHashMap.entryPurged(E) for entries which extend SoftReference or WeakReference and which register themselves with the ReferenceQueue returned by Maps.AbstractHashMap.getQueue(). Maps provides four such classes: Maps.SoftEntry, Maps.WeakEntry, Maps.SoftLinkedEntry, and Maps.WeakLinkedEntry.

The Maps.AbstractHashMap implementation does nothing.

Overrides:

entryPurged in class Maps.AbstractHashMap<K,V,Maps.LinkedEntry<K,V>>

entryEvicted

protected final void entryEvicted(Maps.LinkedEntry<K,V> entry)

Invoked when an existing entry is evicted by Maps.AbstractLinkedHashMap.evictEntry(E), e.g., because Maps.AbstractLinkedHashMap.removeEldestEntry(E) returned true.

The Maps.AbstractLinkedHashMap implementation does nothing.

If this map is canonical, eviction means the entry was converted to a weak reference and mapChanged() was not invoked. If this map is not canonical, eviction means the entry was removed and mapChanged() was invoked.

Overrides:

entryEvicted in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

removeEldestEntry

protected final boolean removeEldestEntry(Maps.LinkedEntry<K,V> eldest)

Gets whether to evict the eldest entry from this map. Invoked when an entry is added to the cache, after Maps.AbstractHashMap.entryAdded(E) is invoked. If Maps.AbstractHashMap.entryAdded(E) modifies the map, however, this method is not invoked. The removal of the entry, if requested, causes the Maps.AbstractLinkedHashMap.entryEvicted(E) method to be invoked, rather than the Maps.AbstractHashMap.entryRemoved(E) method.

The Maps.AbstractLinkedHashMap implementation returns false.

In an insertion-ordered map, the eldest entry is the least recently inserted one; in an access-ordered map, it is the least recently accessed entry.

This method is provided for compatibility with LinkedHashMap.removeEldestEntry(java.util.Map.Entry).

The Maps.CacheMap implementation returns false, like its superclass. It is overridden here only to make it final; use a Maps.CacheStrategy to determine the eviction strategy.

Overrides:

removeEldestEntry in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

Parameters:

eldest - The eldest entry in the map.

Returns:

whether the eldest entry should be evicted.

getEldestEntry

protected Maps.LinkedEntry<K,V> getEldestEntry()

Description copied from class: Maps.AbstractLinkedHashMap

Gets the eldest entry in this map, or null if the map is empty.

In an insertion-ordered map, the eldest entry is the least recently inserted one; in an access-ordered map, it is the least recently accessed entry.

The Maps.AbstractLinkedHashMap implementation does nothing.

Overrides:

getEldestEntry in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

evictEntry

protected final boolean evictEntry(Maps.LinkedEntry<K,V> entry)

Evicts an existing entry from this map. This method matches entries using object identity ("==") on them.

The Maps.CacheMap implementation ensures that, if this map is canonical, the mapping represented by the evicted entry is retained for as long as an external reference to the value exists.

Overrides:

evictEntry in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>

Parameters:

entry - The entry to evict.

Returns:

whether the entry was actually evicted.

clear

public void clear()

Description copied from class: Maps.AbstractLinkedHashMap

Removes all mappings from this map.

Overridden to reset the iteration list.

Specified by:

clear in interface java.util.Map<K,V>

Overrides:

clear in class Maps.AbstractLinkedHashMap<K,V,Maps.LinkedEntry<K,V>>