EPRuntime (Esper API Documentation)

All Known Subinterfaces:

EPRuntimeSPI

All Known Implementing Classes:

EPRuntimeImpl
```
public interface EPRuntime
```
Interface to event stream processing runtime services.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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(String epl)` Execute an on-demand query.
`EPOnDemandQueryResult`	`executeQuery(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(String eventTypeName)` Returns a facility to process event objects that are of a known type.
`EventSender`	`getEventSender(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.
`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.
`Map<String,Object>`	`getVariableValue(Set<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.
`Map<String,List<ContextPartitionVariableState>>`	`getVariableValue(Set<String> variableNames, ContextPartitionSelector contextPartitionSelector)` Returns the current variable values for a context-partitioned variable, per context partition.
`Object`	`getVariableValue(String variableName)` Returns the current variable value for a global variable.
`Map<String,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(String epl)` Prepare an unparameterized on-demand query before execution and for repeated execution.
`EPOnDemandPreparedQueryParameterized`	`prepareQueryWithParameters(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(Map map, 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(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(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(Object[] objectArray, 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`	`routeAvro(Object avroGenericDataDotRecord, String avroEventTypeName)` 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(Map map, String mapEventTypeName)` Send a map containing event property values to the event stream processing runtime.
`void`	`sendEvent(Node node)` Send an event represented by a DOM node to the event stream processing runtime.
`void`	`sendEvent(Object object)` Send an event represented by a plain Java object to the event stream processing runtime.
`void`	`sendEvent(Object[] objectarray, String objectArrayEventTypeName)` Send an object array containing event property values to the event stream processing runtime.
`void`	`sendEventAvro(Object avroGenericDataDotRecord, String avroEventTypeName)` Send an event represented by a Avro GenericData.Record to the event stream processing runtime.
`void`	`setUnmatchedListener(UnmatchedListener listener)` Sets a listener to receive events that are unmatched by any statement.
`void`	`setVariableValue(Map<String,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(Map<String,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(String variableName, Object variableValue)` Sets the value of a single global variable.

- Method Detail
  - sendEvent
```
void sendEvent(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(Map map,
               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(Object[] objectarray,
               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(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(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(Map map,
           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(Object[] objectArray,
           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(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
```
Object getVariableValue(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
```
Map<String,List<ContextPartitionVariableState>> getVariableValue(Set<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
```
Map<String,Object> getVariableValue(Set<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
```
Map<String,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(String variableName,
                      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(Map<String,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(Map<String,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(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(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(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(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(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(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
```
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
  - sendEventAvro
```
void sendEventAvro(Object avroGenericDataDotRecord,
                   String avroEventTypeName)
```
    Send an event represented by a Avro GenericData.Record 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 routeAvro(Object, String)}).
    
    Parameters:
    
    avroGenericDataDotRecord - is the event to sent to the runtime
    
    avroEventTypeName - event type name
    
    Throws:
    
    EPException - is thrown when the processing of the event lead to an error
  - routeAvro
```
void routeAvro(Object avroGenericDataDotRecord,
               String avroEventTypeName)
        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:
    
    avroGenericDataDotRecord - is the event to sent to the runtime
    
    avroEventTypeName - event type name
    
    Throws:
    
    EPException - is thrown when the processing of the event lead to an error

Interface EPRuntime

Method Summary

Method Detail

sendEvent

sendEvent

sendEvent

sendEvent

getNumEventsEvaluated

resetStats

route

route

route

route

setUnmatchedListener

getVariableValue

getVariableValue

getVariableValue

getVariableValueAll

setVariableValue

setVariableValue

setVariableValue

getEventSender

getEventSender

executeQuery

executeQuery

executeQuery

executeQuery

prepareQuery

prepareQuery

prepareQueryWithParameters

executeQuery

executeQuery

getEventRenderer

getCurrentTime

getNextScheduledTime

getDataFlowRuntime

isExternalClockingEnabled

sendEventAvro

routeAvro