Package com.tangosol.util

Class MapListenerSupport

java.lang.Object

com.tangosol.util.Base

com.tangosol.util.MapListenerSupport

public class MapListenerSupport
extends Base

This class provides support for advanced MapListener functionality.

Since:

Coherence 2.3

Author:

gg 2003.09.16

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MapListenerSupport.FilterEvent	An extension of the CacheEvent which may carry no values (old or new), but instead holds on an array of Filter objects being the "cause" of the event.
static interface	MapListenerSupport.PrimingListener<K,V>	A tag interface indicating that this listener is registered as a synchronous listener for lite events (carrying only a key) and generates a "priming" event when registered.
static interface	MapListenerSupport.SynchronousListener<K,V>	A tag interface indicating that tagged MapListener implementation has to receive the MapEvent notifications in a synchronous manner.
static class	MapListenerSupport.WrapperListener<K,V>	A base class for various wrapper listener classes.
static class	MapListenerSupport.WrapperPrimingListener	A wrapper class that turns the specified MapListener into a priming listener.
static class	MapListenerSupport.WrapperSynchronousListener<K,V>	A wrapper class that turns the specified MapListener into a synchronous listener.

Nested classes/interfaces inherited from class com.tangosol.util.Base

Base.LoggingWriter

Field Summary

Fields

Modifier and Type	Field	Description
protected Listeners	m_listenersCached	A cached set of Listeners.
protected Map	m_mapKeyListeners	The collections of MapListener objects that have signed up for key based notifications from an ObservableMap implementation keyed by the corresponding key objects.
protected Map	m_mapListeners	The collections of MapListener objects that have signed up for notifications from an ObservableMap implementation keyed by the corresponding Filter objects.
protected Map	m_mapStandardKeyListeners	The subset of standard (not lite) key listeners.
protected Map	m_mapStandardListeners	The subset of standard (not lite) global listeners.
protected int	m_nOptimizationPlan	The optimization plan which indicates the fastest way to put together a set of listeners.
protected Listeners	NO_LISTENERS	An empty set of Listeners.
protected static int	PLAN_ALL_LISTENER	There is one all-keys non-filtered listener.
protected static int	PLAN_KEY_LISTENER	There is one key listener (even if for multiple keys).
protected static int	PLAN_NO_LISTENERS	There are no listeners.
protected static int	PLAN_NO_OPTIMIZE	There is no optimized plan, so just use the default approach.
protected static int	PLAN_NONE	A plan has not yet been formed.

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_CONFIG, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Constructor Summary

Constructors

Constructor	Description
MapListenerSupport()	Constructs a new MapListenerSupport object.

Method Summary

