com.espertech.esper.client
Interface EPRuntime

All Known Subinterfaces:

EPRuntimeSPI

All Known Implementing Classes:

EPRuntimeImpl

public interface EPRuntime

Interface to event stream processing runtime services.

Method Summary

EPOnDemandQueryResult	executeQuery(EPOnDemandPreparedQueryParameterized parameterizedQuery) Execute an on-demand parameterized query.
EPOnDemandQueryResult	executeQuery(EPOnDemandPreparedQueryParameterized parameterizedQuery, ContextPartitionSelector[] contextPartitionSelectors) Execute an on-demand parameterized query.
EPOnDemandQueryResult	executeQuery(EPStatementObjectModel model) Execute an on-demand query.
EPOnDemandQueryResult	executeQuery(EPStatementObjectModel model, ContextPartitionSelector[] contextPartitionSelectors) For use with named windows that have a context declared and that may therefore have multiple context partitions, allows to target context partitions for query execution selectively.
EPOnDemandQueryResult	executeQuery(java.lang.String epl) Execute an on-demand query.
EPOnDemandQueryResult	executeQuery(java.lang.String epl, ContextPartitionSelector[] contextPartitionSelectors) For use with named windows that have a context declared and that may therefore have multiple context partitions, allows to target context partitions for query execution selectively.
long	getCurrentTime() Returns current engine time.
EPDataFlowRuntime	getDataFlowRuntime() Returns the data flow runtime.
EventRenderer	getEventRenderer() Returns the event renderer for events generated by this runtime.
EventSender	getEventSender(java.lang.String eventTypeName) Returns a facility to process event objects that are of a known type.
EventSender	getEventSender(java.net.URI[] uris) For use with plug-in event representations, returns a facility to process event objects that are of one of a number of types that one or more of the registered plug-in event representation extensions can reflect upon and provide an event for.
java.lang.Long	getNextScheduledTime() Returns the time at which the next schedule execution is expected, returns null if no schedule execution is outstanding.
long	getNumEventsEvaluated() Number of events evaluated over the lifetime of the event stream processing runtime, or since the last resetStats() call.
java.util.Map<java.lang.String,java.lang.Object>	getVariableValue(java.util.Set<java.lang.String> variableNames) Returns current variable values for each of the global variable names passed in, guaranteeing consistency in the face of concurrent updates to the variables.
java.util.Map<java.lang.String,java.util.List<ContextPartitionVariableState>>	getVariableValue(java.util.Set<java.lang.String> variableNames, ContextPartitionSelector contextPartitionSelector) Returns the current variable values for a context-partitioned variable, per context partition.
java.lang.Object	getVariableValue(java.lang.String variableName) Returns the current variable value for a global variable.
java.util.Map<java.lang.String,java.lang.Object>	getVariableValueAll() Returns current variable values for all global variables, guaranteeing consistency in the face of concurrent updates to the variables.
boolean	isExternalClockingEnabled() Returns true for external clocking, false for internal clocking.
EPOnDemandPreparedQuery	prepareQuery(EPStatementObjectModel model) Prepare an unparameterized on-demand query before execution and for repeated execution.
EPOnDemandPreparedQuery	prepareQuery(java.lang.String epl) Prepare an unparameterized on-demand query before execution and for repeated execution.
EPOnDemandPreparedQueryParameterized	prepareQueryWithParameters(java.lang.String epl) Prepare a parameterized on-demand query for repeated parameter setting and execution.
void	resetStats() Reset number of events received and emitted
void	route(java.util.Map map, java.lang.String eventTypeName) Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent.
void	route(org.w3c.dom.Node node) Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent.
void	route(java.lang.Object theEvent) Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent.
void	route(java.lang.Object[] objectArray, java.lang.String eventTypeName) Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent.
void	sendEvent(java.util.Map map, java.lang.String mapEventTypeName) Send a map containing event property values to the event stream processing runtime.
void	sendEvent(org.w3c.dom.Node node) Send an event represented by a DOM node to the event stream processing runtime.
void	sendEvent(java.lang.Object object) Send an event represented by a plain Java object to the event stream processing runtime.
void	sendEvent(java.lang.Object[] objectarray, java.lang.String objectArrayEventTypeName) Send an object array containing event property values to the event stream processing runtime.
void	setUnmatchedListener(UnmatchedListener listener) Sets a listener to receive events that are unmatched by any statement.
void	setVariableValue(java.util.Map<java.lang.String,java.lang.Object> variableValues) Sets the value of multiple global variables in one update, applying all or none of the changes to variable values in one atomic transaction.
void	setVariableValue(java.util.Map<java.lang.String,java.lang.Object> variableValues, int agentInstanceId) Sets the value of multiple context-partitioned variables in one update, applying all or none of the changes to variable values in one atomic transaction.
void	setVariableValue(java.lang.String variableName, java.lang.Object variableValue) Sets the value of a single global variable.

