de.aristaflow.adept2.core.eventmanager.common

Class AbstractSharingActEventSource<T extends Event>

java.lang.Object

de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource<T>

de.aristaflow.adept2.core.eventmanager.common.AbstractSharingActEventSource<T>

Type Parameters:

T - The type of event this event source creates.

All Implemented Interfaces:

EventHandler, EventSource<T>, SharingSource<T>, java.lang.Runnable

public abstract class AbstractSharingActEventSource<T extends Event>
extends AbstractEventSource<T>
implements SharingSource<T>

A source for events shared among several sharing event sources. That is, this event source does not poll regularly but registers at a shared source that combines several sharing event sources, combines the requesting sharing event sources and polls for all in one go. The sharing event sources registered at the same shared event source need to be of a common type that supports sharing, e. g. an SQL statement that differs only in values but not in the statement itself. The sharing event sources only differ in the values retrieved from the process context (DataContext).

The shared event source which distributes the events among the registered sharing event sources via EventHandler

Field Summary

Fields

Modifier and Type	Field and Description
protected Configuration	conf The configuration containing all relevant values for this sharing event source as retrieved from the registry and the activity.
protected java.lang.Class<T>	eventClass The event class, used for type checking.
protected java.lang.String	sharedSourceType The type of the event source.

Fields inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource

eventType, handlerList, id, lock, logger, sourceType, thread, threadLock

Constructor Summary

Constructors

Constructor and Description
AbstractSharingActEventSource(Configuration conf, Registry registry, java.lang.Class<T> eventClass, java.lang.String eventType, java.lang.String sharedSourceType) Default constructor for a plugin of the DefaultEventManager called by a service registry.

Method Summary