Modifier and Type	Method	Description
void	addListener(MapListener listener, Filter filter, boolean fLite)	Add a map listener that receives events based on a filter evaluation.
void	addListener(MapListener listener, Object oKey, boolean fLite)	Add a map listener for a specific key.
void	addListener(MapListener listener, Set setKey, boolean fLite)	Add a map listener for a set of keys.
protected static void	addListenerState(Map mapStandardListeners, Object anyKey, MapListener listener, boolean fLite)	Add a state information (lite or standard) associated with specified key and listener.
boolean	addListenerWithCheck(MapListener listener, Filter filter, boolean fLite)	Add a map listener that receives events based on a filter evaluation.
boolean	addListenerWithCheck(MapListener listener, Object oKey, boolean fLite)	Add a map listener for a specific key.
void	addListenerWithCheck(MapListener listener, Set setKey, boolean fLite)	Add a map listener for a set of keys.
protected static void	addSafeListener(Map mapListeners, Filter anyFilter, MapListener listener)	Ensure that the specified map has a Listeners object associated with the specified Filter and add the specified listener to it.
protected static void	addSafeListener(Map mapListeners, Object anyKey, MapListener listener)	Ensure that the specified map has a Listeners object associated with the specified key and add the specified listener to it.
void	clear()	Remove all signed up listeners.
Listeners	collectListeners(MapEvent event)	Collect all Listeners that should be notified for a given event.
boolean	containsStandardListeners(Filter filter)	Checks whether or not this MapListenerSupport object contains any standard (not lite) listeners for a given filter.
boolean	containsStandardListeners(Object oKey)	Checks whether or not this MapListenerSupport object contains any standard (not lite) listeners for a given key.
static MapEvent	convertEvent(MapEvent event, ObservableMap mapConv, Converter convKey, Converter convVal)	Convert the specified map event into another MapEvent that ensures the lazy event data conversion using the specified converters.
static MapEvent	enrichEvent(MapEvent event, Listeners listeners)	Transform the given MapEvent into a FilterEvent if it is not already a FilterEvent and there are matching filters associated with the specified Listeners object.
protected boolean	evaluateEvent(Filter filter, MapEvent event)	Evaluate whether or not the specified event should be delivered to the listener associated with the specified filter.
void	fireEvent(MapEvent event, boolean fStrict)	Fire the specified map event.
Set	getFilterSet()	Obtain a set of all filters that have associated global listeners.
Set	getKeySet()	Obtain a set of all keys that have associated key listeners.
int	getListenerCount()	Return the number of listeners registered.
Listeners	getListeners(Filter filter)	Obtain the Listeners object for a given filter.
Listeners	getListeners(Object oKey)	Obtain the Listeners object for a given key.
protected static long	getMinVersion(EventListener[] aListeners)	Return a minimum version for the provided listeners.
VersionedPartitions	getMinVersions(Filter filter)	Return the minimum versions for the provided Filter.
VersionedPartitions	getMinVersions(Object oKey)	Return the minimum versions for the provided key.
protected static VersionedPartitions	getMinVersions(EventListener[] aListeners)	Return the minimum versions received for all partitions for the provided listeners.
boolean	isEmpty()	Checks whether or not this MapListenerSupport object contains any listeners.
boolean	isEmpty(Filter filter)	Checks whether or not this MapListenerSupport object contains any listeners for a given filter.
boolean	isEmpty(Object oKey)	Checks whether or not this MapListenerSupport object contains any listeners for a given key.
static boolean	isPrimingListener(MapListener listener)	Check if the given listener is a PrimingListener or if it wraps one.
protected boolean	isTransformedEvent(MapEvent event)	Return true iff the specified event represents a transformed CacheEvent.
protected boolean	isVersionAware(MapListener listener)	Return true if the provided listener is version aware.
protected boolean	isVersionUpdate(MapEvent event)	Return true if the provided MapEvent is due to a synthetic version update.
protected static VersionedPartitions	min(VersionedPartitions versionsLHS, VersionedPartitions versionsRHS)	Return the minimum versions for the provided two partition versioned data structures.
void	removeListener(MapListener listener, Filter filter)	Remove a map listener that previously signed up for events based on a filter evaluation.
void	removeListener(MapListener listener, Object oKey)	Remove a map listener that previously signed up for events about a specific key.
void	removeListener(MapListener listener, Set setKey)	Remove a map listener that previously signed up for events about specific keys.
protected static void	removeListenerState(Map mapStandardListeners, Object anyKey, MapListener listener)	Remove a state information (lite or standard) associated with specified key and listener.
boolean	removeListenerWithCheck(MapListener listener, Filter filter)	Remove a map listener that previously signed up for events based on a filter evaluation.
boolean	removeListenerWithCheck(MapListener listener, Object oKey)	Remove a map listener that previously signed up for events about a specific key.
void	removeListenerWithCheck(MapListener listener, Set setKey)	Remove a map listener that previously signed up for events about specific keys.
protected static void	removeSafeListener(Map mapListeners, Object anyKey, MapListener listener)	Remove the specified listener from the Listeners object associated with the specified key.
String	toString()	Provide a string representation of the MapListenerSupport object.
static <K,V> MapListener<K,V>	unwrap(MapListener<K,V> listener)	Return the inner MapListener skipping any wrapper listeners.
static MapEvent	unwrapEvent(MapEvent evt)	Unwrap the specified map event and return the underlying source event.

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getProcessRandom, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mergeArray, mergeBooleanArray, mergeByteArray, mergeCharArray, mergeDoubleArray, mergeFloatArray, mergeIntArray, mergeLongArray, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

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

Field Detail

PLAN_NONE

protected static final int PLAN_NONE

A plan has not yet been formed.

See Also:

Constant Field Values

PLAN_NO_LISTENERS

protected static final int PLAN_NO_LISTENERS

There are no listeners.

See Also:

Constant Field Values

PLAN_ALL_LISTENER

protected static final int PLAN_ALL_LISTENER

There is one all-keys non-filtered listener.

See Also:

Constant Field Values

PLAN_KEY_LISTENER

