org.decisiondeck.xmcda_oo.utils
Class SharedDirector<K,V>

java.lang.Object
  org.decisiondeck.xmcda_oo.utils.SharedDirector<K,V>

Type Parameters:

K - the key type.

V - the value type. The Object.equals(Object) method of that class is used to test for shared value.

public class SharedDirector<K,V>
extends Object

Maintains a map of (key, value) pairs, together with a virtual value called shared. A value can have a special state called empty, the state it has when it has just been created. When all values in the map are equal they are said to be shared.

The Object.equals(Object) method is used to define the equality relation on the set of values.

This object must be associated with a factory permitting to create new value objects and copies of existing value objects.

This object exposes a special value called shared that can be read and written. When read, and the values are shared, the special value shared is equal to that shared value. When they are not, the special value shared is empty. As a particular case, when this object holds no values, they are said to be shared, and the shared object can hold a different value (the user may set a value to the shared value even when this object holds no other values). Writing to the shared value amounts to change every value in the map. More precisely, it amounts to erase every possibly previously set value and replace it with the shared value. However the user must take care to call updateShared() after updating the shared value for this object to update everything properly. Similarily, it must call one of the put methods after having updated any value in the map.

To spare some memory and improve performance, it is also possible to associate some keys with the special values empty (i.e. the value is as if it was just created) or shared (i.e. that value is the same as the value of shared at the time the method is called). Using these shortcuts allows this object to only create these values when needed, and to not maintain them up to date unneedlessly.

The null key is not allowed, no null values are allowed.

Nested Class Summary

static interface

SharedDirector.CopyContents<T>

Constructor Summary

SharedDirector(Function<V,V> factory, SharedDirector.CopyContents<V> copier, Modifier<V> emptier, Predicate<V> isEmpty)

Method Summary

boolean	apply(K key, Modifier<V> modifier, boolean applyToEmpty)
boolean	applyToAll(Modifier<V> modifier, boolean applyToEmpty) Applies a modification to all values stored in this object.
V	get(K key) Retrieves the value associated with the given key.
Map<K,V>	getAll()
V	getNonEmpty(K key) Retrieves the value associated with the given key if it is not empty.
V	getShared() Retrieves a view of the value shared by all values in this object.
void	put(K key, V value, Boolean sameAsShared) Call this method after some value has been updated to update the state of this object.
boolean	putEmpty(K key) Associates an empty value to the given key.
void	putShared(K key) Associates to the given key the value equals to the currently shared value.
void	remove(K key, boolean keepShared) Removes the pair related to the given key.
void	updateShared() This method must be called after a modification of the shared view (see getShared()) to update the state of this object.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SharedDirector

public SharedDirector(Function<V,V> factory,
                      SharedDirector.CopyContents<V> copier,
                      Modifier<V> emptier,
                      Predicate<V> isEmpty)

Parameters:

factory - a factory which gives a deep copy of any value. When given null, the factory must return a new empty value. It may never return null. Not null.

copier - a function to copy a source content into a target object. Not null.

emptier - a modifier able to empty any given value. The modifier is never given a null value. Not null.

isEmpty - a predicate able to tell whether a given value is in the empty state. The predicate is never given a null value. Not null.

Method Detail

get

public V get(K key)

Retrieves the value associated with the given key. The value is modifiable and the modification is reflected in this object. The appropriate put method must be called after a modification of any value in this object. Conversely, modifications in this value through this object is reflected in the returned object.

Parameters:

key - not null.

Returns:

the value associated with the given key, or null if there is no such key.

getShared

public V getShared()

Retrieves a view of the value shared by all values in this object. That view is writable. It is empty when the values are not shared (some values are different than others); it is equal to the shared value when the values are shared. Writing to the returned object will write through it and all values in this object will be replaced by its value when the method updateShared() is called. It is mandatory to call the method updateShared() after updating, otherwise the state is inconsistent.

Returns:

not null.

updateShared

public void updateShared()

This method must be called after a modification of the shared view (see getShared()) to update the state of this object. All values in this object are set to the current value of the shared value. Note that if the shared value has not been modified, and this object contains non shared values, calling this method resets all values to empty.

put

public void put(K key,
                V value,
                Boolean sameAsShared)

Call this method after some value has been updated to update the state of this object. In that case the value will typically be the same reference as the one already in this object. It is mandatory that the value has the same content as the current value, thus the user must have modified directly the value in this object before calling this method. The method may also be called to add a new pair to this object, in which case the value parameter is used to update this object.

No guarantee is given that the given value will be used directly in this object, thus the caller should not use a reference to it as a view through this object (except if it is the same reference than the one given by a previous call to get, naturally). An accurate view is obtained through a call to the appropriate get method.

Parameters:

key - not null. A new or already existing key.

value - not null. If the given key already exists in this object, this value must equal the value currently associated with the key.

sameAsShared - an optional hint to improve performance. If the value is not null, and if the values are shared before this method is called, it indicates whether the given value is the same as the currently shared value. If true, it implies that if the values are shared before this method is called, it will still be after this method returns. If false, they will still be shared after this method returns iff this object contains exactly one key. If the values are not shared before this method is called, this parameter has no effect. Note that if that parameter is set to true, this method has the same effect than putShared(Object).

putShared

public void putShared(K key)

Associates to the given key the value equals to the currently shared value. Note that this method has no effect when the key already exists and the values are already shared. If all the values are empty, this method is equivalent to putEmpty(Object).

Caution is required to use this method only when the values are shared. When the values are not shared, the result of the method is undetermined.

Parameters:

key - not null.

putEmpty

public boolean putEmpty(K key)

Associates an empty value to the given key. A possibly existing value content is replaced by the new one.

Parameters:

key - not null.

Returns:

true iff the state of this object changed as a result of this call, i.e. true iff there was no value or a non empty value associated with the given key.

remove

public void remove(K key,
                   boolean keepShared)

Removes the pair related to the given key. If this is the last pair contained in this object, it is possible to keep the value as a shared value (shared by noone!), thus it is then still available when querying the shared value bound to this object.

Parameters:

key - not null, must exist in this object.

keepShared - true to keep the value as a shared value if it is the last one in this object. If there is more than one value left in this object, this parameter has no effect.

getAll

public Map<K,V> getAll()

applyToAll

public boolean applyToAll(Modifier<V> modifier,
                          boolean applyToEmpty)

Applies a modification to all values stored in this object.

Parameters:

modifier - the modification to apply. No null value is given to the modifier. Not null.

applyToEmpty - an optimization hint. If false, the modification has no effect on empty objects and must not necessarily be applied to it. Note that this object does not guarantee that the modifier is never called on an empty object, this is only used for optimization when useful. Set it to true to force this object to apply the modifier to empty objects as well.

Returns:

true iff the state of this object has changed as a result of this method call, thus true iff the modifier returned true to one of the modifications calls.

getNonEmpty

public V getNonEmpty(K key)

Retrieves the value associated with the given key if it is not empty. The value is modifiable and the modification is reflected in this object. The appropriate put method must be called after a modification of any value in this object. Conversely, modifications in this value through this object is reflected in the returned object.

Using this method instead of get(Object) permits to avoid unnecessary lazy-initialisations in some circumstances.

Parameters:

key - not null.

Returns:

the value associated with the given key, or null if there is no such key or if the value is empty.

apply

public boolean apply(K key,
                     Modifier<V> modifier,
                     boolean applyToEmpty)