Method Detail

sendEvent

void sendEvent(java.lang.Object object)
               throws EPException

Send an event represented by a plain Java object to the event stream processing runtime.

Use the route method for sending events into the runtime from within UpdateListener code, to avoid the possibility of a stack overflow due to nested calls to sendEvent (except with the outbound-threading configuration), see route(Object)).

Parameters:

object - is the event to sent to the runtime

Throws:

EPException - is thrown when the processing of the event lead to an error

sendEvent

void sendEvent(java.util.Map map,
               java.lang.String mapEventTypeName)
               throws EPException

Send a map containing event property values to the event stream processing runtime.

Use the route method for sending events into the runtime from within UpdateListener code. to avoid the possibility of a stack overflow due to nested calls to sendEvent (except with the outbound-threading configuration), see route(java.util.Map, String)).

Parameters:

map - - map that contains event property values. Keys are expected to be of type String while values can be of any type. Keys and values should match those declared via Configuration for the given eventTypeName.

mapEventTypeName - - the name for the Map event type that was previously configured

Throws:

EPException - - when the processing of the event leads to an error

sendEvent

void sendEvent(java.lang.Object[] objectarray,
               java.lang.String objectArrayEventTypeName)

Send an object array containing event property values to the event stream processing runtime.

Use the route method for sending events into the runtime from within UpdateListener code. to avoid the possibility of a stack overflow due to nested calls to sendEvent (except with the outbound-threading configuration), see route(Object[], String)).

Parameters:

objectarray - - array that contains event property values. Your application must ensure that property values match the exact same order that the property names and types have been declared, and that the array length matches the number of properties declared.

objectArrayEventTypeName - - the name for the Object-array event type that was previously configured

Throws:

EPException - - when the processing of the event leads to an error

sendEvent

void sendEvent(org.w3c.dom.Node node)
               throws EPException

Send an event represented by a DOM node to the event stream processing runtime.

Use the route method for sending events into the runtime from within UpdateListener code. to avoid the possibility of a stack overflow due to nested calls to sendEvent (except with the outbound-threading configuration), see route(org.w3c.dom.Node)).

Parameters:

node - is the DOM node as an event

Throws:

EPException - is thrown when the processing of the event lead to an error

getNumEventsEvaluated

long getNumEventsEvaluated()

Number of events evaluated over the lifetime of the event stream processing runtime, or since the last resetStats() call.

Returns:

number of events received

resetStats

void resetStats()

Reset number of events received and emitted

route

void route(java.lang.Object theEvent)

Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent. The route event is processed just like it was sent to the runtime, that is any active expressions seeking that event receive it. The routed event has priority over other events sent to the runtime. In a single-threaded application the routed event is processed before the next event is sent to the runtime through the EPRuntime.sendEvent method.

Note: when outbound-threading is enabled, the thread delivering to listeners is not the thread processing the original event. Therefore with outbound-threading enabled the sendEvent method should be used by listeners instead.

Parameters:

theEvent - to route internally for processing by the event stream processing runtime

route

void route(java.util.Map map,
           java.lang.String eventTypeName)
           throws EPException

Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent. The route event is processed just like it was sent to the runtime, that is any active expressions seeking that event receive it. The routed event has priority over other events sent to the runtime. In a single-threaded application the routed event is processed before the next event is sent to the runtime through the EPRuntime.sendEvent method.

Note: when outbound-threading is enabled, the thread delivering to listeners is not the thread processing the original event. Therefore with outbound-threading enabled the sendEvent method should be used by listeners instead.