protected static final int PLAN_KEY_LISTENER

There is one key listener (even if for multiple keys).

See Also:

Constant Field Values

PLAN_NO_OPTIMIZE

protected static final int PLAN_NO_OPTIMIZE

There is no optimized plan, so just use the default approach.

See Also:

Constant Field Values

NO_LISTENERS

protected final Listeners NO_LISTENERS

An empty set of Listeners. Because this is a theoretically mutable object that is used as a return value, it is purposefully not static.

m_mapListeners

protected Map m_mapListeners

The collections of MapListener objects that have signed up for notifications from an ObservableMap implementation keyed by the corresponding Filter objects.

m_mapKeyListeners

protected Map m_mapKeyListeners

The collections of MapListener objects that have signed up for key based notifications from an ObservableMap implementation keyed by the corresponding key objects.

m_mapStandardListeners

protected Map m_mapStandardListeners

The subset of standard (not lite) global listeners. The keys are the Filter objects, the values are sets of corresponding standard listeners.

m_mapStandardKeyListeners

protected Map m_mapStandardKeyListeners

The subset of standard (not lite) key listeners. The keys are the key objects, the values are sets of corresponding standard listeners.

m_nOptimizationPlan

protected int m_nOptimizationPlan

The optimization plan which indicates the fastest way to put together a set of listeners.

m_listenersCached

protected Listeners m_listenersCached

A cached set of Listeners.

Constructor Detail

MapListenerSupport

public MapListenerSupport()

Constructs a new MapListenerSupport object.

Method Detail

addListener

public void addListener(MapListener listener,
                        Filter filter,
                        boolean fLite)

Add a map listener that receives events based on a filter evaluation.

Parameters:

listener - the listener to add

filter - a filter that will be passed MapEvent objects to select from; a MapEvent will be delivered to the listener only if the filter evaluates to true for that MapEvent; null is equivalent to a filter that always returns true

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

addListenerWithCheck

public boolean addListenerWithCheck(MapListener listener,
                                    Filter filter,
                                    boolean fLite)

Add a map listener that receives events based on a filter evaluation.

Parameters:

listener - the listener to add

filter - a filter that will be passed MapEvent objects to select from; a MapEvent will be delivered to the listener only if the filter evaluates to true for that MapEvent; null is equivalent to a filter that always returns true

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

Returns:

false iff there already existed a "covering" listener for that filter (either standard or lite for a lite call and standard otherwise)

addListener

public void addListener(MapListener listener,
                        Object oKey,
                        boolean fLite)

Add a map listener for a specific key.

Parameters:

listener - the listener to add

oKey - the key that identifies the entry for which to register the event listener

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

addListenerWithCheck

public boolean addListenerWithCheck(MapListener listener,
                                    Object oKey,
                                    boolean fLite)

Add a map listener for a specific key.

Parameters:

listener - the listener to add

oKey - the key that identifies the entry for which to register the event listener

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

Returns:

false iff there already existed a "covering" listener for that key (either standard or lite for a lite call and standard otherwise)

addListener

public void addListener(MapListener listener,
                        Set setKey,
                        boolean fLite)

Add a map listener for a set of keys.

Parameters:

listener - the listener to add

setKey - the key set for which to register the event listener

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

addListenerWithCheck

public void addListenerWithCheck(MapListener listener,
                                 Set setKey,
                                 boolean fLite)

Add a map listener for a set of keys. This method will modify the passed set by removing the keys that already had existing "covering" listeners for them.

Parameters:

listener - the listener to add

setKey - the key set for which to register the event listener

fLite - true to indicate that the MapEvent objects do not have to include the OldValue and NewValue property values in order to allow optimizations

removeListener

public void removeListener(MapListener listener,
                           Filter filter)

Remove a map listener that previously signed up for events based on a filter evaluation.

Parameters:

listener - the listener to remove

filter - a filter used to evaluate events

removeListenerWithCheck

public boolean removeListenerWithCheck(MapListener listener,
                                       Filter filter)

Remove a map listener that previously signed up for events based on a filter evaluation.

Parameters:

listener - the listener to remove

filter - a filter used to evaluate events

Returns:

true iff there are no longer any listeners for that filter

removeListener

public void removeListener(MapListener listener,
                           Object oKey)

Remove a map listener that previously signed up for events about a specific key.

Parameters:

listener - the listener to remove

oKey - the key that identifies the entry for which to unregister the event listener

