de.aristaflow.adept2.core.eventmanager.common

Class AbstractSharedEventSource<E extends Event,S extends SharingSource<E>>

java.lang.Object

de.aristaflow.adept2.core.eventmanager.common.AbstractSharedEventSource<E,S>

Type Parameters:

E - The type of the event.

S - The type of the SharingSource.

All Implemented Interfaces:

EventSource<E>, PollingSource<E>, SharedPollingSource<E>, java.lang.Runnable

public abstract class AbstractSharedEventSource<E extends Event,S extends SharingSource<E>>
extends java.lang.Object
implements SharedPollingSource<E>

An event source that distributes events among several sharing event sources. Each sharing event source is registered at a shared event source. For this to work, the sharing event sources need to have events similar to that of the shared event source. For instance, several sharing event sources waiting for specific data in a DBMS, may be using a common shared event source if they have the same SQL query that only differs in the filtering attributes (i. e. the values of the WHERE columns).
Each sharing event source is identified by a set of keys (e. g. the values of the WHERE columns). If the shared event source detects an event, it forwards this event to the corresponding sharing event source.

This way, sharing event sources do not need to poll separately but can share the same resources when checking for their respective event.

Field Summary

Fields

Modifier and Type	Field and Description
protected DefaultEventManager	eventManager The event manager of this event source providing the connection to the event source.
protected java.lang.String	eventType The event type, cf Event.getEventType().
protected Configuration	initConf The configuration of this event source that is shared by all sharing sources.
protected java.util.logging.Logger	logger The logger for exceptions that occur when handling an event.
protected java.lang.Class<S>	sharingSourceClass The SharingSource type this event source is using.
protected java.util.concurrent.locks.ReadWriteLock	sourceLock The lock for synchronising access to the sources (sources and sourceIds).
protected java.util.Map<java.util.List<java.io.Serializable>,java.util.List<S>>	sources All sharing sources registered at this shared source, indexed by their identifying values and in the order they have been added to this sharing event source.
protected java.lang.String	sourceType The type of this shared DB event source.

Fields inherited from interface de.aristaflow.adept2.model.events.sources.PollingSource

CONF_POLL_TIME, CONF_START_TIME

Constructor Summary

Constructors

Constructor and Description
AbstractSharedEventSource(Configuration conf, DefaultEventManager eventManager, Registry registry, java.lang.Class<S> sharingSourceClass, java.lang.String eventType, java.lang.String sourceType) Default constructor for a plugin of the DefaultEventManager called by a service registry.

Method Summary

Modifier and Type	Method and Description
void	addAll(java.util.List<EventHandler> handlers) Adds the designated event handler in the designated order to the list of the handler that are already registered.
protected boolean	addedSharingSourceLocked(java.util.List<java.io.Serializable> sourceKeys, S source) Signals subclasses that the designated sharing source has been added to this shared source.
void	addHandler(EventHandler handler, int index) Adds the designated handler at the designated position (0-based) to the list of registered handler.
boolean	addSharingSource(SharingSource<?> source) Adds the designated sharing source at this shared source.
java.util.List<EventHandler>	getEventHandler() Gets the event handler that have been registered for this event source.
protected java.lang.String	getEventType() Gets the type of the events, this shared event source generates.
java.lang.String	getHierarchicalSourceName() Gets the hierarchical name of this source, that is the event type, the source type and the source ID for usage in log messages and alike.
java.lang.String	getID() Gets the ID of this source.
protected abstract java.util.List<java.io.Serializable>	getSourceKeys(S source) Gets the data (key values) that identifies the designated sharing event source.
java.lang.String	getType() Gets the type of this source.
void	init() Initialises this polling source.
protected void	parseConfiguration(Configuration conf) Parses the designated (initial) configuration.
EventHandler	removeHandler(java.lang.String handlerID) Removes the handler with the designated ID from the list and returns it.
boolean	removeSharingSource(SharingSource<?> source) Removes the designated sharing source from this shared source.
protected void	removingSharingSourceLocked(java.util.List<java.io.Serializable> sourceKeys, SharingSource<?> source) Signals subclasses that the designated sharing source is about to be removed from this shared source.
void	setConfiguration(Configuration conf, java.lang.String id) Sets the (additional) configuration of this event source and its ID.
boolean	supportsSharingSource(SharingSource<?> source) Gets whether this shared source can handle the designated sharing source and combine it with the already registered sharing sources.
void	terminate() Terminates this polling source.

Methods inherited from class java.lang.Object

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

Methods inherited from interface de.aristaflow.adept2.model.events.sources.PollingSource

getPollTime, getStartTime

Methods inherited from interface java.lang.Runnable

run

Field Detail

logger

protected final java.util.logging.Logger logger

The logger for exceptions that occur when handling an event.

sharingSourceClass

protected final java.lang.Class<S extends SharingSource<E>> sharingSourceClass