Parameters:

map - - map that contains event property values. Keys are expected to be of type String while values can be of any type. Keys and values should match those declared via Configuration for the given eventTypeName.

eventTypeName - - the name for Map event type that was previously configured

Throws:

EPException - - when the processing of the event leads to an error

route

void route(java.lang.Object[] objectArray,
           java.lang.String eventTypeName)
           throws EPException

Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent. The route event is processed just like it was sent to the runtime, that is any active expressions seeking that event receive it. The routed event has priority over other events sent to the runtime. In a single-threaded application the routed event is processed before the next event is sent to the runtime through the EPRuntime.sendEvent method.

Note: when outbound-threading is enabled, the thread delivering to listeners is not the thread processing the original event. Therefore with outbound-threading enabled the sendEvent method should be used by listeners instead.

Parameters:

objectArray - - object array that contains event property values. Your application must ensure that property values match the exact same order that the property names and types have been declared, and that the array length matches the number of properties declared.

eventTypeName - - the name for Object-array event type that was previously configured

Throws:

EPException - - when the processing of the event leads to an error

route

void route(org.w3c.dom.Node node)
           throws EPException

Route the event object back to the event stream processing runtime for internal dispatching, to avoid the possibility of a stack overflow due to nested calls to sendEvent. The route event is processed just like it was sent to the runtime, that is any active expressions seeking that event receive it. The routed event has priority over other events sent to the runtime. In a single-threaded application the routed event is processed before the next event is sent to the runtime through the EPRuntime.sendEvent method.

Note: when outbound-threading is enabled, the thread delivering to listeners is not the thread processing the original event. Therefore with outbound-threading enabled the sendEvent method should be used by listeners instead.

Parameters:

node - is the DOM node as an event

Throws:

EPException - is thrown when the processing of the event lead to an error

setUnmatchedListener

void setUnmatchedListener(UnmatchedListener listener)

Sets a listener to receive events that are unmatched by any statement.

Events that can be unmatched are all events that are send into a runtime via one of the sendEvent methods, or that have been generated via insert-into clause.

For an event to be unmatched by any statement, the event must not match any statement's event stream filter criteria (a where-clause is NOT a filter criteria for a stream, as below).

Note: In the following statement a MyEvent event does always match this statement's event stream filter criteria, regardless of the value of the 'quantity' property.

select * from MyEvent where quantity > 5

In the following statement only a MyEvent event with a 'quantity' property value of 5 or less does not match this statement's event stream filter criteria:

select * from MyEvent(quantity > 5)

For patterns, if no pattern sub-expression is active for such event, the event is also unmatched.

Parameters:

listener - is the listener to receive notification of unmatched events, or null to unregister a previously registered listener

getVariableValue

java.lang.Object getVariableValue(java.lang.String variableName)
                                  throws VariableNotFoundException

Returns the current variable value for a global variable. A null value is a valid value for a variable. Not for use with context-partitioned variables.

Parameters:

variableName - is the name of the variable to return the value for

Returns:

current variable value

Throws:

VariableNotFoundException - if a variable by that name has not been declared

getVariableValue

java.util.Map<java.lang.String,java.util.List<ContextPartitionVariableState>> getVariableValue(java.util.Set<java.lang.String> variableNames,
                                                                                               ContextPartitionSelector contextPartitionSelector)
                                                                                               throws VariableNotFoundException

Returns the current variable values for a context-partitioned variable, per context partition. A null value is a valid value for a variable. Only for use with context-partitioned variables. Variable names provided must all be associated to the same context partition.

Parameters:

variableNames - are the names of the variables to return the value for

contextPartitionSelector - selector for the context partition to return the value for

Returns:

current variable value

Throws:

VariableNotFoundException - if a variable by that name has not been declared

getVariableValue

java.util.Map<java.lang.String,java.lang.Object> getVariableValue(java.util.Set<java.lang.String> variableNames)
                                                                  throws VariableNotFoundException

Returns current variable values for each of the global variable names passed in, guaranteeing consistency in the face of concurrent updates to the variables. Not for use with context-partitioned variables.

Parameters:

