fulmine.event.listener
Class MultiEventListener

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.event.listener.MultiEventListener

All Implemented Interfaces:

IEventListener, ILifeCycleEventListener, IDestroyable, ILifeCycle

Direct Known Subclasses:

MultiSystemEventListener, PriorityMultiEventListener

public class MultiEventListener
extends AbstractLifeCycle
implements ILifeCycleEventListener

An event listener that is a composition of multiple internal IEventListener objects that each handle a specific type of IEvent. Events received by this listener are passed on to the listener that is mapped to the event's class.

This class registers itself with event sources and then passes the events to the appropriate mapped event listener. The internal listeners are never registered directly with the event sources.

This needs to locate the listener per event by checking assignment compatibility of the event with all listeners' registered event class. This could mean that multiple internal listeners receive the event if there is an intersection between the registered event class of the listeners and the current event's class.

During the AbstractLifeCycle.start() and AbstractLifeCycle.destroy() methods, only listeners that are mapped to an AbstractSystemEvent event will cause the multi-event listener to be registered/unregistered against the event's 'singleton' source (IEventManager.getSystemEventSource(Class)).

Author:

Ramon Servadei

Constructor Summary

MultiEventListener(String name, IEventManager context, Map<Class<? extends IEvent>,IEventListener> listeners)
Standard constructor

Method Summary

void	addedAsListenerFor(IEventSource source) The listener receives this when it has been added as a listener to an event source via IEventSource.addListener(IEventListener).
protected void	doDestroy() Overridden in subclasses to perform custom logic on destruction.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
Class<? extends IEvent>[]	getEventTypeFilter() Get the classes of IEvent instances this listener can process.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
void	removedAsListenerFrom(IEventSource source) The listener receives this when it has been removed as a listener from an event source via IEventSource.removeListener(IEventListener).
String	toString()
void	update(IEvent event) An update has occurred that this listener is interested in.

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, isActive, start

Methods inherited from class java.lang.Object

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

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Constructor Detail

MultiEventListener

public MultiEventListener(String name,
                          IEventManager context,
                          Map<Class<? extends IEvent>,IEventListener> listeners)

Standard constructor

Parameters:

name - the name for this

context - the event context to use

listeners - maps the IEvent type to the IEventListener object that will process events of that type

Method Detail

doDestroy

protected void doDestroy()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on destruction. Any exceptions should be thrown as a RuntimeException or subclass thereof.

Specified by:

doDestroy in class AbstractLifeCycle

getLog

protected AsyncLog getLog()

Description copied from class: AbstractLifeCycle

Get the log to use for the object hierarchy

Overrides:

getLog in class AbstractLifeCycle

Returns:

the log to use for the object hierarchy

doStart

protected void doStart()

Description copied from class: AbstractLifeCycle

Overridden in subclasses to perform custom logic on activation. Any exceptions should be thrown as a RuntimeException or subclass thereof. When this method is called, the AbstractLifeCycle.isActive() method will return true.

Specified by:

doStart in class AbstractLifeCycle

update

public final void update(IEvent event)

Description copied from interface: IEventListener

An update has occurred that this listener is interested in. IEventSource instances are bound to EventProcessor instances so the same thread will execute this method for events originating from the same event source. This does not mean that this method is thread safe; this method may be run by multiple EventProcessor instances and so should be thread aware as appropriate.

This method can throw any Exception and processing will not be interrupted. The EventProcessor will handle the exception.

Specified by:

update in interface IEventListener

Parameters:

event - the event encapsulating the update.

addedAsListenerFor

public void addedAsListenerFor(IEventSource source)

Description copied from interface: IEventListener

The listener receives this when it has been added as a listener to an event source via IEventSource.addListener(IEventListener).

Specified by:

addedAsListenerFor in interface IEventListener

Parameters:

source - the source that this listener will receive events from.

removedAsListenerFrom

public void removedAsListenerFrom(IEventSource source)

Description copied from interface: IEventListener

The listener receives this when it has been removed as a listener from an event source via IEventSource.removeListener(IEventListener).

Specified by:

removedAsListenerFrom in interface IEventListener

Parameters:

source - the source that this listener will no longer receive events from.

getEventTypeFilter

public Class<? extends IEvent>[] getEventTypeFilter()

Description copied from interface: IEventListener

Get the classes of IEvent instances this listener can process. The IEventListener.update(IEvent) method will only be called with IEvent instances whose Class is assignment compatible with any contained in this array.

This is an event filtering mechanism. An IEventSource may generate many types of IEvent instances but a listener may only be interested in one type. By specifying the types of events the listener is interested in using this method, the listener effectively filters out unwanted events.

If the filter is dynamic then this method must be thread aware.

Specified by:

getEventTypeFilter in interface IEventListener

Returns:

an array of Class objects that determine the types of IEvent instances this listener can process

toString

public final String toString()

Overrides:

toString in class AbstractLifeCycle