fulmine.event.listener
Class AsymmetricEventProcessor

java.lang.Object
  fulmine.AbstractLifeCycle
      fulmine.model.component.AbstractComponent
          fulmine.event.EventSource
              fulmine.event.listener.AsymmetricEventProcessor

All Implemented Interfaces:

IEvent, IEventSource, IAddressable, IDescriptor, IDestroyable, ILifeCycle, IComponent, IWireState, Cloneable

Direct Known Subclasses:

ActiveAsymmetricEventProcessor

public abstract class AsymmetricEventProcessor
extends EventSource
implements IEventSource, ILifeCycle

This class must be started by calling AbstractLifeCycle.start().

Processes the events from multiple sources as a single unit of work. The sources must have a unidirectional relationship; there is 1 driver source and 1 or more driven sources. The driver source generates an event that is consumed by the driven sources that then produce events in response. The driver event and driven events will occur in separate frames; the 'asymmetry' is in the events being generated in these separate frames (see IEventFrame for a description of frames). The diagram below helps to illustrate this.

       Source A (generates event A1)
          |           
          |
    ______|_______
    |            |
    |            |
    |            v    
    |         Source B (consumes A1 and generates event B1)
    |            |    
    |            |
    ---> this <---
    (consumes A1 and B1 only when they are both available)
 

This class handles the co-ordination such that event B1 from source B is processed with event A1 from source A even though event A1 and B1 occur in separate frames.

Source A is the 'driver source', source B is the 'driven source'. There can be multiple driven sources, but only 1 driver source. This driving relationship, coupled with:

• the guaranteed event ordering of the FulmineContext
• the guaranteed association of an EventProcessor to an IEventSource
• the guarantee that IPriorityEventListener instances are processed before other listeners

ensures that A1 is received before B1. This listener uses these mechanisms to cache the 'driver' events in preparation for receiving the 'driven' events. The events are associated with each other using the driver event's IEvent.getFrame() and the driven event's IEvent.getDrivingFrame().

AsymmetricEventProcessor instances can be chained together to form arbitrarily complex event propagation listener matrices. This class was principally designed to handle the so-called "diamond" observer construct:

        Node A
          |           
    ______|_______
    |            |
    |            |
    v            v    
  Node B       Node C
    |            |
    |            |
    ---> this <---
 

Author:

Ramon Servadei

Nested Class Summary

static class

AsymmetricEventProcessor.Result The output from the processing of the driving and driven events handled by an AsymmetricEventProcessor.

Field Summary

protected Map<IEventFrameExecution,List<IEvent>>	drivenEvents The driven events stored per driving frame.
protected Map<IEventFrameExecution,IEvent>	driverEvents The driver events that are stored against their IEvent.getFrame() in preparation for a matching driven events (matched using the driven event's IEvent.getDrivingFrame()).

Constructor Summary

AsymmetricEventProcessor(IEventManager context, Class<? extends IEvent>[] driverEventTypeFilter, IEventSource driverSource, Class<? extends IEvent>[] drivenEventTypeFilter, IEventSource... drivenSources)
Construct the processor for the asymmetric event driving relationship.

Method Summary

protected void	doComponentDestroy() Unregisters listeners from the context.
protected void	doStart() Overridden in subclasses to perform custom logic on activation.
IEventSource[]	getDrivenSources() Get the driven source.
IEventSource	getDriverSource() Get the driver source.
protected AsyncLog	getLog() Get the log to use for the object hierarchy
String	toDetailedString() Provides a formatted string describing this object in detail.
String	toString()
protected abstract AsymmetricEventProcessor.Result	update(IEvent driverEvent, List<IEvent> drivenEvents) Process the driver and driven IEvent objects generated by the driver and driven IEventSource objects.

Methods inherited from class fulmine.event.EventSource

doReadState, doWriteState

Methods inherited from class fulmine.model.component.AbstractComponent

addEvent, addListener, checkClone, clone, createIdentityString, doDestroy, doPostAddListener, doPostRemoveListener, equals, getAddress, getAddressable, getDomain, getDrivingFrame, getEventSourceGroupId, getFrame, getIdentity, getIdentityString, getListeners, getSource, getTriggerEvent, getType, hashCode, isClone, readState, removeListener, removeListeners, setDrivingFrame, setFrame, setTriggerEvent, toIdentityString, writeState

Methods inherited from class fulmine.AbstractLifeCycle

checkActive, destroy, finalize, isActive, start

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface fulmine.event.IEventSource

addEvent, addListener, getEventSourceGroupId, getListeners, removeListener, removeListeners

Methods inherited from interface fulmine.IDescriptor

toIdentityString

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.IAddressable

getAddress, getDomain, getIdentity, getType

Field Detail

driverEvents

protected final Map<IEventFrameExecution,IEvent> driverEvents

The driver events that are stored against their IEvent.getFrame() in preparation for a matching driven events (matched using the driven event's IEvent.getDrivingFrame()).

drivenEvents

protected final Map<IEventFrameExecution,List<IEvent>> drivenEvents

The driven events stored per driving frame.

Constructor Detail

AsymmetricEventProcessor

public AsymmetricEventProcessor(IEventManager context,
                                Class<? extends IEvent>[] driverEventTypeFilter,
                                IEventSource driverSource,
                                Class<? extends IEvent>[] drivenEventTypeFilter,
                                IEventSource... drivenSources)

Construct the processor for the asymmetric event driving relationship.

Parameters:

context - the context this processor should use

driverEventTypeFilter - The event filter for driver events, defines the event types from the driver source that are processed

driverSource - the driver IEventSource

drivenEventTypeFilter - The event filter for driven events, defines the event types from the driven sources that are processed

drivenSources - the driven IEventSource objects that will generate events as a result of the driver source events.

Method Detail

update

protected abstract AsymmetricEventProcessor.Result update(IEvent driverEvent,
                                                          List<IEvent> drivenEvents)

Process the driver and driven IEvent objects generated by the driver and driven IEventSource objects. These events are linked by the driver event's frame.

The order of the driven events in this method is not guaranteed to be the same as that of the listeners used in the constructor; the order depends on which driven event arrives first.

Parameters:

driverEvent - the driver IEvent

drivenEvents - the list of driven IEvent objects caused by the driver event. The order of the events in the list is not guaranteed to be the same as the listeners used in the constructor; the order depends on which driven event arrived first.

Returns:

a result (IEvent subclass) that represents the output of this method. The result event is notified to all registered IEventListener instances. The result does not need to set the source, frame or driving frame. Use null for no event to be raised.

See Also:

IEvent.getDrivingFrame()

getDriverSource

public final IEventSource getDriverSource()

Get the driver source.

Returns:

the driver IEventSource

getLog

protected AsyncLog getLog()

Description copied from class: AbstractLifeCycle

Get the log to use for the object hierarchy

Overrides:

getLog in class EventSource

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.

Overrides:

doStart in class AbstractComponent

getDrivenSources

public final IEventSource[] getDrivenSources()

Get the driven source.

Returns:

the driven IEventSource

doComponentDestroy

protected void doComponentDestroy()

Unregisters listeners from the context.

Overrides:

doComponentDestroy in class AbstractComponent

toDetailedString

public String toDetailedString()

Description copied from interface: IDescriptor

Provides a formatted string describing this object in detail. This has the same or more information than the standard Object.toString() method.

Specified by:

toDetailedString in interface IDescriptor

Overrides:

toDetailedString in class AbstractComponent

Returns:

a formatted string describing this object in detail

toString

public final String toString()

Overrides:

toString in class AbstractComponent