de.aristaflow.adept2.core.eventmanager.dbevents

Class DBEventSource

java.lang.Object

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

de.aristaflow.adept2.core.eventmanager.dbevents.DBEventSource

All Implemented Interfaces:

EventSource<ResultSetEvent>, PollingSource<ResultSetEvent>, ResultSetSource, java.lang.Runnable

Direct Known Subclasses:

DBActivityEventSource, ReadOnlyRSEventSource

public class DBEventSource
extends AbstractEventSource<ResultSetEvent>
implements PollingSource<ResultSetEvent>, ResultSetSource

A source for events based on SQL statements, that is a SQL statement is executed regularly and the result set (if one exists) is notified as event to the corresponding event handler.
This event source terminates as soon as an event has been handled by all registered handler.

To simplify events caused by non-existence, the event source can be configured to send the event only if the result set is empty. In this case the empty result set will be attached to the event.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	dataSource The simple instance name of the data source which to poll for the event.
protected DefaultEventManager	eventManager The event manager of this data source providing the connection to the data source.
protected java.lang.String	jdbcConnectionURL The URL to connect to the database.
protected java.lang.String	jdbcDriver The fully-qualified name of the class of the JDBC-driver.
protected java.lang.String	jdbcPassword The password to log on a the database with.
protected java.lang.String	jdbcUserName The name of the user to log on at the database with.
protected java.lang.Boolean	notifyEmptyOnly Whether the event should be produced in case the result set is empty.
protected java.lang.Long	pollTime The time in milliseconds this event source polls its data source.
protected java.lang.String	selectStatement The statement which is executed and provides the result set for the event.
protected java.lang.Long	startTime The start point (in milliseconds) this event should start polling.

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

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

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

CONF_POLL_TIME, CONF_START_TIME

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

CONF_DATA_SOURCE_NAME, CONF_JDBC_CONNECTION_URL, CONF_JDBC_DRIVER, CONF_JDBC_PASSWORD, CONF_JDBC_USER_NAME, CONF_NOTIFY_EMPTY_ONLY, CONF_SELECT_STATEMENT

Constructor Summary

Constructors

Constructor and Description
DBEventSource(Configuration conf, DefaultEventManager eventManager, Registry registry) Default constructor for a plugin of the DefaultEventManager called by a service registry.

Method Summary

Modifier and Type	Method and Description
void	checkForAndHandleEvent() Checks for an event and handles it (usually by using AbstractEventSource.forwardEvent(Event, boolean, boolean)).
protected ResultSetEvent	createResultSetEvent(java.sql.ResultSet resultSet) Creates a ResultSetEvent for the designated result set.
long	getPollTime() Gets the time in milliseconds this event source polls, more precisely, the time span between two polls.
long	getStartTime() Gets the absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling.
void	init() Initialises this polling source.
protected boolean	nextHandler(ResultSetEvent event, boolean consumed, boolean concurrent) This method is called right before an event is offered to the next handler.
protected void	setConfiguration(Configuration conf, boolean completed) Sets the internal fields according to the values of the designated configuration.
void	setConfiguration(Configuration conf, java.lang.String id) Sets the (additional) configuration of this event source and its ID.
void	terminate() Terminates this polling source.
protected void	verifyConfigurationValues() This method verifies whether the required configuration values and the data context have been set yet.

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

addAll, addedHandlerLocked, addedHandlerLocked, addHandler, createPattern, forwardEvent, getEventHandler, getHierarchicalSourceName, getID, getType, maskedInterrupt, maskInterrupt, removeHandler, removingHandlerLocked, 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

Field Detail

pollTime

protected java.lang.Long pollTime

The time in milliseconds this event source polls its data source.

startTime

protected java.lang.Long startTime

The start point (in milliseconds) this event should start polling.

dataSource

protected java.lang.String dataSource

The simple instance name of the data source which to poll for the event. This is not required if the driver, the connection URL, the user name and the password are provided instead. If all are provided, the data source will be used.

jdbcDriver

protected java.lang.String jdbcDriver

The fully-qualified name of the class of the JDBC-driver. This is only required if no data source is provided.

jdbcConnectionURL

protected java.lang.String jdbcConnectionURL

The URL to connect to the database. This is only required if no data source is provided.

jdbcUserName

protected java.lang.String jdbcUserName

The name of the user to log on at the database with. This is only required if no data source is provided.

jdbcPassword

protected java.lang.String jdbcPassword

The password to log on a the database with. This is only required if no data source is provided.

selectStatement

protected java.lang.String selectStatement

The statement which is executed and provides the result set for the event.

notifyEmptyOnly

protected java.lang.Boolean notifyEmptyOnly

Whether the event should be produced in case the result set is empty.

eventManager

protected final DefaultEventManager eventManager

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

Constructor Detail

DBEventSource

public DBEventSource(Configuration conf,
                     DefaultEventManager eventManager,
                     Registry registry)
              throws ConfigurationException

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

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.

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

registry - The registry of this plugin.

Throws:

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

Method Detail

setConfiguration

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

Sets the internal fields according to the values of the designated configuration. Note that this method is called from the constructor and therefore this object may not be fully initialised!

Parameters:

conf - The configuration from which to get the configuration values.

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.

verifyConfigurationValues

protected void verifyConfigurationValues()
                                  throws ConfigurationException

This method verifies whether the required configuration values and the data context have been set yet. If configuration values or the data context are missing or inappropriate, a ConfigurationException will be thrown.

Throws:

ConfigurationException - If there are problems with the configuration, for instance the configuration does not provide required values or the data context is not set, 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<ResultSetEvent>

Overrides:

setConfiguration in class AbstractEventSource<ResultSetEvent>

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.

getPollTime

public long getPollTime()

Description copied from interface: PollingSource

Gets the time in milliseconds this event source polls, more precisely, the time span between two polls. If this is 0 or negative, no polling will apply. However, PollingSource.init() and PollingSource.terminate() will be called.

Specified by:

getPollTime in interface PollingSource<ResultSetEvent>

Returns:

The time in milliseconds this event source polls (> 0).

getStartTime

public long getStartTime()

Description copied from interface: PollingSource

Gets the absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling. This is used for calculating the first poll time by adding the time span defined in PollingSource.getPollTime().

Specified by:

getStartTime in interface PollingSource<ResultSetEvent>

Returns:

The absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling.

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<ResultSetEvent>

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<ResultSetEvent>

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<ResultSetEvent>

createResultSetEvent

protected ResultSetEvent createResultSetEvent(java.sql.ResultSet resultSet)

Creates a ResultSetEvent for the designated result set.

Parameters:

resultSet - The result set for which to create a ResultSetEvent.

Returns:

The ResultSetEvent created for the designated result set.

nextHandler

protected boolean nextHandler(ResultSetEvent 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<ResultSetEvent>

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.