removeListenerWithCheck

public boolean removeListenerWithCheck(MapListener listener,
                                       Object oKey)

Remove a map listener that previously signed up for events about a specific key.

Parameters:

listener - the listener to remove

oKey - the key that identifies the entry for which to unregister the event listener

Returns:

true iff there are no longer any listeners for that key

removeListener

public void removeListener(MapListener listener,
                           Set setKey)

Remove a map listener that previously signed up for events about specific keys.

Parameters:

listener - the listener to remove

setKey - the set of keys for which to unregister the event listener

removeListenerWithCheck

public void removeListenerWithCheck(MapListener listener,
                                    Set setKey)

Remove a map listener that previously signed up for events about specific keys. This method will modify the passed set by removing the keys that still have existing "covering" listeners for them, so the keys that are retained in the set no longer have any listeners for them.

Parameters:

listener - the listener to remove

setKey - the set of keys for which to unregister the event listener

clear

public void clear()

Remove all signed up listeners.

isEmpty

public boolean isEmpty()

Checks whether or not this MapListenerSupport object contains any listeners.

Returns:

true iff there are no listeners encapsulated by this MapListenerSupport object

getListenerCount

public int getListenerCount()

Return the number of listeners registered.

Returns:

the number of listeners registered

isEmpty

public boolean isEmpty(Filter filter)

Checks whether or not this MapListenerSupport object contains any listeners for a given filter.

Parameters:

filter - the filter

Returns:

true iff there are no listeners for the specified filter encapsulated by this MapListenerSupport object

isEmpty

public boolean isEmpty(Object oKey)

Checks whether or not this MapListenerSupport object contains any listeners for a given key.

Parameters:

oKey - the key

Returns:

true iff there are no listeners for the specified filter encapsulated by this MapListenerSupport object

containsStandardListeners

public boolean containsStandardListeners(Filter filter)

Checks whether or not this MapListenerSupport object contains any standard (not lite) listeners for a given filter.

Parameters:

filter - the filter

Returns:

true iff there are no standard listeners for the specified filter encapsulated by this MapListenerSupport object

containsStandardListeners

public boolean containsStandardListeners(Object oKey)

Checks whether or not this MapListenerSupport object contains any standard (not lite) listeners for a given key.

Parameters:

oKey - the key

Returns:

true iff there are no standard listeners for the specified filter encapsulated by this MapListenerSupport object

getFilterSet

public Set getFilterSet()

Obtain a set of all filters that have associated global listeners.

Note: The returned value must be treated as an immutable.

Returns:

a set of all filters that have associated global listeners

getKeySet

public Set getKeySet()

Obtain a set of all keys that have associated key listeners.

Note: The returned value must be treated as an immutable.

Returns:

a set of all keys that have associated key listeners

getListeners

public Listeners getListeners(Filter filter)

Obtain the Listeners object for a given filter.

Note: The returned value must be treated as an immutable.

Parameters:

filter - the filter

Returns:

the Listeners object for the filter; null if none exists

getListeners

public Listeners getListeners(Object oKey)

Obtain the Listeners object for a given key.

Note: The returned value must be treated as an immutable.

Parameters:

oKey - the key

Returns:

the Listeners object for the key; null if none exists

collectListeners

public Listeners collectListeners(MapEvent event)

Collect all Listeners that should be notified for a given event.

Note: The returned value must be treated as an immutable.

Parameters:

event - the MapEvent object

Returns:

the Listeners object containing the relevant listeners

fireEvent

public void fireEvent(MapEvent event,
                      boolean fStrict)

Fire the specified map event.

Parameters:

event - the map event

fStrict - if true then any RuntimeException thrown by event handlers stops all further event processing and the exception is re-thrown; if false then all exceptions are logged and the process continues

getMinVersions

public VersionedPartitions getMinVersions(Filter filter)

Return the minimum versions for the provided Filter.

Parameters:

filter - the filter the listeners were registered with

Returns:

the minimum versions for the provided Filter

getMinVersions

public VersionedPartitions getMinVersions(Object oKey)

Return the minimum versions for the provided key.

Parameters:

oKey - the key the listeners were registered with

Returns:

the minimum versions for the provided key

convertEvent

public static MapEvent convertEvent(MapEvent event,
                                    ObservableMap mapConv,
                                    Converter convKey,
                                    Converter convVal)

