org.libj.util

Class MirrorMap<K,V,R>

java.lang.Object

java.util.AbstractMap<K,V>

org.libj.util.DelegateMap<K,V>

org.libj.util.ObservableMap<K,V>

org.libj.util.MirrorMap<K,V,R>

Type Parameters:

K - The type of keys maintained by this map.

V - The type of value elements in this map.

R - The type of reflected value elements in the mirror map.

All Implemented Interfaces:

Map<K,V>

public class MirrorMap<K,V,R>
extends ObservableMap<K,V>

A map that maintains 2 representations of its key-value entries:

1. For value elements of type <V>, which is the generic type of this map.
2. For reflected elements of type <R>, which is the generic type of the map returned by getMirrorMap()

The MirrorMap.Mirror provides the V -> R and R -> V methods, which are used to reflect values from one MirrorMap to the other.

Entries added to either sides of the MirrorMap are "lazy-reflected" -- i.e. instead of reflecting entries upon their addition to the map, entries are reflected upon retrieval from the map.

The getMirrorMap() method returns the MirrorMap instance of type <K,R> that represents the one-to-one mapping with its mirror of type <K,V> (i.e. this instance). Changes to the MirrorMap will be reflected in this instance, and vice-versa.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MirrorMap.Mirror<K,V,R> Interface providing methods for the reflection of one type of object to another, and vice-versa.
protected class	MirrorMap.ObservableMirrorEntrySet

Nested classes/interfaces inherited from class org.libj.util.ObservableMap

ObservableMap.ObservableEntrySet, ObservableMap.ObservableKeySet

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

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

Map.Entry<K,V>

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	inited
protected MirrorMap<K,R,V>	mirrorMap
protected static Object	PENDING Object to be used in the underlying maps to represent that a value is pending reflection via the methods in mirror upon the invocation of beforeGet(Object).
protected Iterator<?>	targetLock

Fields inherited from class org.libj.util.ObservableMap

entrySet, keySet, values

Fields inherited from class org.libj.util.DelegateMap

target

Constructor Summary

Constructors

Modifier	Constructor and Description
	MirrorMap(Map<K,V> values, Map<K,R> reflections, MirrorMap.Mirror<K,V,R> mirror) Creates a new MirrorMap with the specified target maps and MirrorMap.Mirror.
protected	MirrorMap(MirrorMap<K,R,V> mirrorMap, Map<K,V> values, MirrorMap.Mirror<K,V,R> mirror) Creates a new MirrorMap with the specified maps and mirror.

Method Summary

