com.espertech.esper.client
Interface EPStatement

All Superinterfaces:

EPIterable, EPListenable

All Known Subinterfaces:

EPStatementSPI

All Known Implementing Classes:

EPStatementImpl

public interface EPStatement
extends EPListenable, EPIterable

Statement interface that provides methods to start, stop and destroy a statement as well as get statement information such as statement name, expression text and current state.

Statements have 3 states: STARTED, STOPPED and DESTROYED.

In started state, statements are actively evaluating event streams according to the statement expression. Started statements can be stopped and destroyed.

In stopped state, statements are inactive. Stopped statements can either be started, in which case they begin to actively evaluate event streams, or destroyed.

Destroyed statements have relinguished all statement resources and cannot be started or stopped.

Method Summary

void	addListenerWithReplay(UpdateListener listener) Add an update listener replaying current statement results to the listener.
void	destroy() Destroy the statement releasing all statement resources.
java.lang.annotation.Annotation[]	getAnnotations() Returns EPL or pattern statement annotations provided in the statement text, if any.
java.lang.String	getName() Returns the statement name.
java.lang.String	getServiceIsolated() Returns the name of the isolated service provided is the statement is currently isolated in terms of event visibility and scheduling, or returns null if the statement is live in the engine.
EPStatementState	getState() Returns the statement's current state.
java.lang.Object	getSubscriber() Returns the current subscriber instance that receives statement results.
java.lang.String	getText() Returns the underlying expression text.
long	getTimeLastStateChange() Returns the system time in milliseconds of when the statement last change state.
java.lang.Object	getUserObject() Returns the application defined user data object associated with the statement, or null if none was supplied at time of statement creation.
boolean	isDestroyed() Returns true if the statement state is destroyed.
boolean	isPattern() Returns true if statement is a pattern
boolean	isStarted() Returns true if the statement state is started.
boolean	isStopped() Returns true if the statement state is stopped.
java.util.Iterator<EventBean>	iterator(ContextPartitionSelector selector) For use with statements that have a context declared and that may therefore have multiple context partitions, allows to iterate over context partitions selectively.
SafeIterator<EventBean>	safeIterator(ContextPartitionSelector selector) For use with statements that have a context declared and that may therefore have multiple context partitions, allows to safe-iterate over context partitions selectively.
void	setSubscriber(java.lang.Object subscriber) Attaches a subscriber to receive statement results, or removes a previously set subscriber (by providing a null value).
void	setSubscriber(java.lang.Object subscriber, java.lang.String methodName) Attaches a subscriber to receive statement results by calling the method with the provided method name, or removes a previously set subscriber (by providing a null value).
void	start() Start the statement.
void	stop() Stop the statement.

Methods inherited from interface com.espertech.esper.client.EPListenable

addListener, addListener, getStatementAwareListeners, getUpdateListeners, removeAllListeners, removeListener, removeListener

Methods inherited from interface com.espertech.esper.client.EPIterable

getEventType, iterator, safeIterator

Method Detail

start

void start()

Start the statement.

stop

void stop()

Stop the statement.

destroy

void destroy()

Destroy the statement releasing all statement resources.

A destroyed statement cannot be started again.

getState

EPStatementState getState()

Returns the statement's current state.

Returns:

state enum

isStarted

boolean isStarted()

Returns true if the statement state is started.

Returns:

true for started statements, false for stopped or destroyed statements.

isStopped

boolean isStopped()

Returns true if the statement state is stopped.

Returns:

true for stopped statements, false for started or destroyed statements.

isDestroyed

boolean isDestroyed()

Returns true if the statement state is destroyed.

Returns:

true for destroyed statements, false for started or stopped statements.

getText

java.lang.String getText()

Returns the underlying expression text.

Returns:

expression text

getName

java.lang.String getName()

Returns the statement name.

Returns:

statement name

getTimeLastStateChange

long getTimeLastStateChange()

