Package de.aristaflow.adept2.core.eventmanager

Interface EventManager

All Superinterfaces:

ADEPT2Service

All Known Subinterfaces:

ActivityEventManager, InstanceStartEventManager

All Known Implementing Classes:

AbstractEventManager, DefaultEventManager

public interface EventManager
extends ADEPT2Service

An event manager provides the means to create events including arbitrary data and handling these events. This consists of four parts: occurring events providing arbitrary data, event sources creating these events (usually polling for some data), event handler processing occurred events and an event manager that creates event sources and event handler and combines them appropriately.
Event sources and handlers are rather loosely coupled at runtime. However, regarding the type of produced and handled events they are tightly coupled, that is, usually a handler can only process one or a few specific event types since it needs to access the data provided by the event and this is very event specific. For instance an event indicating the presence of data in a database will usually provide this data in the obvious data structure of a ResultSet. Therefore the corresponding handler needs to be able to process the result set appropriately.
To allow for a wide range of event types, sources and handler will usually be loaded as plugins of and by an event manager. The event manager will combine event sources and event handler, however, it cannot ensure that they fit to each other. Therefore each event handler should check for the type of the event before handling it. If a handler receives an unsuitable event, it should silently ignore it.

An event manager allows for registering arbitrary event sources and event handler (as long as it has plugins for these). Event sources are identified by the event type (e.g. ResultSetEvent), the source type (e.g. DBActivityEventSource, that is an event source for database events where the event is based on the configuration of an activity) and an arbitrary event source ID. The latter allows for fine-grained differentiation between event sources of the same type. For instance, an activity-based event source can an ID that identifies the corresponding activity.
The declaration of an event source (type) as plugin is as follows: The plugin type is the event type, the plugin instance name is the source type. The event source ID is arbitrarily and is set by the one who adds the source to the event manager.

An event handler is identified by the event type, the source type as well as an arbitrary ID. In the configuration, the plugin type has an arbitrary name that is usually "EventHandler" but can also be specified by the event manager implementation. The plugin instance name equals the handler ID.

Both event sources and event handler can be added and removed arbitrarily (as long as they are known as plugin by the event manager). Adding an event handler, registers the event handler for a specific event type and source type together with a position an a list. This list is used by event sources to notify event handler about an occurred event in a well-defined order. If the event manager already has one or more event sources for the types a new event handler is added, the handler will be registered at these sources. If new sources are registered for the event type and source type, the handler will be implicitly added to the source. Vice versa, removing an event source will also remove all the registered handler from this source (but not from the event and source type), and removing an event handler removes this handler from the event and source type as well as all existing sources of these types.
To summarise, event sources are registered for an event type and source, as well as event handler. Event handler reside in a list that defines the order they handle events of the event type and source. Each source has the registered handler for its event type and source type. Event sources are instantiated each time they are added. Therefore they need MULTIPLE. Event handler are singleton with respect to an event type and source type, that is all events from different sources of a specific event type and source type are handled by the very same handler instance. Event handler also need MULTIPLE. However, they may also have SINGLETON which uses the very same handler instance for all sources of an event manager independent from the event type and source type.

Note that due to event sources and event handler not being serialisable, the event manager cannot be used remotely.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field	Description
static String	PLUGIN_TYPE_EVENT_HANDLER	The plug-in type ID for event handler.

Method Summary

Modifier and Type	Method	Description
EventHandler	addEventHandler(SessionToken session, String eventType, String sourceType, EventHandler handler, int index)	Adds the designated event handler to the designated event type and event source at the designated position.
EventHandler	addEventHandler(SessionToken session, String eventType, String sourceType, String handlerID, int index)	Adds an event handler having the designated ID to the designated event type and event source at the designated position.
EventSource<? extends Event>	addEventSource(SessionToken session, String eventType, String sourceType, String sourceID, org.apache.commons.configuration2.Configuration configuration)	Adds an event source having the designated ID to the designated event type and event source.
List<String>	getEventHandler(SessionToken session, String eventType, String sourceType)	Gets the event handler that are registered for the designated event type and source type.
Collection<String>	getEventSources(SessionToken session, String eventType, String sourceType)	Gets the event sources that exist for the designated event type and source type.
Map<String,Class<? extends Event>>	getSupportedEventTypes(SessionToken session)	Gets all the event types this event manager supports, that is, it can create event sources for these event types.
EventHandler	removeEventHandler(SessionToken session, String eventType, String sourceType, String handlerID)	Removes the event handler having the designated ID and being registered for the designated event type and event source.
EventSource<? extends Event>	removeEventSource(SessionToken session, String eventType, String sourceType, String sourceID)	Removes the event source having the designated event type, event source and ID.

Methods inherited from interface de.aristaflow.adept2.base.service.ADEPT2Service

getLocalUris, getRelease, getRuntimeRequiredServices, getServiceInstanceName, getStartupRequiredServices, getURIs, init, ping, preShutdown, shutdown, start

Field Detail