Modifier and Type	Method and Description
protected void	afterContainsKey(Object key, boolean result, RuntimeException e) Callback method that is invoked immediately after a key is dereferenced for inclusion via ObservableMap.containsKey(Object).
protected void	afterContainsValue(Object value, boolean result, RuntimeException e) Callback method that is invoked immediately after a value is dereferenced for inclusion via ObservableMap.containsValue(Object).
protected void	afterGet(Object key, V value, RuntimeException e) Callback method that is invoked immediately after a value is retrieved from the enclosed Map.
protected void	afterPut(K key, V oldValue, V newValue, RuntimeException e) Callback method that is invoked immediately after an entry is put into the enclosed Map.
protected void	afterRemove(Object key, V value, RuntimeException e) Callback method that is invoked immediately after an entry is removed from the enclosed Map.
protected boolean	beforeContainsKey(Object key) Callback method that is invoked immediately before a key is dereferenced for inclusion via ObservableMap.containsKey(Object).
protected void	beforeContainsValue(Object value) Callback method that is invoked immediately before a value is dereferenced for inclusion via ObservableMap.containsValue(Object).
protected void	beforeGet(Object key) Callback method that is invoked immediately before a value is retrieved via ObservableMap.get(Object).
protected boolean	beforePut(K key, V oldValue, V newValue) Callback method that is invoked immediately before an entry is put into the enclosed Map.
protected boolean	beforeRemove(Object key, V value) Callback method that is invoked immediately before an entry is removed from the enclosed Map.
MirrorMap.Mirror<K,V,R>	getMirror() Returns the MirrorMap.Mirror for this MirrorMap.
MirrorMap<K,R,V>	getMirrorMap() Returns the MirrorMap instance of type <K,R> that represents the one-to-one mapping with its mirror of type <K,V> (i.e.
protected MirrorMap.Mirror<K,R,V>	getReverseMirror() Returns the reverse MirrorMap.Mirror for this MirrorMap, and caches it for subsequent retrieval, avoiding reinstantiation.
protected void	lock(boolean unlocked) Locks the underlying map to detect concurrent modification.
protected ObservableMap.ObservableEntrySet	newEntrySet() Factory method that returns a new instance of an ObservableMap.ObservableEntrySet.
protected MirrorMap<K,V,R>	newInstance(Map<K,V> values, Map<K,R> reflections) Factory method that returns a new instance of a MirrorMap with the specified target maps.
protected MirrorMap<K,R,V>	newMirrorInstance(Map<K,R> values) Factory method that returns a new mirror instance of a MirrorMap with the specified target map.
int	size()
protected boolean	unlock() Unlocks the underlying map and checks for concurrent modification.

Methods inherited from class org.libj.util.ObservableMap

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, keySet, merge, newKeySet, put, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, toString, values

Methods inherited from class org.libj.util.DelegateMap

isEmpty, superCompute, superComputeIfAbsent, superComputeIfPresent, superForEach, superGetOrDefault, superMerge, superPutIfAbsent, superRemove, superReplace, superReplace, superReplaceAll

Methods inherited from class java.util.AbstractMap

clone

Methods inherited from class java.lang.Object

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

Field Detail

PENDING

protected static final Object PENDING

Object to be used in the underlying maps to represent that a value is pending reflection via the methods in mirror upon the invocation of beforeGet(Object).

mirrorMap

protected MirrorMap<K,R,V> mirrorMap

targetLock

protected Iterator<?> targetLock

inited

protected boolean inited

Constructor Detail

MirrorMap

public MirrorMap(Map<K,V> values,
                 Map<K,R> reflections,
                 MirrorMap.Mirror<K,V,R> mirror)

Creates a new MirrorMap with the specified target maps and MirrorMap.Mirror. The specified target maps are meant to be empty, as they become the underlying maps of the new MirrorMap instance. The specified MirrorMap.Mirror provides the V -> R and R -> V methods, which are used to reflect object values from one MirrorMap to the other.

Parameters:

values - The underlying map of type <K,V>.

reflections - The underlying map of type <K,R>.

mirror - The MirrorMap.Mirror specifying the V -> R and R -> V methods.

Throws:

NullPointerException - If any of the specified parameters is null.

MirrorMap

protected MirrorMap(MirrorMap<K,R,V> mirrorMap,
                    Map<K,V> values,
                    MirrorMap.Mirror<K,V,R> mirror)

Creates a new MirrorMap with the specified maps and mirror. This method is specific for the construction of a reflected MirrorMap instance.

Parameters:

mirrorMap - The MirrorMap for which this map will be a reflection. Likewise, this map will be a reflection for mirrorMap.

values - The underlying map of type <K,V>.

mirror - The MirrorMap.Mirror specifying the V -> R and R -> V methods.

Method Detail

newInstance

protected MirrorMap<K,V,R> newInstance(Map<K,V> values,
                                       Map<K,R> reflections)

Factory method that returns a new instance of a MirrorMap with the specified target maps. This method is intended to be overridden by subclasses in order to provide instances of the subclass.

Parameters:

values - The underlying map of type <K,V>.

reflections - The underlying map of type <K,R>.

Returns:

A new instance of a MirrorMap with the specified target maps.

newMirrorInstance

protected MirrorMap<K,R,V> newMirrorInstance(Map<K,R> values)

Factory method that returns a new mirror instance of a MirrorMap with the specified target map. This method is intended to be overridden by subclasses in order to provide instances of the subclass.

Parameters:

values - The underlying map of type <K,V>.

Returns:

A new instance of a MirrorMap with the specified target maps.

newEntrySet

protected ObservableMap.ObservableEntrySet newEntrySet()

Description copied from class: ObservableMap

Factory method that returns a new instance of an ObservableMap.ObservableEntrySet. This method is intended to be overridden by subclasses in order to provide instances of the subclass.

Overrides:

newEntrySet in class ObservableMap<K,V>

Returns:

A new instance of an ObservableMap.ObservableEntrySet.

getMirrorMap

public MirrorMap<K,R,V> getMirrorMap()

Returns the MirrorMap instance of type <K,R> that represents the one-to-one mapping with its mirror of type <K,V> (i.e. this instance). Changes to the MirrorMap will be reflected in this instance, and vice-versa.

Returns:

The MirrorMap instance of type <K,R> that retains the one-to-one mapping with its mirror of type <K,V> (i.e. this instance).

getMirror

public MirrorMap.Mirror<K,V,R> getMirror()

Returns the MirrorMap.Mirror for this MirrorMap.

Returns:

The MirrorMap.Mirror for this MirrorMap.

getReverseMirror

protected MirrorMap.Mirror<K,R,V> getReverseMirror()

Returns the reverse MirrorMap.Mirror for this MirrorMap, and caches it for subsequent retrieval, avoiding reinstantiation.

Returns:

The reverse MirrorMap.Mirror for this MirrorMap.

lock

protected void lock(boolean unlocked)

Locks the underlying map to detect concurrent modification. Specifically, this method calls target.entrySet().iterator() and saves its reference for examination during the next method call that is made to the MirrorMap. If the call to Iterator.next() on the saved iterator results in a ConcurrentModificationException, it means that the underlying map was modified outside of the MirrorMap. Such modifications are not allowed, because they risk compromising the data integrity of the this map and its mirrorMap.

Parameters:

unlocked - If true, this map is unlocked and will be locked; if false, this map is already locked and will not be relocked.

unlock

protected boolean unlock()
                  throws ConcurrentModificationException

Unlocks the underlying map and checks for concurrent modification. Specifically, this method calls Iterator.next() on targetLock, which may result in a ConcurrentModificationException if the underlying map was modified outside of this MirrorMap.

Returns:

Whether this map was locked prior to the execution of this method.

Throws:

ConcurrentModificationException - If the underlying map was modified outside of the MirrorMap

size

public int size()

Specified by:

size in interface Map<K,V>

Overrides:

size in class DelegateMap<K,V>

beforePut

protected boolean beforePut(K key,
                            V oldValue,
                            V newValue)

Description copied from class: ObservableMap

Callback method that is invoked immediately before an entry is put into the enclosed Map.

Overrides:

beforePut in class ObservableMap<K,V>

Parameters:

key - The key of the entry to be added to the enclosed Map.

oldValue - The old value to be replaced for the key in the enclosed Map, or null if there was no existing value for the key.

newValue - The new value to be put for the key in the enclosed Map.

Returns:

If this method returns false, the subsequent put operation will not be performed; otherwise, the operation will be performed.

afterPut

protected void afterPut(K key,
                        V oldValue,
                        V newValue,
                        RuntimeException e)

Description copied from class: ObservableMap

Callback method that is invoked immediately after an entry is put into the enclosed Map.

Overrides:

afterPut in class ObservableMap<K,V>

Parameters:

key - The key of the entry to be added to the enclosed Map.

oldValue - The old value to be replaced for the key in the enclosed Map, or null if there was no existing value for the key.

newValue - The new value to be put for the key in the enclosed Map.

e - A RuntimeException that occurred during the put operation, or null if no exception occurred.

beforeRemove

protected boolean beforeRemove(Object key,
                               V value)

Description copied from class: ObservableMap

Callback method that is invoked immediately before an entry is removed from the enclosed Map.

Overrides:

beforeRemove in class ObservableMap<K,V>

Parameters:

key - The key of the entry to be removed from the enclosed Map.

value - The value for the key to be removed in the enclosed Map, or null if there was no existing value for the key.

Returns:

If this method returns false, the subsequent remove operation will not be performed; otherwise, the operation will be performed.

afterRemove

protected void afterRemove(Object key,
                           V value,
                           RuntimeException e)

Description copied from class: ObservableMap

Callback method that is invoked immediately after an entry is removed from the enclosed Map.

Overrides:

afterRemove in class ObservableMap<K,V>

Parameters:

key - The key of the entry to be removed from the enclosed Map.

value - The value for the key to be removed in the enclosed Map, or null if there was no existing value for the key.

e - A RuntimeException that occurred during the remove operation, or null if no exception occurred.

beforeContainsKey

protected boolean beforeContainsKey(Object key)

Description copied from class: ObservableMap

Callback method that is invoked immediately before a key is dereferenced for inclusion via ObservableMap.containsKey(Object).

Overrides:

beforeContainsKey in class ObservableMap<K,V>

Parameters:

key - The key to be dereferenced for inclusion.

Returns:

If this method returns false, the subsequent ObservableMap.containsKey(Object) operation immediately return false; otherwise, the operation will be performed in regular fashion.

afterContainsKey

protected void afterContainsKey(Object key,
                                boolean result,
                                RuntimeException e)

Description copied from class: ObservableMap

Callback method that is invoked immediately after a key is dereferenced for inclusion via ObservableMap.containsKey(Object).

Overrides:

afterContainsKey in class ObservableMap<K,V>

Parameters:

key - The key dereferenced for inclusion.

result - The result returned by ObservableMap.containsKey(Object).

e - A RuntimeException that occurred during the get operation, or null if no exception occurred.

beforeContainsValue

protected void beforeContainsValue(Object value)

Description copied from class: ObservableMap

Callback method that is invoked immediately before a value is dereferenced for inclusion via ObservableMap.containsValue(Object).

Overrides:

beforeContainsValue in class ObservableMap<K,V>

Parameters:

value - The key to be dereferenced for inclusion.

afterContainsValue

protected void afterContainsValue(Object value,
                                  boolean result,
                                  RuntimeException e)

Description copied from class: ObservableMap

Callback method that is invoked immediately after a value is dereferenced for inclusion via ObservableMap.containsValue(Object).

Overrides:

afterContainsValue in class ObservableMap<K,V>

Parameters:

value - The value dereferenced for inclusion.

result - The result returned by ObservableMap.containsValue(Object).

e - A RuntimeException that occurred during the get operation, or null if no exception occurred.

beforeGet

protected void beforeGet(Object key)

Description copied from class: ObservableMap

Callback method that is invoked immediately before a value is retrieved via ObservableMap.get(Object).

Overrides:

beforeGet in class ObservableMap<K,V>

Parameters:

key - The key whose associated value is to be retrieved.

afterGet

protected void afterGet(Object key,
                        V value,
                        RuntimeException e)

Description copied from class: ObservableMap

Callback method that is invoked immediately after a value is retrieved from the enclosed Map.

Overrides:

afterGet in class ObservableMap<K,V>

Parameters:

key - The key whose associated value is to be retrieved.

value - The value retrieved via ObservableMap.get(Object).

e - A RuntimeException that occurred during the get operation, or null if no exception occurred.