Package org.marketcetera.modules.cep.esper

Class CEPEsperProcessor

java.lang.Object

org.marketcetera.module.Module

org.marketcetera.modules.cep.esper.CEPEsperProcessor

All Implemented Interfaces:

DataEmitter, DataReceiver, CEPEsperProcessorMXBean

public class CEPEsperProcessor
extends Module
implements DataReceiver, DataEmitter, CEPEsperProcessorMXBean

A module that processes data using the Esper Runtime. The module can receive any type of data. Null data values are ignored. Map and Node data types are supplied to the esper runtime so that esper specific interpretation is possible. All maps are supplied to the runtime with the type name map.

When requesting data, either an EPL or a Pattern query has to be specified. The results of the query are emitted to the next module in the data flow.

Multiple queries can be submitted when creating a data flow. When multiple queries are submitted, only the results of the last query are emitted to the next stage in the data flow.

Any errors in the query syntax will result in an error when setting up the data flow, except when the module is configured to use external time.

If the module is configured to use external time, errors in query syntax are not reported until after the module has received data that implements TimestampCarrier. Errors in query will result in the data flow being cancelled. When configured to use external time, the module creates the query statements after it receives the first TimestampCarrier. Any non-TimestampCarrier received prior to that are reported and ignored.

Module Features

CEPEsperProcessor capabilities

Capabilities	Data Emitter, Data Receiver
DataFlow Request Parameters	String: CEP query; String[]: Multiple CEP queries
Stops data flows	If it encounters an error when creating statements in external time mode.
Start Operation	Initializes Esper Runtime
Stop Operation	Destroys Esper Runtime
Management Interface	CEPEsperProcessorMXBean
Factory	CEPEsperFactory

Since:

1.0.0

Version:

$Id$

Author:

anshul@marketcetera.com, toli@marketcetera.com

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private class	CEPEsperProcessor.ExternalTimeDelegate	Responsible for implemneting external time behaviour - instead of sending the querieis straight to Esper, we wait until the first time event comes in, and only start CEP then
private static interface	CEPEsperProcessor.ProcessingDelegate	Basic interface to describe a data flow processing delegate.
private class	CEPEsperProcessor.RegularDelegate	Regular "straight-through" delegate - just send all the incoming queries directly to Esper This is for non-external-time (ie for wall-clock time) operation.
static class	CEPEsperProcessor.Subscriber	A Subscriber class that subscribes to the query statement results and emits them out to the flow that requested that statement.

Field Summary

Fields

Modifier and Type	Field	Description
private String	mConfiguration	Configuration file location.
private CEPEsperProcessor.ProcessingDelegate	mDelegate	The processing delegate to use.
private Map<RequestID,List<com.espertech.esper.client.EPStatement>>	mRequests	The table of requests that this module is currently processing.
private ThreadLocal<Integer>	mSelfPostingEvents	Reference counter that keep track if we get events posted back into us from events that we emit ie we emit to a strategy that sends events in back to this Esper instance 0 means "not self-posted event", ie "send regular events to Esper"
private com.espertech.esper.client.EPServiceProvider	mService	The Esper engine runtime.
private boolean	mUseExternalTime	If the module should be configured for external time.
private static String	PATTERN_QUERY_PREFIX	The prefix for pattern queries - they all start with p:xxxxx

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	CEPEsperProcessor(ModuleURN inURN)	Creates an instance.
protected	CEPEsperProcessor(ModuleURN inURN, boolean inAutoStart)

Method Summary

Modifier and Type	Method	Description
void	cancel(DataFlowID inFlowID, RequestID inRequestID)
protected ArrayList<com.espertech.esper.client.EPStatement>	createStatements(String... inQuery)	Submits the supplied queries to the runtime and returns the statement objects representing each one of those queries.
String	getConfiguration()	Specifies the location of the configuration file for the module.
private CEPEsperProcessor.ProcessingDelegate	getDelegate()
long	getNumEventsReceived()	Returns the number of events received over the lifetime of the event stream processing runtime.
String[]	getStatementNames()	Returns the names of all the statements currently being handled by the runtime.
boolean	isUseExternalTime()	If the runtime should use external time source.
protected void	preStart()
protected void	preStop()
void	receiveData(DataFlowID inFlowID, Object inData)	Need to keep a reference count in case of nested events being sent out of Esper and posted back in Increment the count before, and then decrement after
void	requestData(DataRequest inRequest, DataEmitterSupport inSupport)
void	setConfiguration(String inConfiguration)	Specifies the location of the configuration file for the module.
void	setUseExternalTime(boolean inUseExternalTime)	If the runtime should use external time source.

Methods inherited from class org.marketcetera.module.Module

getCreated, getLastStartFailure, getLastStopFailure, getStarted, getState, getStopped, getURN, isAutoCreated, isAutoStart

Methods inherited from class java.lang.Object

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

Field Detail