The SharingSource type this event source is using.

eventType

protected final java.lang.String eventType

The event type, cf Event.getEventType().

sourceType

protected final java.lang.String sourceType

The type of this shared DB event source. This is used in the configuration of the event manager as well as for the sharing event sources to retrieve the shared event source.

initConf

protected Configuration initConf

The configuration of this event source that is shared by all sharing sources. This will be configuration set via setConfiguration(Configuration, String).

sourceLock

protected final java.util.concurrent.locks.ReadWriteLock sourceLock

The lock for synchronising access to the sources (sources and sourceIds).

sources

protected final java.util.Map<java.util.List<java.io.Serializable>,java.util.List<S extends SharingSource<E>>> sources

All sharing sources registered at this shared source, indexed by their identifying values and in the order they have been added to this sharing event source.

eventManager

protected final DefaultEventManager eventManager

The event manager of this event source providing the connection to the event source.

Constructor Detail

AbstractSharedEventSource

public AbstractSharedEventSource(Configuration conf,
                                 DefaultEventManager eventManager,
                                 Registry registry,
                                 java.lang.Class<S> sharingSourceClass,
                                 java.lang.String eventType,
                                 java.lang.String sourceType)

Default constructor for a plugin of the DefaultEventManager called by a service registry.

Parameters:

conf - The configuration as provided from the registry. Since this is a shared event source, the configuration will be ignored and only the explicitly set configuration will be used. This is usually a configuration of a/all sharing event sources.

eventManager - The event manager this event source is a plugin of.

registry - The registry of this plugin.

sharingSourceClass - The class of S, used for type checks.

eventType - The event type, cf. Event.getEventType().

sourceType - The name of the source type.

Method Detail

getEventType

protected java.lang.String getEventType()

Gets the type of the events, this shared event source generates.

Returns:

The type of the events, this shared event source generates.

See Also:

Event.getEventType()

getType

public java.lang.String getType()

Description copied from interface: EventSource

Gets the type of this source. This is usually the simple instance name of the plugin, if the event source has been loaded as plugin.

Specified by:

getType in interface EventSource<E extends Event>

Returns:

The type of this source.

getID

public java.lang.String getID()

Description copied from interface: EventSource

Gets the ID of this source. Until separately set this ID is arbitrary and may even be null.

Specified by:

getID in interface EventSource<E extends Event>

Returns:

The ID of this source.

getHierarchicalSourceName

public java.lang.String getHierarchicalSourceName()

Description copied from interface: EventSource

Gets the hierarchical name of this source, that is the event type, the source type and the source ID for usage in log messages and alike.

Specified by:

getHierarchicalSourceName in interface EventSource<E extends Event>

Returns:

The hierarchical name of this source, that is the event type, the source type and the source ID.

setConfiguration

public void setConfiguration(Configuration conf,
                             java.lang.String id)
                      throws ConfigurationException

Description copied from interface: EventSource

Sets the (additional) configuration of this event source and its ID. The configuration is additional with respect to the configuration provided by the plugin load mechanism, if the event source is loaded as plugin.
It is ensured that this method will be called before Runnable.run().

Specified by:

setConfiguration in interface EventSource<E extends Event>

Parameters:

conf - The configuration of this event source. This adheres (and overwrites) the configuration provided by the plugin loading, if this event source has been loaded as plugin. Whether this is allowed to be null depends on the implementation of the event source.

id - The ID of this event source. This must not be null nor the empty string.

Throws:

ConfigurationException - If there are problems with the designated configuration (configuration is null although this is not allowed, a required configuration value is missing, ...), a ConfigurationException will be thrown.

parseConfiguration

protected void parseConfiguration(Configuration conf)
                           throws ConfigurationException

Parses the designated (initial) configuration. Subclasses should parse the configuration values they need from it.
The designated configuration will usually be the initial configuration right after setting it.

This implementation does nothing as default.

Parameters:

conf - The configuration to parse the required configuration values from.

Throws:

ConfigurationException - If there are problems with the designated configuration, for instance the configuration does not provide required values, a ConfigurationException may be thrown.

getEventHandler

public java.util.List<EventHandler> getEventHandler()

Description copied from interface: EventSource

Gets the event handler that have been registered for this event source. These handler are notified about an event in the designated order.

Specified by:

getEventHandler in interface EventSource<E extends Event>

Returns:

The event handler that have been registered for this event source.

addHandler

public void addHandler(EventHandler handler,
                       int index)

Description copied from interface: EventSource

Adds the designated handler at the designated position (0-based) to the list of registered handler. It is not checked, whether the handler is already registered.

Specified by:

addHandler in interface EventSource<E extends Event>

Parameters:

handler - The handler which to add.

index - The index (0-based) at which to add the handler in the list.

addAll

public void addAll(java.util.List<EventHandler> handlers)

Description copied from interface: EventSource