variableNames - is a set of variable names for which to return values

Returns:

map of variable name and variable value

Throws:

VariableNotFoundException - if any of the variable names has not been declared

getVariableValueAll

java.util.Map<java.lang.String,java.lang.Object> getVariableValueAll()

Returns current variable values for all global variables, guaranteeing consistency in the face of concurrent updates to the variables. Not for use with context-partitioned variables.

Returns:

map of variable name and variable value

setVariableValue

void setVariableValue(java.lang.String variableName,
                      java.lang.Object variableValue)
                      throws VariableValueException,
                             VariableNotFoundException

Sets the value of a single global variable.

Note that the thread setting the variable value queues the changes, i.e. it does not itself re-evaluate such new variable value for any given statement. The timer thread performs this work.

Not for use with context-partitioned variables.

Parameters:

variableName - is the name of the variable to change the value of

variableValue - is the new value of the variable, with null an allowed value

Throws:

VariableValueException - if the value does not match variable type or cannot be safely coerced to the variable type

VariableNotFoundException - if the variable name has not been declared

setVariableValue

void setVariableValue(java.util.Map<java.lang.String,java.lang.Object> variableValues)
                      throws VariableValueException,
                             VariableNotFoundException

Sets the value of multiple global variables in one update, applying all or none of the changes to variable values in one atomic transaction.

Note that the thread setting the variable value queues the changes, i.e. it does not itself re-evaluate such new variable value for any given statement. The timer thread performs this work.

Not for use with context-partitioned variables.

Parameters:

variableValues - is the map of variable name and variable value, with null an allowed value

Throws:

VariableValueException - if any value does not match variable type or cannot be safely coerced to the variable type

VariableNotFoundException - if any of the variable names has not been declared

setVariableValue

void setVariableValue(java.util.Map<java.lang.String,java.lang.Object> variableValues,
                      int agentInstanceId)
                      throws VariableValueException,
                             VariableNotFoundException

Sets the value of multiple context-partitioned variables in one update, applying all or none of the changes to variable values in one atomic transaction.

Note that the thread setting the variable value queues the changes, i.e. it does not itself re-evaluate such new variable value for any given statement. The timer thread performs this work.

Only for use with context-partitioned variables.

Parameters:

variableValues - is the map of variable name and variable value, with null an allowed value

agentInstanceId - the id of the context partition

Throws:

VariableValueException - if any value does not match variable type or cannot be safely coerced to the variable type

VariableNotFoundException - if any of the variable names has not been declared

getEventSender

EventSender getEventSender(java.lang.String eventTypeName)
                           throws EventTypeException

Returns a facility to process event objects that are of a known type.

Given an event type name this method returns a sender that allows to send in event objects of that type. The event objects send in via the event sender are expected to match the event type, thus the event sender does not inspect the event object other then perform basic checking.

For events backed by a Java class (JavaBean events), the sender ensures that the object send in matches in class, or implements or extends the class underlying the event type for the given event type name. Note that event type identity for Java class events is the Java class. When assigning two different event type names to the same Java class the names are an alias for the same event type i.e. there is always a single event type to represent a given Java class.

For events backed by a Object[] (Object-array events), the sender does not perform any checking other then checking that the event object indeed is an array of object.

For events backed by a java.util.Map (Map events), the sender does not perform any checking other then checking that the event object indeed implements Map.

For events backed by a org.w3c.Node (XML DOM events), the sender checks that the root element name indeed does match the root element name for the event type name.

Parameters:

eventTypeName - is the name of the event type

Returns:

sender for fast-access processing of event objects of known type (and content)

Throws:

EventTypeException - thrown to indicate that the name does not exist

getEventSender

EventSender getEventSender(java.net.URI[] uris)
                           throws EventTypeException

For use with plug-in event representations, returns a facility to process event objects that are of one of a number of types that one or more of the registered plug-in event representation extensions can reflect upon and provide an event for.

Parameters:

uris - is the URIs that specify which plug-in event representations may process an event object.

URIs do not need to match event representation URIs exactly, a child (hierarchical) match is enough for an event representation to participate.

The order of URIs is relevant as each event representation's factory is asked in turn to process the event, until the first factory processes the event.

