mirrormap.collections
Class NotifyingMap<K,V>

java.lang.Object
  mirrormap.collections.NotifyingMap<K,V>

Type Parameters:

K - The key type for the map

V - The value type for the map

All Implemented Interfaces:

Map<K,V>

Direct Known Subclasses:

MirrorMap

public class NotifyingMap<K,V>
extends Object
implements Map<K,V>

A NotifyingMap wraps a Map and notifies IMapListener instances when entries in the underlying map are added, updated or removed. The IMapListener instances are registered with the NotifyingMap via the addListener(IMapListener) method. This is the only activity that requires a NotifyingMap reference, all other activities can be handled via the Map interface.

In general, the best practice is to create the underlying map, construct the notifying map with the underlying map and then use the notifying map as the map reference. Mutating the underlying map outside of the notifying map will lead to inconsistent behaviour.

This implementation is thread safe. All methods are synchronized. However the usual semantics for iterating over a HashMap apply to this (i.e. synchronized on the map during iteration to prevent ConcurrentModificationException). In particular see the note in the put(Object, Object) method.

Author:

Ramon Servadei

Nested Class Summary

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

Map.Entry<K,V>

Constructor Summary

NotifyingMap(Map<K,V> data)
Construct the NotifyingMap with the underlying data map.

Method Summary

boolean	addListener(IMapListener<K,V> listener) Add a listener that will be notified when entries in the underlying Map are added, updated or removed.
void	clear() Clear the underlying map.
boolean	containsKey(Object key)
boolean	containsValue(Object value)
Set<Map.Entry<K,V>>	entrySet()
boolean	equals(Object o)
V	get(Object key)
int	hashCode()
boolean	isEmpty()
Set<K>	keySet()
V	put(K key, V value) If the mapping is new, this will: call IMapListener.willAdd(Object, Object) on all listeners put the mapping call IMapListener.didAdd(Object, Object) on all listeners Otherwise this will: call IMapListener.willUpdate(Object, Object, Object) on all listeners put the mapping (overwriting) call IMapListener.didUpdate(Object, Object, Object) on all listeners
void	putAll(Map<? extends K,? extends V> t) Calls put(Object, Object) for each entry added from the argument map.
V	remove(Object key) If the mapping exists, this will: call IMapListener.willRemove(Object) on all listeners remove the mapping call IMapListener.didRemove(Object, Object) on all listeners
boolean	removeListener(IMapListener<?,?> listener) Remove the listener from this NotifyingMap instance.
int	size()
String	toString()
Collection<V>	values()

Methods inherited from class java.lang.Object

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

Constructor Detail

NotifyingMap

public NotifyingMap(Map<K,V> data)

Construct the NotifyingMap with the underlying data map.

Parameters:

data - the map that holds the actual data

Method Detail

addListener

public boolean addListener(IMapListener<K,V> listener)

Add a listener that will be notified when entries in the underlying Map are added, updated or removed.

On adding the listener, it will be notified with the current content of the underlying map. This will be done by calling the IMapListener.didAdd(Object, Object) method of the listener. Note: there may be event interleaving if an update occurs whilst the existing map content is being notified to the newly added listener.

This is an idempotent operation and is synchronized to ensure this.

Parameters:

listener - the listener to add

Returns:

true if the listener was added, false if it already contained the listener

removeListener

public boolean removeListener(IMapListener<?,?> listener)

Remove the listener from this NotifyingMap instance.

Parameters:

listener - the listener to remove

Returns:

true if this list contained the specified element.

clear

public void clear()

Clear the underlying map. Listeners can expect to receive will/did remove events for each entry removed from the map.

Specified by:

clear in interface Map<K,V>

See Also:

Map.clear()

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<K,V>

See Also:

Map.containsKey(java.lang.Object)

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<K,V>

See Also:

Map.containsValue(java.lang.Object)

entrySet

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

Specified by:

entrySet in interface Map<K,V>

Returns:

a Set of Entry instances contained in the underlying Map. Removing entries from the set via the Iterator returned from Set.iterator() will trigger will/did remove events.

See Also:

Map.entrySet()

equals

public boolean equals(Object o)

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class Object

See Also:

Map.equals(java.lang.Object)

get

public V get(Object key)

Specified by:

get in interface Map<K,V>

See Also:

Map.get(java.lang.Object)

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class Object

See Also:

Map.hashCode()

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

See Also:

Map.isEmpty()

keySet

public Set<K> keySet()

Specified by:

keySet in interface Map<K,V>

Returns:

a Set of the keys contained in the underlying Map . Removing entries from the set via the Iterator returned from Set.iterator() will trigger will/did remove events.

See Also:

Map.keySet()

put

public V put(K key,
             V value)

If the mapping is new, this will:

1. call IMapListener.willAdd(Object, Object) on all listeners
2. put the mapping
3. call IMapListener.didAdd(Object, Object) on all listeners

Otherwise this will:

1. call IMapListener.willUpdate(Object, Object, Object) on all listeners
2. put the mapping (overwriting)
3. call IMapListener.didUpdate(Object, Object, Object) on all listeners

Note: this method calls Map.get(Object) followed by Map.put(Object, Object) on the underlying map. For this reason the class is required to be thread safe.

Specified by:

put in interface Map<K,V>

See Also:

Map.put(java.lang.Object, java.lang.Object)

putAll

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

Calls put(Object, Object) for each entry added from the argument map.

Specified by:

putAll in interface Map<K,V>

See Also:

Map.putAll(java.util.Map)

remove

public V remove(Object key)

If the mapping exists, this will:

1. call IMapListener.willRemove(Object) on all listeners
2. remove the mapping
3. call IMapListener.didRemove(Object, Object) on all listeners

Specified by:

remove in interface Map<K,V>

See Also:

Map.remove(java.lang.Object)

size

public int size()

Specified by:

size in interface Map<K,V>

See Also:

Map.size()

values

public Collection<V> values()

Specified by:

values in interface Map<K,V>

Returns:

a Collection of the values contained in the underlying Map. Removing entries from the set via the Iterator returned from Collection.iterator() will trigger will/did remove events.

See Also:

Map.values()

toString

public String toString()

Overrides:

toString in class Object