oracle.javatools.util

Class Maps.AbstractHashMap<K,V,E extends Maps.BaseEntry<K,V>>

java.lang.Object

oracle.javatools.util.Maps.AbstractHashMap<K,V,E>

All Implemented Interfaces:

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

Direct Known Subclasses:

Maps.AbstractLinkedHashMap, Maps.SoftHashMap, Maps.StrongHashMap, Maps.WeakHashMap

Enclosing class:

Maps

public abstract static class Maps.AbstractHashMap<K,V,E extends Maps.BaseEntry<K,V>>
extends java.lang.Object
implements java.util.Map<K,V>, java.lang.Cloneable, java.io.Serializable

An abstract, but nearly complete, implementation of the Map interface that is functionally equivalent to HashMap but that allows subclasses to do any or all of the following:

• control the concrete class of Map.Entry instances used so long as they extend Maps.BaseEntry (see createEntry(int, K, V, E));
• override the calculation of hashCode and equals for all keys (see keyHashCode(java.lang.Object) and keyEquals(java.lang.Object, java.lang.Object));
• override the calculation of hashCode and equals for all values (see valueHashCode(java.lang.Object) and valueEquals(java.lang.Object, java.lang.Object));
• track when the map is constructed, initialized, and changed (see mapConstructed(), mapInitialized(), and mapChanged()).
• track when entries are added, changed, accessed, and removed (see entryAdded(E), entryChanged(E, V, E), entryAccessed(E), entryRemoved(E)).
• track when, for entries which hold their values through soft or weak references, values are garbage collected (see entryPurged(E)).

The only method that a concrete subclass must override is createEntry(int, K, V, E).

Notes
If a subclass maintains state which is updated when entries are added and that state requires initialization of any kind, that initialization should be done in mapConstructed(), not in the subclass constructor.

If overriding any of the value or key hashCode and equals methods, be aware that the usual consistency requirements between hash code and equality continue to apply. Also, while the entrySet view uses the map's overridden implementations, invoking hashCode or equals directly on an entry obtained from the entry set will not use the overridden implementations (the entry does not have a reference to the map to gain access to them).

See Also:

Serialized Form

Nested Class Summary

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

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

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_INITIAL_CAPACITY The default initial capacity.
static float	DEFAULT_LOAD_FACTOR The default load factor.
static int	MAXIMUM_CAPACITY The maximum capacity, used if a higher value is explicitly specified by either of the constructors with arguments.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Maps.AbstractHashMap(int initialCapacity, float loadFactor, java.util.Map<? extends K,? extends V> map) Constructs a map.
protected	Maps.AbstractHashMap(java.util.Map<? extends K,? extends V> map) Constructs a map with specified initial mappings, initial capacity based on the number of initial mappings, and default load factor.

Method Summary

Methods