Returns:

sender for processing of event objects of one of the plug-in event representations

Throws:

EventTypeException - thrown to indicate that the URI list was invalid

executeQuery

EPOnDemandQueryResult executeQuery(java.lang.String epl)

Execute an on-demand query.

On-demand queries are EPL queries that execute non-continuous fire-and-forget queries against named windows.

Parameters:

epl - is the EPL query to execute

Returns:

query result

executeQuery

EPOnDemandQueryResult executeQuery(java.lang.String epl,
                                   ContextPartitionSelector[] contextPartitionSelectors)

For use with named windows that have a context declared and that may therefore have multiple context partitions, allows to target context partitions for query execution selectively.

Parameters:

epl - is the EPL query to execute

contextPartitionSelectors - selects context partitions to consider

Returns:

result

executeQuery

EPOnDemandQueryResult executeQuery(EPStatementObjectModel model)

Execute an on-demand query.

On-demand queries are EPL queries that execute non-continuous fire-and-forget queries against named windows.

Parameters:

model - is the EPL query to execute, obtain a model object using EPAdministrator.compileEPL(String) or via the API

Returns:

query result

executeQuery

EPOnDemandQueryResult executeQuery(EPStatementObjectModel model,
                                   ContextPartitionSelector[] contextPartitionSelectors)

For use with named windows that have a context declared and that may therefore have multiple context partitions, allows to target context partitions for query execution selectively.

Parameters:

model - is the EPL query to execute, obtain a model object using EPAdministrator.compileEPL(String) or via the API

contextPartitionSelectors - selects context partitions to consider

Returns:

result

prepareQuery

EPOnDemandPreparedQuery prepareQuery(java.lang.String epl)

Prepare an unparameterized on-demand query before execution and for repeated execution.

Parameters:

epl - to prepare

Returns:

proxy to execute upon, that also provides the event type of the returned results

prepareQuery

EPOnDemandPreparedQuery prepareQuery(EPStatementObjectModel model)

Prepare an unparameterized on-demand query before execution and for repeated execution.

Parameters:

model - is the EPL query to prepare, obtain a model object using EPAdministrator.compileEPL(String) or via the API

Returns:

proxy to execute upon, that also provides the event type of the returned results

prepareQueryWithParameters

EPOnDemandPreparedQueryParameterized prepareQueryWithParameters(java.lang.String epl)

Prepare a parameterized on-demand query for repeated parameter setting and execution. Set all values on the returned holder then execute using executeQuery(EPOnDemandPreparedQueryParameterized).

Parameters:

epl - to prepare

Returns:

parameter holder upon which to set values

executeQuery

EPOnDemandQueryResult executeQuery(EPOnDemandPreparedQueryParameterized parameterizedQuery)

Execute an on-demand parameterized query.

On-demand queries are EPL queries that execute non-continuous fire-and-forget queries against named windows.

Parameters:

parameterizedQuery - contains the query and parameter values

Returns:

query result

executeQuery

EPOnDemandQueryResult executeQuery(EPOnDemandPreparedQueryParameterized parameterizedQuery,
                                   ContextPartitionSelector[] contextPartitionSelectors)

Execute an on-demand parameterized query.

On-demand queries are EPL queries that execute non-continuous fire-and-forget queries against named windows.

Parameters:

parameterizedQuery - contains the query and parameter values

contextPartitionSelectors - selects context partitions to consider

Returns:

query result

getEventRenderer

EventRenderer getEventRenderer()

Returns the event renderer for events generated by this runtime.

Returns:

event renderer

getCurrentTime

long getCurrentTime()

Returns current engine time.

If time is provided externally via timer events, the function returns current time as externally provided.

Returns:

current engine time

getNextScheduledTime

java.lang.Long getNextScheduledTime()

Returns the time at which the next schedule execution is expected, returns null if no schedule execution is outstanding.

Returns:

time of next schedule if any

getDataFlowRuntime

EPDataFlowRuntime getDataFlowRuntime()

Returns the data flow runtime.

Returns:

data flow runtime

isExternalClockingEnabled

boolean isExternalClockingEnabled()

Returns true for external clocking, false for internal clocking.

Returns:

clocking indicator