i3.dragos.core.services.events
Class EventManager

java.lang.Object
  i3.dragos.core.AbstractService
      i3.dragos.core.services.events.EventManager

All Implemented Interfaces:

Service

public class EventManager
extends AbstractService

The EventManager is responsible for distributing events to the registered event listeners. It is transacation-aware and implements event queueing, so listeners can precisely specify when in the life cycle of a transaction they want to receive their events.

A note about the order of event firing, especially for those implementing multiple types of listeners at once:

• Events are forwarded to general listeners first, then to those listeners that are restricted to a certain DataSourceURL or TransactionManager.
• TransactionEvents (like "before commit") are fired before any queued DataEvents, which might be "released" by that state change. The reason behind this is that reactions to the TransactionEvent may cause more DataEvents, but not the other way around.

The EventManager also serves a secondary purpose: Because he is informed about every change in the graph data anyway, he marks transactions as "dirty", which means that consistency is not guaranteed until a consistency check is performed (which will also reset the "dirty" flag).

A remark about the "generic event" facility: Please note that this is not the only way for an extension to use custom events! In fact, if your event can be expressed as a subclass of any of the pre-defined event classes, it is strongly encouraged to do so, especially for DataEvents, where you gain transaction-awareness for free!

For much more information about EventManager and associated classes, please refer to the "Guide to Events and Rules" in the documentation.

Author:

Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

Nested Class Summary

Nested classes/interfaces inherited from interface i3.dragos.core.Service

Service.Result, Service.State

Constructor Summary

EventManager()
Creates an EventManager instance.

Method Summary

void	addDataListener(DataListener l, EventCouplingMode mode, DataSourceURL ds) Registers a DataListener.
<T extends java.util.EventListener> void	addGenericListener(java.lang.Class<T> channelInterface, T listener) Adds a generic listener.
void	addGraphPoolListener(GraphPoolListener l) Registers a GraphPoolListener.
void	addPreFilter(EventFilter f) Adds an EventFilter that is consulted for every event before it is processed.
void	addTransactionListener(TransactionListener l, TransactionManager tm) Registers a TransactionListener.
void	fireDataEvent(DataEvent e) Fires an event after a GraphEntity changes.
<T extends java.util.EventListener> void	fireGenericEvent(java.lang.Class<T> channelInterface, java.util.EventObject event, java.lang.reflect.Method method) Fires a generic event.
void	fireGraphPoolEvent(GraphPoolEvent e) Fires a GraphPoolEvent.
void	fireTransactionEvent(TransactionEvent e) Fires a TransactionEvent.
static EventManager	getInstance() Returns the event manager instance registered by the service manager.
java.lang.String	getName() Returns the name of the service.
java.util.List<EventFilter>	getPreFilters() Returns all currently registered pre-filters.
void	removeDataListener(DataListener l, EventCouplingMode mode, DataSourceURL ds) Unregisters a DataListener.
<T extends java.util.EventListener> void	removeGenericListener(java.lang.Class<T> channelInterface, T listener) Removes a generic listener.
void	removeGraphPoolListener(GraphPoolListener l) Unregisters a GraphPoolListener.
void	removePreFilter(EventFilter f) Removes a pre-filter.
void	removeTransactionListener(TransactionListener l, TransactionManager tm) Unregisters a TransactionListener.

Methods inherited from class i3.dragos.core.AbstractService

getState, initialize, resume, start, stop, suspend, uninitialize

Methods inherited from class java.lang.Object

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

Constructor Detail

EventManager

public EventManager()

Creates an EventManager instance.

Method Detail

getInstance

public static EventManager getInstance()

Returns the event manager instance registered by the service manager.

Returns:

the rule engine registered by the module manager.

getName

public java.lang.String getName()

Returns the name of the service.

Returns:

the name of the service.

addPreFilter

public void addPreFilter(EventFilter f)

Adds an EventFilter that is consulted for every event before it is processed.

The EventFilter.accepts(i3.dragos.core.services.events.DragosEvent) method is called on all EventFilters in the same order they were added, until one of them does not accept the event. Only if all pre-filters accept the event, it will be processed as usual by the EventManager.

The main application for this method is for extensions to supress events generated by manipulation of their meta-data. These events should not become visible to the application and might confuse it. You may even employ this method to rewrite events, by firing you own modified event and rejecting the original one.

Pre-filters can not be used for the generic event distribution service offered by EventManager, only for DragosEvent's.

When using pre-filters to suppress transaction events, you should be aware that this also affects the transaction-awareness of the EventManager itself (DataEvent queues for EventCouplingMode.BEFORE_COMMIT and EventCouplingMode.AFTER_COMMIT), because pre-filters are applied before any event evaluation!

Parameters:

f - The EventFilter (must not be null).

removePreFilter

public void removePreFilter(EventFilter f)

Removes a pre-filter. If the filter was not added to the list before, no action is taken.

Parameters:

f - The EventFilter (must not be null).

See Also:

addPreFilter(EventFilter)

getPreFilters

public java.util.List<EventFilter> getPreFilters()

Returns all currently registered pre-filters. The returned list is a shallow copy of the original list.

Returns:

all currently registered pre-filters.

See Also:

addPreFilter(EventFilter)

