de.aristaflow.adept2.core.eventmanager.common

Class AbstractEventSource<T extends Event>

java.lang.Object

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

Type Parameters:

T - The type of events this event source creates.

All Implemented Interfaces:

EventSource<T>, java.lang.Runnable

Direct Known Subclasses:

AbstractSharingActEventSource, DBEventSource, FileEventSource, MailEventSource

public abstract class AbstractEventSource<T extends Event>
extends java.lang.Object
implements EventSource<T>

This abstract class provides the means for managing the handler registered for an event source.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	eventType The ID (name) of the events this event source produces.
protected java.util.List<EventHandler>	handlerList All handler registered for this event source.
protected java.lang.String	id The ID of this event source.
protected java.util.concurrent.locks.ReadWriteLock	lock The lock for synchronising accesses to the list of handler.
protected java.util.logging.Logger	logger The logger for exceptions that occur when handling an event.
protected java.lang.String	sourceType The type of this event source.
protected java.lang.Thread	thread The thread currently running, null if no thread is running.
protected java.util.concurrent.locks.ReadWriteLock	threadLock The lock for synchronising access to the thread and the interrupt handling.

Constructor Summary

Constructors

Constructor and Description
AbstractEventSource(Registry registry, java.lang.String eventType) Creates a new event source providing the management of registered event handler.
AbstractEventSource(java.lang.String sourceType, java.lang.String eventType) Creates a new event source providing the management of registered event handler.

Method Summary

Modifier and Type	Method and Description
void	addAll(java.util.List<EventHandler> handler) Adds the designated event handler in the designated order to the list of the handler that are already registered.
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	addHandler(EventHandler handler, int index) Adds the designated handler at the designated position (0-based) to the list of registered handler.
protected abstract void	checkForAndHandleEvent() Checks for an event and handles it (usually by using forwardEvent(Event, boolean, boolean)).
protected java.util.regex.Pattern	createPattern(java.lang.String filter) Creates a pattern for the designated filter.
protected boolean	forwardEvent(T event, boolean consumed, boolean concurrent) Sends the designated event to all registered event handler.
java.util.List<EventHandler>	getEventHandler() Gets the event handler that have been registered for this event source.
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.
java.lang.String	getType() Gets the type of this source.
protected void	maskedInterrupt() Interrupts the current thread if there is one.
protected void	maskInterrupt() Masks interrupts that occur after calling this method.
protected abstract boolean	nextHandler(T event, boolean consumed, boolean concurrent) This method is called right before an event is offered to the next handler.
EventHandler	removeHandler(java.lang.String handlerID) Removes the handler with the designated ID from the list and returns it.
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 java.lang.String	replaceValueParams(java.lang.String value, InputDataContext dataContext) Wraps ParamRefTools#replaceParams(String, InputDataContext) by allowing for null and the empty string as value.
void	run() This method tracks the running state of this source and delegates to subclasses for checking for an event and handling it appropriately.
void	setConfiguration(Configuration conf, java.lang.String id) Sets the (additional) configuration of this event source and its ID.
protected boolean	unmaskInterrupt() Unmasks the interrupt once.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final java.util.logging.Logger logger

The logger for exceptions that occur when handling an event.

sourceType

protected final java.lang.String sourceType

The type of this event source.

id

protected java.lang.String id

The ID of this event source.

eventType

protected final java.lang.String eventType

The ID (name) of the events this event source produces.

lock

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

The lock for synchronising accesses to the list of handler.

handlerList

protected final java.util.List<EventHandler> handlerList

All handler registered for this event source.

thread

protected volatile java.lang.Thread thread

The thread currently running, null if no thread is running. This allows to prevent concurrent runs and interrupting runs.
Synchronise access to this field via threadLock.

threadLock

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

The lock for synchronising access to the thread and the interrupt handling.

Constructor Detail

AbstractEventSource

public AbstractEventSource(java.lang.String sourceType,
                           java.lang.String eventType)

Creates a new event source providing the management of registered event handler.

Parameters:

sourceType - The type of this event source.

eventType - The ID (name) of the events this event source produces.

AbstractEventSource

public AbstractEventSource(Registry registry,
                           java.lang.String eventType)

Creates a new event source providing the management of registered event handler.

Parameters:

registry - The registry providing the source type of this event source.

eventType - The ID (name) of the events this event source produces.

Method Detail

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

createPattern

protected java.util.regex.Pattern createPattern(java.lang.String filter)

Creates a pattern for the designated filter.
NOTE: This method is used by filtered event sources.

Parameters:

filter - The filter as string which to transform to a pattern.

Returns:

The pattern for the designated filter or null in case the filter is null or the empty string.

replaceValueParams

protected java.lang.String replaceValueParams(java.lang.String value,
                                              InputDataContext dataContext)
                                       throws ConfigurationException

Wraps ParamRefTools#replaceParams(String, InputDataContext) by allowing for null and the empty string as value. In this case null will be returned.
NOTE: This method is used by filtered event activity sources.

Parameters:

value - The configuration value in which to replace parameter references.

dataContext - The data context with which to replace parameter references.

Returns:

A string having all parameter references in the value replaced or null.

Throws:

ConfigurationException - If a parameter in the value cannot be replaced with the designated data context, a ConfigurationException will 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<T 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<T extends Event>

Parameters:

handler - The handler which to add.

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

addedHandlerLocked

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. The write lock for adding is still held.

This implementation does nothing as default.

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:

addHandler(EventHandler, int)

addAll

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

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

Parameters:

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

addedHandlerLocked

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. The write lock for adding is still held.

This implementation does nothing as default.

Parameters:

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

See Also:

addAll(List)

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

removingHandlerLocked

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. The write lock for removing is still held.

This implementation does nothing as default.

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:

removeHandler(String)

run

public final void run()

This method tracks the running state of this source and delegates to subclasses for checking for an event and handling it appropriately. It is ensured that it is not run concurrently on an event source instance. Additionally the handler list will be read locked.

Specified by:

run in interface java.lang.Runnable

checkForAndHandleEvent

protected abstract void checkForAndHandleEvent()

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

forwardEvent

protected boolean forwardEvent(T event,
                               boolean consumed,
                               boolean concurrent)
                        throws EventHandlingException

Sends the designated event to all registered event handler. Concurrent event handling is done if the caller of this method allows it and there are appropriate event handler. Exceptions from the event handling will be logged and handling will continue. However, the first occurred EventHandlingException will be rethrown.
Depending on whether the handler is interruptible or not, while event handling interrupts will be masked. If a masked interrupt occurs, the interrupt flag will be set and this method will return early, that is before all event handler have been notified.

Parameters:

event - The event to be handled by the registered handler.

consumed - Whether the event has been consumed yet.

concurrent - Whether the event can be handled concurrently.

Returns:

Whether the event has been consumed by one of the registered handler.

Throws:

EventHandlingException - The first exception that occurred when handling the designated event.

nextHandler

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

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.

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.

maskInterrupt

protected void maskInterrupt()

Masks interrupts that occur after calling this method. This is reentrant, that is masking is totalled.

unmaskInterrupt

protected boolean unmaskInterrupt()

Unmasks the interrupt once. If there are no more masks and an interrupt occurred while being masked, true will be returned.
Note that a pending interrupt will be set as interrupt in the thread but just as return value of this method.

Returns:

Whether an interrupt occurred while being masked but only if no more masks are left.

maskedInterrupt

protected void maskedInterrupt()

Interrupts the current thread if there is one. If the current thread masks its interrupts, the interrupt will remain pending until the thread has unmasked completely.