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

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.SynchronousListener A tag interface indicating that tagged MapListener implementation has to receive the MapEvent notifications in a synchronous manner.
static class	MapListenerSupport.WrapperSynchronousListener A wrapper class that turns the specified MapListener into a synchronous listener.

Field Summary

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.

Constructor Summary

MapListenerSupport()
Constructs a new MapListenerSupport object.

Method Summary

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.
protected static void	addListenerState(Map mapStandardListeners, Object anyKey, MapListener listener, boolean fLite) Add a state information (lite or standard) assosiated with specified key and listener.
protected static void	addSafeListener(Map mapListeners, Object anyKey, MapListener listener) Ensure that the specified map has an Listeners object assosiated 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.
void	fireEvent(MapEvent event, boolean fStrict) Fire the specified map event.
Set	getFilterSet() Obtain a set of all filters that have assosiated global listeners.
Set	getKeySet() Obtain a set of all keys that have assosiated 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.
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.
protected static void	removeListenerState(Map mapStandardListeners, Object anyKey, MapListener listener) Remove a state information (lite or standard) assosiated with specified key and listener.
protected static void	removeSafeListener(Map mapListeners, Object anyKey, MapListener listener) Remove the specified listener from the Listeners object assosiated with the specified key.
String	toString() Provide a string representation of the MapListenerSupport object.

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 alway 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

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 raise events

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

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 raise events

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 assosiated global listeners.

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

Returns:

a set of all filters that have assosiated global listeners

getKeySet

public Set getKeySet()

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

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

Returns:

a set of all keys that have assosiated 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

addSafeListener

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

Ensure that the specified map has an Listeners object assosiated with the specified key 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 assosiated with the specified key.

addListenerState

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

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

removeListenerState

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

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

toString

public String toString()

Provide a string representation of the MapListenerSupport object.

Returns:

a human-readable description of the MapListenerSupport instance