addDataListener

public void addDataListener(DataListener l,
                            EventCouplingMode mode,
                            DataSourceURL ds)

Registers a DataListener. If a DataSourceURL is specified, the DataListener will only receive events for transactions running on that data source; null indicates that the listener wants to be informed about all transactions.

A DataListener can register multiple times, which means that he will receive each event more than once. A separate list of listeners is maintained for each category, where category means a specific EventCouplingMode/DataSourceURL pair (where the DataSourceURL may be null). When unregistering, you have to specify the same parameter values you used when registering, otherwise EventManager will look in the wrong category and not find the correct listener entry (or none at all).

Parameters:

l - The DataListener (must not be null).

mode - The EventCouplingMode (must not be null).

ds - The DataSourceURL (may be null).

removeDataListener

public void removeDataListener(DataListener l,
                               EventCouplingMode mode,
                               DataSourceURL ds)

Unregisters a DataListener.

Parameters:

l - The DataListener (must not be null).

mode - The EventCouplingMode (must not be null).

ds - The DataSourceURL (may be null).

See Also:

addDataListener(DataListener, EventCouplingMode, DataSourceURL)

fireDataEvent

public void fireDataEvent(DataEvent e)
                   throws DragosException

Fires an event after a GraphEntity changes.

Parameters:

e - The DataEvent.

Throws:

DragosException - in case of internal or nested errors.

addTransactionListener

public void addTransactionListener(TransactionListener l,
                                   TransactionManager tm)

Registers a TransactionListener. If a TransactionManager is specified, the TransactionListener will only receive events for transactions running on that manager; null indicates that the listener wants to be informed about all transactions.

A TransactionListener can register multiple times, which means that he will receive each event more than once. A separate list of listeners is maintained for each category, where category means a specific TransactionManager or the special case null. When unregistering, you have to specify the same tm value you used when registering, otherwise EventManager will look in the wrong category and not find the correct listener entry (or none at all).

Parameters:

l - The TransactionListener (must not be null).

tm - The TransactionManager (may be null).

removeTransactionListener

public void removeTransactionListener(TransactionListener l,
                                      TransactionManager tm)

Unregisters a TransactionListener.

Parameters:

l - The TransactionListener (must not be null).

tm - The TransactionManager (may be null).

See Also:

addTransactionListener(TransactionListener, TransactionManager)

fireTransactionEvent

public void fireTransactionEvent(TransactionEvent e)
                          throws DragosException

Fires a TransactionEvent.

Parameters:

e - The TransactionEvent.

Throws:

DragosException - in case of any errors.

addGraphPoolListener

public void addGraphPoolListener(GraphPoolListener l)

Registers a GraphPoolListener.

A GraphPoolListener can register multiple times, which means that he will receive each event more than once.

Parameters:

l - The GraphPoolListener (must not be null).

removeGraphPoolListener

public void removeGraphPoolListener(GraphPoolListener l)

Unregisters a GraphPoolListener.

If it has been registered multiple times, only one of these registrations is removed.

Parameters:

l - The GraphPoolListener (must not be null).

See Also:

addGraphPoolListener(GraphPoolListener)

fireGraphPoolEvent

public void fireGraphPoolEvent(GraphPoolEvent e)
                        throws DragosException

Fires a GraphPoolEvent.

Parameters:

e - The GraphPoolEvent.

Throws:

DragosException - in case of any errors.

addGenericListener

public <T extends java.util.EventListener> void addGenericListener(java.lang.Class<T> channelInterface,
                                                                   T listener)

Adds a generic listener.

Type Parameters:

T - the listener interface for the channel.

Parameters:

channelInterface - The EventListener interface that identifies this channel and also must be implemented by all listeners on that channel.

listener - The listener to add.

removeGenericListener

public <T extends java.util.EventListener> void removeGenericListener(java.lang.Class<T> channelInterface,
                                                                      T listener)

Removes a generic listener.

Type Parameters:

T - the listener interface for the channel.

Parameters:

channelInterface - The EventListener interface that identifies this channel and also must be implemented by all listeners on that channel.

listener - The listener to remove.

fireGenericEvent

public <T extends java.util.EventListener> void fireGenericEvent(java.lang.Class<T> channelInterface,
                                                                 java.util.EventObject event,
                                                                 java.lang.reflect.Method method)
                      throws java.lang.IllegalArgumentException,
                             java.lang.IllegalAccessException,
                             java.lang.reflect.InvocationTargetException

Fires a generic event.

Type Parameters:

T - the listener interface for the channel.

Parameters:

channelInterface - The EventListener interface that identifies this channel and also must be implemented by all listeners on that channel.

event - The event to fire.

method - The method to invoke on the listeners (must exist at all listeners (should be defined in the channel interface anyway) and must accept the event type as the only parameter!).

Throws:

java.lang.reflect.InvocationTargetException - see Method.invoke(java.lang.Object, java.lang.Object[]) for details.

java.lang.IllegalAccessException - see Method.invoke(java.lang.Object, java.lang.Object[]) for details.

java.lang.IllegalArgumentException - see Method.invoke(java.lang.Object, java.lang.Object[]) for details.

See Also:

Method.invoke(java.lang.Object, java.lang.Object[])