PLUGIN_TYPE_EVENT_HANDLER

static final String PLUGIN_TYPE_EVENT_HANDLER

The plug-in type ID for event handler.

See Also:

Constant Field Values

Method Detail

getSupportedEventTypes

Map<String,Class<? extends Event>> getSupportedEventTypes(SessionToken session)

Gets all the event types this event manager supports, that is, it can create event sources for these event types.

Parameters:

session - The session which is used to check for access rights on this method.

Returns:

All event types that are supported by this event manager and for which this event manager can create event sources. They are indexed by the event type name (which equals the plugin type name for event sources).

getEventSources

Collection<String> getEventSources(SessionToken session,
                                   String eventType,
                                   String sourceType)

Gets the event sources that exist for the designated event type and source type.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type for which to get the event sources.

sourceType - The source type for which to get the event sources.

Returns:

The event sources registered for the designated event type and source type. In case no source exists for this event type and source type, the empty collection will be returned.

addEventSource

EventSource<? extends Event> addEventSource(SessionToken session,
                                            String eventType,
                                            String sourceType,
                                            String sourceID,
                                            org.apache.commons.configuration2.Configuration configuration)
                                     throws ConfigurationException,
                                            ServiceNotKnownException

Adds an event source having the designated ID to the designated event type and event source. The designated configuration will complement the plugin configuration of the source. If there is already a source of the designated ID for the designated event type and source type, it will be returned. Event handler registered for the designated event type and source type will be registered at the new source.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The type of which the source creates events.

sourceType - The type of the source to add.

sourceID - The unique (with respect to the event type and source type) ID of the source to add.

configuration - The configuration of the source which complements the plugin configuration.

Returns:

The newly created or the existing event source.

Throws:

ConfigurationException - If there are problems with the designated configuration, a ConfigurationException will be thrown.

ServiceNotKnownException - If there are problems with the plugin configuration or no plugin configured at all for the designated source a ServiceNotKnownException will be thrown.

removeEventSource

EventSource<? extends Event> removeEventSource(SessionToken session,
                                               String eventType,
                                               String sourceType,
                                               String sourceID)

Removes the event source having the designated event type, event source and ID. The removed event source will be returned. If no event source is found, null will be returned. All handler will be removed from the designated event source.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type of which to remove a source.

sourceType - The type of which to remove a source.

sourceID - The ID of the source to remove.

Returns:

The removed event source or null in case there is already an event source of the designated source ID.

getEventHandler

List<String> getEventHandler(SessionToken session,
                             String eventType,
                             String sourceType)

Gets the event handler that are registered for the designated event type and source type.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type for which to get the event handler.

sourceType - The source type for which to get the event handler.

Returns:

The event handler registered for the designated event type and source type in the order they are notified about the corresponding events. In case no handler is registered, the empty list will be returned.

addEventHandler

EventHandler addEventHandler(SessionToken session,
                             String eventType,
                             String sourceType,
                             String handlerID,
                             int index)
                      throws ServiceNotKnownException

Adds an event handler having the designated ID to the designated event type and event source at the designated position. If there is already an event handler of the designated ID for the designated event type and source type, it will be returned. An existing handler may change its position according to the provided one. The event handler will be registered at all existing sources of the designated event type and source type.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type for which to register the event handler.

sourceType - The source type for which to register the event handler.

handlerID - The unique (with respect to the event type and source type) ID of the handler to add.

index - The (0-based) position in the handler list for the designated event type and source type.

Returns:

The newly created or the existing event handler.

Throws:

ServiceNotKnownException - If there are problems with the plugin configuration or no plugin configured at all for the designated source a ServiceNotKnownException will be thrown.

addEventHandler

EventHandler addEventHandler(SessionToken session,
                             String eventType,
                             String sourceType,
                             EventHandler handler,
                             int index)

Adds the designated event handler to the designated event type and event source at the designated position. If there is already an event handler of the designated ID for the designated event type and source type, it will be returned and the designated handler will be ignored. An existing handler may change its position according to the provided one. The event handler will be registered at all existing sources of the designated event type and source type.
This method does not retrieve the handler as plugin and therefore does not need an appropriate plugin configuration for the handler.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type for which to register the event handler.

sourceType - The source type for which to register the event handler.

handler - The handler which to add.

index - The (0-based) position in the handler list for the designated event type and source type.

Returns:

The designated or the existing event handler.

removeEventHandler

EventHandler removeEventHandler(SessionToken session,
                                String eventType,
                                String sourceType,
                                String handlerID)

Removes the event handler having the designated ID and being registered for the designated event type and event source. The removed event handler will be returned. If no event handler is found, null will be returned. The handler will be removed from the corresponding event sources.

Parameters:

session - The session which is used to check for access rights on this method.

eventType - The event type of which to remove an event handler.

sourceType - The source type of which to remove an event handler.

handlerID - The ID of the handler to remove.

Returns:

The removed event source or null in case there is already an event source of the designated source ID.