mSelfPostingEvents

private final ThreadLocal<Integer> mSelfPostingEvents

Reference counter that keep track if we get events posted back into us from events that we emit ie we emit to a strategy that sends events in back to this Esper instance 0 means "not self-posted event", ie "send regular events to Esper"

mService

private com.espertech.esper.client.EPServiceProvider mService

The Esper engine runtime.

mRequests

private final Map<RequestID,List<com.espertech.esper.client.EPStatement>> mRequests

The table of requests that this module is currently processing.

mConfiguration

private String mConfiguration

Configuration file location.

mUseExternalTime

private volatile boolean mUseExternalTime

If the module should be configured for external time.

PATTERN_QUERY_PREFIX

private static final String PATTERN_QUERY_PREFIX

The prefix for pattern queries - they all start with p:xxxxx

See Also:

Constant Field Values

mDelegate

private volatile CEPEsperProcessor.ProcessingDelegate mDelegate

The processing delegate to use.

Constructor Detail

CEPEsperProcessor

protected CEPEsperProcessor(ModuleURN inURN,
                            boolean inAutoStart)

CEPEsperProcessor

protected CEPEsperProcessor(ModuleURN inURN)

Creates an instance.

Parameters:

inURN - the module URN.

Method Detail

requestData

public void requestData(DataRequest inRequest,
                        DataEmitterSupport inSupport)
                 throws UnsupportedRequestParameterType,
                        IllegalRequestParameterValue

Specified by:

requestData in interface DataEmitter

Throws:

UnsupportedRequestParameterType

IllegalRequestParameterValue

cancel

public void cancel(DataFlowID inFlowID,
                   RequestID inRequestID)

Specified by:

cancel in interface DataEmitter

receiveData

public void receiveData(DataFlowID inFlowID,
                        Object inData)
                 throws UnsupportedDataTypeException,
                        StopDataFlowException

Need to keep a reference count in case of nested events being sent out of Esper and posted back in Increment the count before, and then decrement after

Specified by:

receiveData in interface DataReceiver

Throws:

UnsupportedDataTypeException

StopDataFlowException

getConfiguration

public String getConfiguration()

Description copied from interface: CEPEsperProcessorMXBean

Specifies the location of the configuration file for the module. The location is first interpreted as a URL. If URL creation fails with a malformed URL exception, an attempt is made to interpret the location as a local file. If the file doesn't exist, the value is interpreted as the name of a classpath resource. If the configuration is not found via any of these interpretations an exception is thrown during module start. If a null value is specified, an empty configuration is used.

Specified by:

getConfiguration in interface CEPEsperProcessorMXBean

Returns:

the location of the configuration file.

setConfiguration

public void setConfiguration(String inConfiguration)

Description copied from interface: CEPEsperProcessorMXBean

Specifies the location of the configuration file for the module.

Specified by:

setConfiguration in interface CEPEsperProcessorMXBean

Parameters:

inConfiguration - the location of the configuration file.

See Also:

CEPEsperProcessorMXBean.getConfiguration()

getStatementNames

public String[] getStatementNames()

Description copied from interface: CEPEsperProcessorMXBean

Returns the names of all the statements currently being handled by the runtime.

Specified by:

getStatementNames in interface CEPEsperProcessorMXBean

Returns:

the names of all the statements.

getNumEventsReceived

public long getNumEventsReceived()

Description copied from interface: CEPEsperProcessorMXBean

Returns the number of events received over the lifetime of the event stream processing runtime.

Specified by:

getNumEventsReceived in interface CEPEsperProcessorMXBean

Returns:

number of events received.

isUseExternalTime

public boolean isUseExternalTime()

Description copied from interface: CEPEsperProcessorMXBean

If the runtime should use external time source.

Specified by:

isUseExternalTime in interface CEPEsperProcessorMXBean

Returns:

if the runtime should use external time source.

setUseExternalTime

public void setUseExternalTime(boolean inUseExternalTime)

Description copied from interface: CEPEsperProcessorMXBean

If the runtime should use external time source.

Specified by:

setUseExternalTime in interface CEPEsperProcessorMXBean

Parameters:

inUseExternalTime - if the runtime should use external time source.

preStart

protected void preStart()
                 throws ModuleException

Specified by:

preStart in class Module

Throws:

ModuleException

preStop

protected void preStop()

Specified by:

preStop in class Module

createStatements

protected ArrayList<com.espertech.esper.client.EPStatement> createStatements(String... inQuery)
                                                                      throws com.espertech.esper.client.EPException

Submits the supplied queries to the runtime and returns the statement objects representing each one of those queries.

Parameters:

inQuery - the EPL and Pattern queries.

Returns:

The statements representing the submitted queries.

Throws:

com.espertech.esper.client.EPException - in case the statements cannot be created

getDelegate

private CEPEsperProcessor.ProcessingDelegate getDelegate()