Returns the system time in milliseconds of when the statement last change state.

Returns:

time in milliseconds of last statement state change

setSubscriber

void setSubscriber(java.lang.Object subscriber)
                   throws EPSubscriberException

Attaches a subscriber to receive statement results, or removes a previously set subscriber (by providing a null value).

Only a single subscriber may be set for a statement. If this method is invoked twice any previously-set subscriber is no longer used.

Parameters:

subscriber - to attach, or null to remove the previously set subscriber

Throws:

EPSubscriberException - if the subscriber does not provide the methods needed to receive statement results

setSubscriber

void setSubscriber(java.lang.Object subscriber,
                   java.lang.String methodName)
                   throws EPSubscriberException

Attaches a subscriber to receive statement results by calling the method with the provided method name, or removes a previously set subscriber (by providing a null value).

Only a single subscriber may be set for a statement. If this method is invoked twice any previously-set subscriber is no longer used.

Parameters:

subscriber - to attach, or null to remove the previously set subscriber

methodName - the name of the method to invoke, or null for the "update" method

Throws:

EPSubscriberException - if the subscriber does not provide the methods needed to receive statement results

getSubscriber

java.lang.Object getSubscriber()

Returns the current subscriber instance that receives statement results.

Returns:

subscriber object, or null to indicate that no subscriber is attached

Throws:

EPSubscriberException - if the subscriber does not provide the methods needed to receive statement results

isPattern

boolean isPattern()

Returns true if statement is a pattern

Returns:

true if statement is a pattern

getUserObject

java.lang.Object getUserObject()

Returns the application defined user data object associated with the statement, or null if none was supplied at time of statement creation.

The user object is a single, unnamed field that is stored with every statement. Applications may put arbitrary objects in this field or a null value.

User objects are passed at time of statement creation as a parameter the create method.

Returns:

user object or null if none defined

addListenerWithReplay

void addListenerWithReplay(UpdateListener listener)

Add an update listener replaying current statement results to the listener.

The listener receives current statement results as the first call to the update method of the listener, passing in the newEvents parameter the current statement results as an array of zero or more events. Subsequent calls to the update method of the listener are statement results.

Current statement results are the events returned by the iterator or safeIterator methods.

Delivery of current statement results in the first call is performed by the same thread invoking this method, while subsequent calls to the listener may deliver statement results by the same or other threads.

Note: this is a blocking call, delivery is atomic: Events occurring during iteration and delivery to the listener are guaranteed to be delivered in a separate call and not lost. The listener implementation should minimize long-running or blocking operations.

Delivery is only atomic relative to the current statement. If the same listener instance is registered with other statements it may receive other statement result s simultaneously.

If a statement is not started an therefore does not have current results, the listener receives a single invocation with a null value in newEvents.

Parameters:

listener - to add

getAnnotations

java.lang.annotation.Annotation[] getAnnotations()

Returns EPL or pattern statement annotations provided in the statement text, if any.

See the annotation com.espertech.esper.client.annotation package for available annotations.

Returns:

annotations or a zero-length array if no annotaions have been specified.

getServiceIsolated

java.lang.String getServiceIsolated()

Returns the name of the isolated service provided is the statement is currently isolated in terms of event visibility and scheduling, or returns null if the statement is live in the engine.

Returns:

isolated service name or null for statements that are not currently isolated

iterator

java.util.Iterator<EventBean> iterator(ContextPartitionSelector selector)

For use with statements that have a context declared and that may therefore have multiple context partitions, allows to iterate over context partitions selectively.

Parameters:

selector - selects context partitions to consider

Returns:

iterator

safeIterator

SafeIterator<EventBean> safeIterator(ContextPartitionSelector selector)

For use with statements that have a context declared and that may therefore have multiple context partitions, allows to safe-iterate over context partitions selectively.

Parameters:

selector - selects context partitions to consider

Returns:

safe iterator