MapListenerSupport (Java API Reference for Oracle® Coherence Community Edition)

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 and 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, Base.StackFrame

Field Summary

Fields
Modifier and Type	Field and 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_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 and Description

MapListenerSupport()
Constructs a new MapListenerSupport object.

Constructors
Constructor and Description
`MapListenerSupport()` Constructs a new MapListenerSupport object.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`Listeners`	`getListeners(Filter filter)` Obtain the Listeners object for a given filter.
`Listeners`	`getListeners(Object oKey)` Obtain the Listeners object for a given key.
`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.
`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 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, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, 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
  - 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
  - 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
  - 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
  - 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.
  - 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

Class MapListenerSupport

Nested Class Summary

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

Field Summary

Fields inherited from class com.tangosol.util.Base

Constructor Summary

Method Summary

Methods inherited from class com.tangosol.util.Base

Methods inherited from class java.lang.Object

Field Detail

PLAN_NONE

PLAN_NO_LISTENERS

PLAN_ALL_LISTENER

PLAN_KEY_LISTENER

PLAN_NO_OPTIMIZE

NO_LISTENERS

m_mapListeners

m_mapKeyListeners

m_mapStandardListeners

m_mapStandardKeyListeners

m_nOptimizationPlan

m_listenersCached

Constructor Detail

MapListenerSupport

Method Detail

addListener

addListenerWithCheck

addListener

addListenerWithCheck

addListener

addListenerWithCheck

removeListener

removeListenerWithCheck

removeListener

removeListenerWithCheck

removeListener

removeListenerWithCheck

clear

isEmpty

isEmpty

isEmpty

containsStandardListeners

containsStandardListeners

getFilterSet

getKeySet

getListeners

getListeners

collectListeners

fireEvent

convertEvent

enrichEvent

unwrapEvent

isPrimingListener

evaluateEvent

isTransformedEvent

addSafeListener

addSafeListener

removeSafeListener

addListenerState

removeListenerState

toString