Convert the specified map event into another MapEvent that ensures the lazy event data conversion using the specified converters.

Parameters:

event - the map event

mapConv - the source for the converted event

convKey - (optional) the key Converter

convVal - (optional) the value converter

Returns:

the converted MapEvent object

enrichEvent

public static MapEvent enrichEvent(MapEvent event,
                                   Listeners listeners)

Transform the given MapEvent into a FilterEvent if it is not already a FilterEvent and there are matching filters associated with the specified Listeners object.

Parameters:

event - the MapEvent to transform, if necessary

listeners - the Listeners object

Returns:

a FilterEvent if the given MapEvent is not a FilterEvent and the specified Listeners object has associated filters; otherwise, the given MapEvent

unwrapEvent

public static MapEvent unwrapEvent(MapEvent evt)

Unwrap the specified map event and return the underlying source event.

Parameters:

evt - the event to unwrap

Returns:

the unwrapped event

unwrap

public static <K,V> MapListener<K,V> unwrap(MapListener<K,V> listener)

Return the inner MapListener skipping any wrapper listeners.

Type Parameters:

K - key type for the map

V - value type for the map

Parameters:

listener - the listener to check against

Returns:

the inner MapListener skipping any wrapper listeners

isPrimingListener

public static boolean isPrimingListener(MapListener listener)

Check if the given listener is a PrimingListener or if it wraps one.

Parameters:

listener - Map listener to check

Returns:

true iff the listener is a PrimingListener or wraps one

isVersionAware

protected boolean isVersionAware(MapListener listener)

Return true if the provided listener is version aware.

Parameters:

listener - the listener to check

Returns:

true if the provided listener is version aware

isVersionUpdate

protected boolean isVersionUpdate(MapEvent event)

Return true if the provided MapEvent is due to a synthetic version update.

Parameters:

event - the event to test

Returns:

true if the provided MapEvent is due to a synthetic version update

evaluateEvent

protected boolean evaluateEvent(Filter filter,
                                MapEvent event)

Evaluate whether or not the specified event should be delivered to the listener associated with the specified filter.

Parameters:

filter - the filter

event - the event

Returns:

true iff the event should be delivered to the corresponding listener

isTransformedEvent

protected boolean isTransformedEvent(MapEvent event)

Return true iff the specified event represents a transformed CacheEvent.

Parameters:

event - the event to test

Returns:

true iff the event has been transformed

addSafeListener

protected static void addSafeListener(Map mapListeners,
                                      Object anyKey,
                                      MapListener listener)

Ensure that the specified map has a Listeners object associated with the specified key and add the specified listener to it.

addSafeListener

protected static void addSafeListener(Map mapListeners,
                                      Filter anyFilter,
                                      MapListener listener)

Ensure that the specified map has a Listeners object associated with the specified Filter and add the specified listener to it.

removeSafeListener

protected static void removeSafeListener(Map mapListeners,
                                         Object anyKey,
                                         MapListener listener)

Remove the specified listener from the Listeners object associated with the specified key.

addListenerState

protected static void addListenerState(Map mapStandardListeners,
                                       Object anyKey,
                                       MapListener listener,
                                       boolean fLite)

Add a state information (lite or standard) associated with specified key and listener.

removeListenerState

protected static void removeListenerState(Map mapStandardListeners,
                                          Object anyKey,
                                          MapListener listener)

Remove a state information (lite or standard) associated with specified key and listener.

getMinVersions

protected static VersionedPartitions getMinVersions(EventListener[] aListeners)

Return the minimum versions received for all partitions for the provided listeners.

Parameters:

aListeners - the listeners to interrogate

Returns:

the minimum versions received for all partitions for the provided listeners

min

protected static VersionedPartitions min(VersionedPartitions versionsLHS,
                                         VersionedPartitions versionsRHS)

Return the minimum versions for the provided two partition versioned data structures.

Parameters:

versionsLHS - the first partition versioned object

versionsRHS - the second partition versioned object

Returns:

the minimum versions for the provided two partition versioned data structures

getMinVersion

protected static long getMinVersion(EventListener[] aListeners)

Return a minimum version for the provided listeners.

Parameters:

aListeners - the listeners to interrogate

Returns:

a minimum version for the provided listeners

toString

public String toString()

Provide a string representation of the MapListenerSupport object.

Overrides:

toString in class Object

Returns:

a human-readable description of the MapListenerSupport instance