Modifier and Type	Method and Description
protected void	addedHandlerLocked(int index, EventHandler handler) Signals subclasses that the designated event handler has been added to this event source at the designated index.
protected void	addedHandlerLocked(java.util.List<EventHandler> handlers) Signals subclasses that the designated event handlers have been added to this event source at the end of the list of event handlers.
void	checkForAndHandleEvent() Checks for an event and handles it (usually by using AbstractEventSource.forwardEvent(Event, boolean, boolean)).
protected abstract T	createForwardEvent(T event) Create a copy of the given event for forwarding it, i. e. replacing the source ID with AbstractEventSource.getID().
Configuration	getConfiguration() Gets the (final) configuration of this sharing source.
SerialisableDataContext	getDataContext() Gets the data context of this sharing source.
java.lang.String	getSharedSourceEventType() Gets the event type of the shared event source, that is the event type of the event source used by this sharing source.
java.lang.String	getSharedSourceId() Gets the ID of the shared event source, that is the ID of the event source used by this sharing source.
java.lang.String	getSharedSourceType() Gets the type of the shared event source, that is the type of the event source used by this sharing source.
boolean	handleEvent(Event eve, boolean consumed) This method actually processes an event.
boolean	isConsuming() Gets whether this event handler is consuming and therefore may change or consume an event while processing it.
boolean	isExclusive() Gets whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.
boolean	isInterruptible() Whether this event handler can be interrupted while handling an event.
protected boolean	nextHandler(T event, boolean consumed, boolean concurrent) This method is called right before an event is offered to the next handler.
protected void	removingHandlerLocked(int index, EventHandler handler) Signals subclasses that the designated event handler is about to be removed from the designated index of the handler list of this event source.
protected void	setConfiguration(Configuration newConf, boolean completed) Adds the relevant values from the designated configuration in the own configuration of this sharing event source overriding existing values. and verifies the complete configuration if completed.
void	setConfiguration(Configuration conf, java.lang.String id) Sets the (additional) configuration of this event source and its ID.
void	setSharedSourceId(java.lang.String sourceId) Sets the ID of the shared event source, that is the ID of the event source used by this sharing source.
protected void	takeOverConfValuesFromConfiguration(Configuration source, Configuration target) Takes over all relevant configuration values from the designated source to the designated target configuration.
protected void	takeOverConfValuesFromContext(SimpleSessionContext source, Configuration target) Takes over all relevant configuration values from the designated session context (usually from the corresponding activity configuration but may also be based on other elemest of the session context.
protected void	verifyConfigurationValues(Configuration configuration) Verifies that all required configuration values have been set in the designated configuration.

Methods inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource

addAll, addHandler, createPattern, forwardEvent, getEventHandler, getHierarchicalSourceName, getID, getType, maskedInterrupt, maskInterrupt, removeHandler, replaceValueParams, run, unmaskInterrupt

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.EventSource

addAll, addHandler, getEventHandler, getHierarchicalSourceName, getID, getType, removeHandler

Methods inherited from interface java.lang.Runnable

run

Methods inherited from interface de.aristaflow.adept2.model.events.handler.EventHandler

getID

Field Detail

eventClass

protected final java.lang.Class<T extends Event> eventClass

The event class, used for type checking.

sharedSourceType

protected final java.lang.String sharedSourceType

The type of the event source.

conf

protected final Configuration conf

The configuration containing all relevant values for this sharing event source as retrieved from the registry and the activity. This will be empty at first and will be filled when setting the configuration.

Constructor Detail

AbstractSharingActEventSource

public AbstractSharingActEventSource(Configuration conf,
                                     Registry registry,
                                     java.lang.Class<T> eventClass,
                                     java.lang.String eventType,
                                     java.lang.String sharedSourceType)
                              throws ConfigurationException

Default constructor for a plugin of the DefaultEventManager called by a service registry. It validates the configuration with respect to this class including super-classes and interfaces.

Note that this constructor calls setConfiguration(Configuration, boolean); subclasses may not be fully initialised at this point.

Parameters:

conf - The configuration as provided from the registry.

registry - The registry of this plugin.

eventClass - The class of the event, used for type checking during event handling.

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

sharedSourceType - The type of the shared source.

Throws:

ConfigurationException - If the configuration is not valid for a ResultSetSource, a ConfigurationException will be thrown.

Method Detail

setConfiguration

protected void setConfiguration(Configuration newConf,
                                boolean completed)
                         throws ConfigurationException

Adds the relevant values from the designated configuration in the own configuration of this sharing event source overriding existing values. and verifies the complete configuration if completed. If a configuration value is missing or inappropriate, a ConfigurationException will be thrown.
Since this is an activity event source, it expects a session context to be provided with one of the configurations. This will provide the data context as well as an activity configuration. The activity configuration will also override the configuration values set so far.

Parameters:

newConf - The configuration which to set.

completed - Whether the configuration is complete after this setting and therefore the values should be verified.

Throws:

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

takeOverConfValuesFromConfiguration

protected void takeOverConfValuesFromConfiguration(Configuration source,
                                                   Configuration target)

Takes over all relevant configuration values from the designated source to the designated target configuration.
The target will usually be the field conf.

This implementation does nothing as default.

Parameters:

source - The source configuration to read relevant configuration values from.

target - The target configuration in which to write relevant configuration values to.

takeOverConfValuesFromContext

protected void takeOverConfValuesFromContext(SimpleSessionContext source,
                                             Configuration target)

Takes over all relevant configuration values from the designated session context (usually from the corresponding activity configuration but may also be based on other elemest of the session context.
The target will usually be the field conf.

This implementation does nothing as default.

Parameters:

source - The session context to read relevant configuration values from.

target - The target configuration in which to write relevant configuration values to.

verifyConfigurationValues

protected void verifyConfigurationValues(Configuration configuration)
                                  throws ConfigurationException

Verifies that all required configuration values have been set in the designated configuration. If a configuration value is missing or inappropriate, a ConfigurationException will be thrown.
The target will usually be the field conf.

This implementation does nothing as default.

Parameters:

configuration - The configuration of which to verify its values.

Throws:

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

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<T extends Event>

Overrides:

setConfiguration in class AbstractEventSource<T 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.

getSharedSourceEventType

public java.lang.String getSharedSourceEventType()

Description copied from interface: SharingSource

Gets the event type of the shared event source, that is the event type of the event source used by this sharing source. This may be the same event type as this sharing source.

Specified by:

getSharedSourceEventType in interface SharingSource<T extends Event>

Returns:

The event type of the shared event source, that is the event type of the event source used by this sharing source.

getSharedSourceType

public java.lang.String getSharedSourceType()

Description copied from interface: SharingSource

Gets the type of the shared event source, that is the type of the event source used by this sharing source. This usually has to be different from the type of this source (EventSource.getType()).

Specified by:

getSharedSourceType in interface SharingSource<T extends Event>

Returns:

The type of the shared event source, that is the type of the event source used by this sharing source.

getSharedSourceId

public java.lang.String getSharedSourceId()

Description copied from interface: SharingSource

Gets the ID of the shared event source, that is the ID of the event source used by this sharing source. This will probably be null until explicitly set by the event manager.

Specified by:

getSharedSourceId in interface SharingSource<T extends Event>

Returns:

The ID of the shared event source, that is the ID of the event source used by this sharing source or null in case the ID has not been set yet.

setSharedSourceId

public void setSharedSourceId(java.lang.String sourceId)

Description copied from interface: SharingSource

Sets the ID of the shared event source, that is the ID of the event source used by this sharing source.

Specified by:

setSharedSourceId in interface SharingSource<T extends Event>

Parameters:

sourceId - The ID of the shared event source, that is the ID of the event source used by this sharing source.

getConfiguration

public Configuration getConfiguration()

Description copied from interface: SharingSource

Gets the (final) configuration of this sharing source. This is used to provide an appropriate shared source. Only sharing sources having the same configuration values (for at least parts of the configuration) may share a source. Otherwise they will get a non-shared source.

Specified by:

getConfiguration in interface SharingSource<T extends Event>

Returns:

The (final) configuration of this sharing source which is used to determine which sharing sources may share a source.

getDataContext

public SerialisableDataContext getDataContext()

Description copied from interface: SharingSource

Gets the data context of this sharing source. This provides the process context that usually identifies this sharing source uniquely in the shared source.

Specified by:

getDataContext in interface SharingSource<T extends Event>

Returns:

The data context of this sharing source and therefore the process context which is usually used by the shared source to identify a sharing source.

addedHandlerLocked

protected void addedHandlerLocked(int index,
                                  EventHandler handler)

Description copied from class: AbstractEventSource

Signals subclasses that the designated event handler has been added to this event source at the designated index. The write lock for adding is still held.

This implementation does nothing as default.

Overrides:

addedHandlerLocked in class AbstractEventSource<T extends Event>

Parameters:

index - The index (position in the list of all handlers) at which the designated handler has been added to this event source.

handler - The event handler which has been added to this event source.

See Also:

AbstractEventSource.addHandler(EventHandler, int)

addedHandlerLocked

protected void addedHandlerLocked(java.util.List<EventHandler> handlers)

Description copied from class: AbstractEventSource

Signals subclasses that the designated event handlers have been added to this event source at the end of the list of event handlers. The write lock for adding is still held.

This implementation does nothing as default.

Overrides:

addedHandlerLocked in class AbstractEventSource<T extends Event>

Parameters:

handlers - The event handlers which have been added to this event source.

See Also:

AbstractEventSource.addAll(List)

removingHandlerLocked

protected void removingHandlerLocked(int index,
                                     EventHandler handler)

Description copied from class: AbstractEventSource

Signals subclasses that the designated event handler is about to be removed from the designated index of the handler list of this event source. The write lock for removing is still held.

This implementation does nothing as default.

Overrides:

removingHandlerLocked in class AbstractEventSource<T extends Event>

Parameters:

index - The index (position in the list of all handlers) from which the designated handler will be removed from this event source.

handler - The event handler which is about to be removed from this event source.

See Also:

AbstractEventSource.removeHandler(String)

nextHandler

protected boolean nextHandler(T event,
                              boolean consumed,
                              boolean concurrent)

Description copied from class: AbstractEventSource

This method is called right before an event is offered to the next handler. In case of concurrent handling, this method will only be called once for all concurrent handling but this will be indicated by the corresponding parameter.

Specified by:

nextHandler in class AbstractEventSource<T extends Event>

Parameters:

event - The event which is about to be handled by the next registered handler.

consumed - Whether the event has been consumed yet.

concurrent - Whether the next event handling is concurrent and thus the event will be offered to several event handler concurrently.

Returns:

Whether the event handling may continue. In case of serious problems preventing further event handling, return false here.

isExclusive

public boolean isExclusive()

Description copied from interface: EventHandler

Gets whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.
In case of a consuming handler, exclusive handling is always implicitly presumed.

Specified by:

isExclusive in interface EventHandler

Returns:

Whether this event handler is exclusive and thus no concurrent event handling should take place while this handler is processing an event.

isConsuming

public boolean isConsuming()

Description copied from interface: EventHandler

Gets whether this event handler is consuming and therefore may change or consume an event while processing it. This does not indicate that all events will be consumed when handled.
A consuming handler is always exclusive.

Specified by:

isConsuming in interface EventHandler

Returns:

Whether this event handler is consuming and thus may change or consume an event while processing it.

isInterruptible

public boolean isInterruptible()

Description copied from interface: EventHandler

Whether this event handler can be interrupted while handling an event. If so, it must expect an interrupt any time. If not, it has to be aware that the event may have been cancelled while handling.
This must not change at any time.

Specified by:

isInterruptible in interface EventHandler

Returns:

Whether this event handler can be interrupted while handling an event.

handleEvent

public boolean handleEvent(Event eve,
                           boolean consumed)
                    throws EventHandlingException

Description copied from interface: EventHandler

This method actually processes an event. What is done depends on the implementation of the event handler. Some restrictions may apply depending on the produced event. Only events will be received for which the event handler is registered. However, to improve robustness, an event handler should check the event before processing. If it cannot handle the provided event, this method should just return.
Event handling is usually synchronously, that is, this method will only be executed by one thread at a time. If another event of the same type occurs while still handling the previous event, the second event will be suspended until the previous event has been completely handled. There is no need to start a separate thread while handling to improve performance. But it is not forbidden to do so. Handling that takes place in a new thread is not exclusive any more and therefore must not consume the event!

Specified by:

handleEvent in interface EventHandler

Parameters:

eve - The event that occurred and for which this event handler is registered.

consumed - Whether the event has been consumed by a previous event handler.

Returns:

Whether the event has been consumed (that is changed) while handling it. If the event has been consumed before the current handing, it will have to remain consumed (implementations must return true).

Throws:

EventHandlingException - If there have been problems handling the event, an EventHandlingException may be thrown. If this is critical, the event handling for the current event will stop. If it is non-critical, other event handlers will also get the event for handling it.
If event handling fails, the corresponding event handler needs to roll back its changes, especially a consuming event handler.

checkForAndHandleEvent

public void checkForAndHandleEvent()

Description copied from class: AbstractEventSource

Checks for an event and handles it (usually by using AbstractEventSource.forwardEvent(Event, boolean, boolean)).

Specified by:

checkForAndHandleEvent in class AbstractEventSource<T extends Event>

createForwardEvent

protected abstract T createForwardEvent(T event)

Create a copy of the given event for forwarding it, i. e. replacing the source ID with AbstractEventSource.getID().

Parameters:

event - The event to be copied.

Returns:

The new, copied event which will be forwarded.