Modifier and Type	Method and Description
protected V	addEntry(K key, V value) Creates an entry and add it to the map.
protected int	capacity()
protected void	change() Increment the change count.
void	clear() Removes all mappings from this map.
java.lang.Object	clone() Returns a shallow copy of this HashMap instance: the keys and values themselves are not cloned.
boolean	containsKey(java.lang.Object key) Returns true if this map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Gets whether this map maps at least one key to the specified value.
protected abstract E	createEntry(int hashCode, K key, V value, E next) Creates an entry for this map.
protected java.util.Iterator<E>	createEntryIterator() Gets an iterator through all the entries of the map.
protected java.util.Iterator<java.util.Map.Entry<K,V>>	createEntrySetIterator() Gets an iterator through all the entries of the map.
protected java.util.Iterator<K>	createKeySetIterator() Gets an iterator through all the keys of all the entries of the map.
protected java.util.Iterator<V>	createValuesIterator() Gets an iterator through all the values of all the entries of the map.
protected void	entryAccessed(E entry) Invoked when the value of an existing entry is accessed by get(java.lang.Object).
protected void	entryAdded(E entry) Invoked when a new entry is added to this map.
protected void	entryChanged(E oldEntry, V oldValue, E newEntry) Invoked when the value of an existing entry is changed.
protected void	entryPurged(E entry) Invoked when an existing entry is purged by purgeEntry(E) after its value has been garbage collected.
protected void	entryRemoved(E 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
java.util.Set<java.util.Map.Entry<K,V>>	entrySet() Gets a collection view of the mappings contained in this map.
boolean	equals(java.lang.Object object) Compares the specified object with this map for equality.
V	get(java.lang.Object key) Gets the value from the mapping for a key in this map, or null if the key is not mapped.
protected int	getChangeCount() Gets the current change count.
protected E	getEntry(java.lang.Object key) Gets the entry from the map with the specified key, or null if none.
protected java.lang.ref.ReferenceQueue<V>	getQueue() Gets the reference queue used by purge().
int	hashCode() Returns the hash code value for this map.
boolean	isEmpty() Gets whether this map is empty.
protected boolean	keyEquals(java.lang.Object key1, java.lang.Object key2) Gets whether two keys are equal.
protected int	keyHashCode(java.lang.Object key) Gets the hash code for a key.
java.util.Set<K>	keySet() Gets a set view of the keys contained in this map.
protected float	loadFactor()
protected void	mapChanged() Invoked when the map has changed.
protected void	mapConstructed() Invoked after the map has been constructed but before initial mappings, if any, are added.
protected void	mapInitialized() Invoked after the map has been constructed and initial mappings have been added.
protected void	purge() Purges stale entries from the map.
protected void	purgeEntry(E entry) Purges an existing entry from this map.
V	put(K key, V value) Puts a mapping from key to value into this map.
void	putAll(java.util.Map<? extends K,? extends V> map) Puts all the mappings of a map into this map.
V	remove(java.lang.Object key) Removes the mapping for a key from this map and gets the value that was mapped from the key, or null if none.
protected void	removeExistingEntry(E entry) Removes an existing entry from this map.
protected E	removeKey(java.lang.Object key, java.util.Map.Entry<K,V> optionalEntryWithValue) Removes the entry with a key from this map and returns the entry removed, or null if no entry is removed.
int	size() Gets the number of mappings in this map.
java.lang.String	toString()
protected boolean	valueEquals(java.lang.Object value1, java.lang.Object value2) Gets whether two values are equal.
protected int	valueHashCode(java.lang.Object value) Gets the hash code for a value.
java.util.Collection<V>	values() Gets a collection view of the values contained in this map.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_INITIAL_CAPACITY

public static final int DEFAULT_INITIAL_CAPACITY

The default initial capacity. MUST be a power of two.

See Also:

Constant Field Values

MAXIMUM_CAPACITY

public static final int MAXIMUM_CAPACITY

The maximum capacity, used if a higher value is explicitly specified by either of the constructors with arguments. MUST be a power of two <= 1<<30.

See Also:

Constant Field Values

DEFAULT_LOAD_FACTOR

public static final float DEFAULT_LOAD_FACTOR

The default load factor.

See Also:

Constant Field Values

Constructor Detail

Maps.AbstractHashMap

protected Maps.AbstractHashMap(int initialCapacity,
                    float loadFactor,
                    java.util.Map<? extends K,? extends V> map)

Constructs a map.

Parameters:

initialCapacity - The initial capacity. A reasonable default is DEFAULT_INITIAL_CAPACITY.

loadFactor - The load factor. A reasonable default is DEFAULT_LOAD_FACTOR

map - A map providing initial mappings. Use null or an empty map if none required.

Throws:

java.lang.IllegalArgumentException - if the initial capacity is negative or the load factor is nonpositive.

Maps.AbstractHashMap

protected Maps.AbstractHashMap(java.util.Map<? extends K,? extends V> map)

Constructs a map with specified initial mappings, initial capacity based on the number of initial mappings, and default load factor.

Parameters:

map - A map providing initial mappings.

Throws:

java.lang.NullPointerException - if the specified map is null.

Method Detail

createEntry

protected abstract E createEntry(int hashCode,
            K key,
            V value,
            E next)

Creates an entry for this map.

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.

keyHashCode

protected int keyHashCode(java.lang.Object key)

Gets the hash code for a key. The Maps.AbstractHashMap implementation returns key.hashCode().

Parameters:

key - A non-null key object.

keyEquals

protected boolean keyEquals(java.lang.Object key1,
                java.lang.Object key2)

Gets whether two keys are equal. The Maps.AbstractHashMap implementation returns key1 == key2 || key1.equals(key2).

Parameters:

key1 - A non-null key object.

key2 - A potentially null key object.

valueHashCode

protected int valueHashCode(java.lang.Object value)

Gets the hash code for a value. The Maps.AbstractHashMap implementation returns value.hashCode().

Parameters:

value - A non-null value object.

valueEquals

protected boolean valueEquals(java.lang.Object value1,
                  java.lang.Object value2)

Gets whether two values are equal. The default Maps.AbstractHashMap implementation returns value1 == value2 || value1.equals(value2).

Parameters:

value1 - A non-null value object.

value2 - A potentially null value object.

purge

protected void purge()

Purges stale entries from the map. Invoked by most map methods before the structure is accessed, so subclass extensions of this method should avoid potentially expensive operations such as scanning all entries in the map.

The Maps.AbstractHashMap implementation removes any entries that have been enqueued on the reference queue returned by getQueue().

getQueue

protected final java.lang.ref.ReferenceQueue<V> getQueue()

Gets the reference queue used by purge().

mapConstructed

protected void mapConstructed()

Invoked after the map has been constructed but before initial mappings, if any, are added. Beware, this method is called before the subclass constructor is called.

Subclass state that is accessed by, for example put(K, V), should be initialized in the subclass mapConstructed() method instead of in the subclass constructor, because mapConstructed() is called before the initial entries are added to the map, whereas the subclass constructor does not get invoked until afterwards (i.e., too late).

The Maps.AbstractHashMap implementation does nothing.

mapInitialized

protected void mapInitialized()

Invoked after the map has been constructed and initial mappings have been added. After this point, entries are only added or changed by put(K, V). Beware, this method is called before the subclass constructor is called.

The Maps.AbstractHashMap implementation does nothing.

mapChanged

protected void mapChanged()

Invoked when the map has changed. After the map is initialized (see 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 entryAdded(E), entryRemoved(E) or entryPurged(E) method.

The Maps.AbstractHashMap implementation does nothing.

entryAdded

protected void entryAdded(E entry)

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

The Maps.AbstractHashMap implementation does nothing.

entryChanged

protected void entryChanged(E oldEntry,
                V oldValue,
                E newEntry)

Invoked when the value of an existing entry is changed. After the map is initialized (see mapInitialized()), entries are only changed by 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.

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 void entryAccessed(E entry)

Invoked when the value of an existing entry is accessed by 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.

entryRemoved

protected void entryRemoved(E 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

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

The Maps.AbstractHashMap implementation does nothing.

entryPurged

protected void entryPurged(E entry)

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

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

The Maps.AbstractHashMap implementation does nothing.

size

public int size()

Gets the number of mappings in this map.

Specified by:

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

isEmpty

public boolean isEmpty()

Gets whether this map is empty.

Specified by:

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

get

public V get(java.lang.Object key)

Gets the value from the mapping for a key in this map, or null if the key is not mapped. If necessary to distinguish between an unmapped key and a key explicitly mapped to null, use containsKey(java.lang.Object).

Specified by:

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

Parameters:

key - A key mapped in this map.

Returns:

The value to which the key is mapped, or null if none.

put

public V put(K key,
    V value)

Puts a mapping from key to value into this map. If the map already has a mapping for the key, that mapping is replaced.

Specified by:

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

Parameters:

key - The key to map.

value - The value to which to map the key.

Returns:

The value of the previous mapping for the key, or null if none.

putAll

public void putAll(java.util.Map<? extends K,? extends V> map)

Puts all the mappings of a map into this map. Any mappings in this map with the same key as one of the mappings being added is replaced.

Specified by:

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

Parameters:

map - mappings to put into this map.

Throws:

java.lang.NullPointerException - if the map is null.

remove

public V remove(java.lang.Object key)

Removes the mapping for a key from this map and gets the value that was mapped from the key, or null if none.

Specified by:

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

Parameters:

key - A key mapped in this map.

Returns:

The value to which the key is mapped, or null if none.

clear

public void clear()

Removes all mappings from this map.

Specified by:

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

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this map contains a mapping for the specified key.

Specified by:

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

Parameters:

key - The key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key.

containsValue

public boolean containsValue(java.lang.Object value)

Gets whether this map maps at least one key to the specified value.

Specified by:

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

Parameters:

value - value for which to test.

keySet

public java.util.Set<K> keySet()

Gets a set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

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

Returns:

a set view of the keys contained in this map.

values

public java.util.Collection<V> values()

Gets a collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Collection.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

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

Returns:

a collection view of the values contained in this map.

entrySet

public java.util.Set<java.util.Map.Entry<K,V>> entrySet()

Gets a collection view of the mappings contained in this map. Each element in the returned collection is a Map.Entry. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Specified by:

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

Returns:

a collection view of the mappings contained in this map.

See Also:

Map.Entry

clone

public java.lang.Object clone()

Returns a shallow copy of this HashMap instance: the keys and values themselves are not cloned.

Overrides:

clone in class java.lang.Object

Returns:

a shallow copy of this map.

equals

public boolean equals(java.lang.Object object)

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings. More formally, two maps t1 and t2 represent the same mappings if t1.keySet().equals(t2.keySet()) and for every key k in t1.keySet(), (t1.get(k)==null ? t2.get(k)==null : t1.get(k).equals(t2.get(k))) . This ensures that the equals method works properly across different implementations of the map interface.

This implementation first checks if the specified object is this map; if so it returns true. Then, it checks if the specified object is a map whose size is identical to the size of this set; if not, it returns false. If so, it iterates over this map's entrySet collection, and checks that the specified map contains each mapping that this map contains. If the specified map fails to contain such a mapping, false is returned. If the iteration completes, true is returned.

Specified by:

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

Overrides:

equals in class java.lang.Object

Parameters:

object - object to be compared for equality with this map.

Returns:

true if the specified object is equal to this map.

hashCode

public int hashCode()

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view. This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode() for any two maps t1 and t2, as required by the general contract of Object.hashCode.

This implementation iterates over entrySet(), calling hashCode on each element (entry) in the Collection, and adding up the results.

Specified by:

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

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value for this map.

See Also:

Map.Entry#hashCode(), Object.hashCode(), Object.equals(Object), Set.equals(Object)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

change

protected void change()

Increment the change count.

See Also:

getChangeCount(), mapChanged()

getChangeCount

protected int getChangeCount()

Gets the current change count. During construction and initialization of the map, the change count is -1, immediately after initialization it is zero, and it increments thereafter.

See Also:

change();

createEntryIterator

protected java.util.Iterator<E> createEntryIterator()

Gets an iterator through all the entries of the map. The Maps.AbstractHashMap implementation returns an instance of AbstractEntryIterator. A subclass would typically override this only if it had access to a more efficient iterator implementation.

createEntrySetIterator

protected java.util.Iterator<java.util.Map.Entry<K,V>> createEntrySetIterator()

Gets an iterator through all the entries of the map. The Maps.AbstractHashMap implementation returns an instance of AbstractEntryIterator. A subclass would typically override this only if it had access to a more efficient iterator implementation.

createKeySetIterator

protected java.util.Iterator<K> createKeySetIterator()

Gets an iterator through all the keys of all the entries of the map. The Maps.AbstractHashMap implementation returns an instance of AbstractEntryIterator. A subclass would typically override this only if it had access to a more efficient iterator implementation.

createValuesIterator

protected java.util.Iterator<V> createValuesIterator()

Gets an iterator through all the values of all the entries of the map. The Maps.AbstractHashMap implementation returns an instance of AbstractEntryIterator. A subclass would typically override this only if it had access to a more efficient iterator implementation.

addEntry

protected V addEntry(K key,
         V value)

Creates an entry and add it to the map.

Parameters:

key - The key for the entry to create.

value - The value for the entry to create.

getEntry

protected E getEntry(java.lang.Object key)

Gets the entry from the map with the specified key, or null if none.

removeKey

protected E removeKey(java.lang.Object key,
          java.util.Map.Entry<K,V> optionalEntryWithValue)

Removes the entry with a key from this map and returns the entry removed, or null if no entry is removed. Normally, an entry with the same key is removed outright. However, in support of the EntrySet#remove method, if entry is not null, then the entry values must additionally be equal, as determined by the valueEquals(java.lang.Object, java.lang.Object) method, for an entry to be removed.

Parameters:

key - The key for the entry to remove.

optionalEntryWithValue - An entry containing the value to match, or null if none.

Returns:

the entry removed, or null if no entry is removed.

removeExistingEntry

protected void removeExistingEntry(E entry)

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

Parameters:

entry - The entry to remove.

purgeEntry

protected void purgeEntry(E entry)

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

Parameters:

entry - The entry to remove.

capacity

protected int capacity()

loadFactor

protected float loadFactor()