Adds the designated event handler in the designated order to the list of the handler that are already registered. It is not checked whether a handler is already registered (and neither whether a handler is several times in the designated list.

Specified by:

addAll in interface EventSource<E extends Event>

Parameters:

handlers - The handler to register in the designated order. They are added at the end of the list of handler that are already registered.

removeHandler

public EventHandler removeHandler(java.lang.String handlerID)

Description copied from interface: EventSource

Removes the handler with the designated ID from the list and returns it. If there is no handler registered with the designated ID, null will be returned.

Specified by:

removeHandler in interface EventSource<E extends Event>

Parameters:

handlerID - The ID of the handler which to remove.

Returns:

The removed handler or null in case no handler with the designated ID has been registered.

init

public void init()

Description copied from interface: PollingSource

Initialises this polling source. This is called once before polling is started the first time.

Specified by:

init in interface PollingSource<E extends Event>

terminate

public void terminate()

Description copied from interface: PollingSource

Terminates this polling source. This is called once after polling has terminated and this source is removed.
Note that this may be called any time, even when creating or handling an event. So take care to synchronise the implementation appropriately!

Specified by:

terminate in interface PollingSource<E extends Event>

supportsSharingSource

public boolean supportsSharingSource(SharingSource<?> source)

Gets whether this shared source can handle the designated sharing source and combine it with the already registered sharing sources. This usually analyses some of the configuration values of the designated sharing source. This implementation only checks for whether the designated source has the right class. Usually subclasses need to do more, e. g. check for compatibility of the configuration of the designated sharing source.

Specified by:

supportsSharingSource in interface SharedPollingSource<E extends Event>

Parameters:

source - The source that wants to share a source for polling.

Returns:

Whether this shared source can handle the designated sharing source and combine it with the already registered sharing sources.

addSharingSource

public boolean addSharingSource(SharingSource<?> source)

Description copied from interface: SharedPollingSource

Adds the designated sharing source at this shared source. This will add it to the existing sharing sources by combining the poll for the events.
Implementations should usually also add the designated sharing source as event handler. Callers do not register the sharing source as event handler separately.

Specified by:

addSharingSource in interface SharedPollingSource<E extends Event>

Parameters:

source - The source that wants to share a source for polling.

Returns:

Whether the designated sharing sources has been successfully added. This is quite similar to the return value of SharedPollingSource.supportsSharingSource(SharingSource).

addedSharingSourceLocked

protected boolean addedSharingSourceLocked(java.util.List<java.io.Serializable> sourceKeys,
                                           S source)

Signals subclasses that the designated sharing source has been added to this shared source. The write lock for adding is still held.
Subclasses may refuse to add the designated sharing source by returning false. In this case the sharing source will be removed from this shared source.
Note that supportsSharingSource(SharingSource) has already been called before calling this method.

This implementation does nothing as default.

Parameters:

sourceKeys - The data (key values) of the designated source which also identify it.

source - The sharing source which has been added and should be added to this shared source.

Returns:

Whether the designated sharing sources has been successfully added.

See Also:

addSharingSource(SharingSource)

removeSharingSource

public boolean removeSharingSource(SharingSource<?> source)

Description copied from interface: SharedPollingSource

Removes the designated sharing source from this shared source. This will remove it from the existing sharing sources. Afterwards no polling for the designated sharing source will occur.
Implementations should usually also remove the designated sharing source as event handler. Callers do not unregister the sharing source as event handler separately.

Specified by:

removeSharingSource in interface SharedPollingSource<E extends Event>

Parameters:

source - The source that does no longer want to share a source for polling.

Returns:

Whether the last sharing source has been removed. In this case this shared polling source should also be removed from polling.

removingSharingSourceLocked

protected void removingSharingSourceLocked(java.util.List<java.io.Serializable> sourceKeys,
                                           SharingSource<?> source)

Signals subclasses that the designated sharing source is about to be removed from this shared source. The write lock for removing is still held.

This implementation does nothing as default.

Parameters:

sourceKeys - The data (key values) of the designated source which also identify it.

source - The sharing source which is about to be removed from this shared source.

See Also:

removeSharingSource(SharingSource)

getSourceKeys

protected abstract java.util.List<java.io.Serializable> getSourceKeys(S source)
                                                               throws InvalidDataTypeException,
                                                                      NoSuchParameterException

Gets the data (key values) that identifies the designated sharing event source.
Usually the list should be unmodifiable.

Parameters:

source - The sharing event source for which to retrieve the key values identifying it.

Returns:

A list of key values identifying the designated sharing event source.

Throws:

InvalidDataTypeException - If a parameter reference identifying the designated sharing event source has not the same data type as in the data context, an InvalidDataTypeException will be thrown.

NoSuchParameterException - If a parameter reference identifying the designated sharing event source is not in the data context, an InvalidDataTypeException will be thrown.