com.grey.base.collections

Class HashedMapEntries<K,V>

java.lang.Object

com.grey.base.collections.HashedMapEntries<K,V>

All Implemented Interfaces:

Map<K,V>

public final class HashedMapEntries<K,V>
extends Object
implements Map<K,V>

This class implements the Map interface, and serves as a zero-garbage replacement for the JRE's HashMap class.
This class may be preferable to the JRE-provided HashMap for high-frequency caches with short-lived entries, as the JRE class not only allocates new memory (in the shape of the Entry class, a linked list of which is rooted in each table slot) when inserting each new key, but also releases that memory when the key is removed. The standard HashMap would therefore generate too much garbage in such a scenario, whereas this class never frees its own memory (though it does of course free its references to deleted key/value pairs) and keeps empty bucket positions available for re-use.

In general, the HashedMap class should be preferred to this one, as it has a smaller memory footprint, less indirection and better locality of reference.
However that class reuses objects when iterating on the entrySet() view and while that is perfectly valid, this class provides a safe option for badly written applications which can't handle that.

Like the JRE's HashMap, this class implements all optional Map operations.
Beware that this class is single-threaded and non-reentrant.

Discussion on reuse of Map.Entry nodes:
You should note that the Map.Entry objects returned by this class's iterator are no longer valid once their key has been deleted, as they will then be nulled and recycled for use by other keys.
This is is not in breach of the required Map interface, but it is at variance with the behaviour of some other Maps such as the JDK's java.util.HashMap (whose returned Map.Entry objects are dedicated to their key in perpetuity).
Map.Entry has this to say:
(i) "Map.Entry objects are valid only for the duration of the iteration" (ii) "the behavior of a map entry is undefined if the backing map has been modified after the entry was returned by the iterator, except through the setValue operation on the map entry"
FindBugs takes both sides, with PZ_DONT_REUSE_ENTRY_OBJECTS_IN_ITERATORS warning Map implementors not to reuse Map.Entry objects and DMI_ENTRY_SETS_MAY_REUSE_ENTRY_OBJECTS warning Map users to beware that Map.Entry objects might mutate unexpectedly.
The HashedMapEntries class is therefore in compliance. It reuses Map.Entry objects only if their key has been deleted, and not under any other circumstances. It also returns long-lived (ie. will not be recycled) Map.Entry nodes in the entrySet() view's toArray() methods, as required by the Java Map spec.

See Also:

HashedMap

Nested Class Summary

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

Map.Entry<K,V>

Constructor Summary

Constructors

Modifier	Constructor and Description
	HashedMapEntries()
	HashedMapEntries(int initcap)
protected	HashedMapEntries(int initcap, float factor)

Method Summary

Modifier and Type	Method and Description
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object val)
Iterator<Map.Entry<K,V>>	entriesIterator() This returns a recycled Map.Entry iterator. Whereas entrySet().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object. This is not a standard Map method, and is obviously unsuitable for multi-threaded use.
Set<Map.Entry<K,V>>	entrySet()
V	get(Object key)
boolean	isEmpty()
Set<K>	keySet()
Iterator<K>	keysIterator() This returns a recycled keys iterator. Whereas keySet().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object. This is not a standard Map method, and is obviously unsuitable for multi-threaded use.
V	put(K key, V value)
void	putAll(Map<? extends K,? extends V> srcmap)
V	remove(Object key)
int	size()
String	toString()
int	trimToSize()
Collection<V>	values()
Iterator<V>	valuesIterator() This returns a recycled values iterator. Whereas values().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object. This is not a standard Map method, and is obviously unsuitable for multi-threaded use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, equals, forEach, getOrDefault, hashCode, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

HashedMapEntries

public HashedMapEntries()

HashedMapEntries

public HashedMapEntries(int initcap)

HashedMapEntries

protected HashedMapEntries(int initcap,
                           float factor)

Method Detail

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

size

public int size()

Specified by:

size in interface Map<K,V>

clear

public void clear()

Specified by:

clear in interface Map<K,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

put

public V put(K key,
             V value)

Specified by:

put in interface Map<K,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<K,V>

containsValue

public boolean containsValue(Object val)

Specified by:

containsValue in interface Map<K,V>

putAll

public void putAll(Map<? extends K,? extends V> srcmap)

Specified by:

putAll in interface Map<K,V>

trimToSize

public int trimToSize()

toString

public String toString()

Overrides:

toString in class Object

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

entrySet

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

Specified by:

entrySet in interface Map<K,V>

keysIterator

public Iterator<K> keysIterator()

This returns a recycled keys iterator.
Whereas keySet().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object.
This is not a standard Map method, and is obviously unsuitable for multi-threaded use.

Returns:

The reusable keys iterator. It is created on the first call to this method.

valuesIterator

public Iterator<V> valuesIterator()

This returns a recycled values iterator.
Whereas values().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object.
This is not a standard Map method, and is obviously unsuitable for multi-threaded use.

Returns:

The reusable values iterator. It is created on the first call to this method.

entriesIterator

public Iterator<Map.Entry<K,V>> entriesIterator()

This returns a recycled Map.Entry iterator.
Whereas entrySet().iterator() creates a new Iterator object, this method returns a single instance of that iterator type, that is associated with this Map object.
This is not a standard Map method, and is obviously unsuitable for multi-threaded use.

Returns:

The reusable entries iterator. It is created on the first call to this method.