com.apama.services.event
Interface IEventServiceChannel

public interface IEventServiceChannel

IEventServiceChannel is the public interface for a class that represents a channel or channels on which events are received from a Correlator.

IEventServiceChannel is an interface that forms part of the service style high-level public interface to the Correlator with a focus on only dealing with Events and consumer channels.

To create an IEventServiceChannel, use the IEventService.addChannel(String, Map) method. If the channel is no longer required, it can be removed using IEventService.removeChannel(String)

See Also:

IEventService

Field Summary

static java.lang.String	CONFIG_DEFAULT_REQUEST_RESPONSE_TIMEOUT Configuration property name for specifying the default request-response timeout that a new EventServiceChannel should use.
static java.lang.String	CONFIG_ENFORCE_RESPONSE_SEQUENCING Configuration property name for specifying if a new EventServiceChannel should use strict response sequencing for synchronous request-response invocations.
static java.lang.String	CONFIG_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES Configuration property name for specifying for which event names a new EventServiceChannel should use SoftReferences in the inbound queue.
static java.lang.String	CONFIG_MESSAGEID_FIELD_NAME Configuration property name for specifying the field name of message ID's (for request-response) that a new EventServiceChannel should use.
static boolean	DEFAULT_ENFORCE_RESPONSE_SEQUENCING Default value for the flag specifying if strict response sequencing should be used (true).
static java.util.Set<java.lang.String>	DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES Default value for the set of event name prefixes that would cause a received event to be placed in the inbound event queue as a SoftReference (null).
static java.lang.String	DEFAULT_MESSAGEID_FIELD_NAME Default value for the field name of message ID's for request-response ("messageId").
static long	DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS Default value for the request-reponse timeout (3000ms).
static java.lang.String	PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT System property (in millisecond) to set the default RequestResponseTimeout.
static java.lang.String	PROP_OVERRIDE_REQUEST_RESPONSE_TIMEOUT System property (in millisecond) to override RequestResponseTimeout.

Method Summary

void	addEventListener(IEventListener eventListener) Add an IEventListener that will be notified of every event (of a pre-registered type) that is received by this EventServiceChannel instance.
void	addEventListener(IEventListener eventListener, EventType eventType) Add an IEventListener that will be notified of every event, of the specified EventType, that is received by this EventServiceChannel instance.
void	asyncRequestResponse(IResponseListener responseListener, Event requestEvent, EventType responseEventType) Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call).
void	asyncRequestResponse(IResponseListener responseListener, Event requestEvent, EventType responseEventType, long timeout) Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call, with timeout).
void	clearProcessingQueue() Immediately remove (discard) all events from the internal processing queue.
java.util.Map<java.lang.String,java.lang.Object>	getConfig() Get the channel configuration that define the requested operating semantics of this instance.
java.lang.String	getName() Get the name of the channel(s) that this instance is consuming events from.
boolean	isDestroyed() Determine if this EventServiceChannel channel (not the Correlator) is destroyed, which is true if it has been removed from the parent EventService using IEventService.removeChannel(String).
void	registerEventType(EventType eventType) Register an arbitrary EventType with this EventServiceChannel.
void	removeEventListener(IEventListener eventListener) Remove a previously registered IEventListener that was listening to all events received.
void	removeEventListener(IEventListener eventListener, EventType eventType) Remove a previously registered IEventListener that was listening to all events received of the specified EventType.
IResponseWrapper	requestResponse(Event requestEvent, EventType responseEventType) Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call).
IResponseWrapper	requestResponse(Event requestEvent, EventType responseEventType, long timeout) Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call with timeout).
void	setLateResponseListener(IEventListener eventListener) Register the single IEventListener that will be notified of any "late" responses to either synchronous or asynchronous request-response calls.
void	unregisterEventType(EventType eventType) Unregister an arbitrary EventType from this EventServiceChannel.

Field Detail

DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES

static final java.util.Set<java.lang.String> DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES

Default value for the set of event name prefixes that would cause a received event to be placed in the inbound event queue as a SoftReference (null).

DEFAULT_ENFORCE_RESPONSE_SEQUENCING

static final boolean DEFAULT_ENFORCE_RESPONSE_SEQUENCING

Default value for the flag specifying if strict response sequencing should be used (true).

See Also:

Constant Field Values

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

static final long DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

Default value for the request-reponse timeout (3000ms).

See Also:

Constant Field Values

DEFAULT_MESSAGEID_FIELD_NAME

static final java.lang.String DEFAULT_MESSAGEID_FIELD_NAME

Default value for the field name of message ID's for request-response ("messageId").

See Also:

Constant Field Values

CONFIG_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES

static final java.lang.String CONFIG_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES

Configuration property name for specifying for which event names a new EventServiceChannel should use SoftReferences in the inbound queue.

See Also:

DEFAULT_INBOUND_EVENT_QUEUE_SOFT_REFERENCE_PREFIXES, Constant Field Values

CONFIG_ENFORCE_RESPONSE_SEQUENCING

static final java.lang.String CONFIG_ENFORCE_RESPONSE_SEQUENCING

Configuration property name for specifying if a new EventServiceChannel should use strict response sequencing for synchronous request-response invocations.

See Also:

DEFAULT_ENFORCE_RESPONSE_SEQUENCING, Constant Field Values

CONFIG_DEFAULT_REQUEST_RESPONSE_TIMEOUT

static final java.lang.String CONFIG_DEFAULT_REQUEST_RESPONSE_TIMEOUT

Configuration property name for specifying the default request-response timeout that a new EventServiceChannel should use.

See Also:

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT, Constant Field Values

PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT

static final java.lang.String PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT

System property (in millisecond) to set the default RequestResponseTimeout. If this property is defined, then its value will be used instead of the hard-coded DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

See Also:

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, PROP_OVERRIDE_REQUEST_RESPONSE_TIMEOUT

PROP_OVERRIDE_REQUEST_RESPONSE_TIMEOUT

static final java.lang.String PROP_OVERRIDE_REQUEST_RESPONSE_TIMEOUT

System property (in millisecond) to override RequestResponseTimeout. If this property is defined, then its value will be used at runtime. This value will supersede the CONFIG_DEFAULT_REQUEST_RESPONSE_TIMEOUT and PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT property setting.

See Also:

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, CONFIG_DEFAULT_REQUEST_RESPONSE_TIMEOUT, PROP_DEFAULT_REQUEST_RESPONSE_TIMEOUT

CONFIG_MESSAGEID_FIELD_NAME

static final java.lang.String CONFIG_MESSAGEID_FIELD_NAME

Configuration property name for specifying the field name of message ID's (for request-response) that a new EventServiceChannel should use.

See Also:

DEFAULT_MESSAGEID_FIELD_NAME, Constant Field Values

Method Detail

getName

java.lang.String getName()

Get the name of the channel(s) that this instance is consuming events from.

This is an read-only property.

Returns:

A single string containing the channel name, or a single string containin a comma separated list of channel names.

getConfig

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

Get the channel configuration that define the requested operating semantics of this instance.

This is an read-only property.

Returns:

an unmodifiable view of the channelConfig Map that was specified at construction.

clearProcessingQueue

void clearProcessingQueue()

Immediately remove (discard) all events from the internal processing queue.

requestResponse

IResponseWrapper requestResponse(Event requestEvent,
                                 EventType responseEventType)
                                 throws ResponseTimeoutException,
                                        EngineException,
                                        EventServiceException

Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call).

Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Note: this is a blocking call, with the default timeout for this channel. See also IEventService.addChannel(String, Map), DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, and ChannelConfig

Parameters:

requestEvent - the request Event to be sent to the Correlator.

responseEventType - the expected EventType of the response Event from the Correlator.

Returns:

the response Event from the Correlator, inside the wrapper that is used for locking when response sequencing is enforced.

Throws:

ResponseTimeoutException - if the default timeout is exceeded without receiving the response.

EngineException - if there was a problem sending the request.

EventServiceException - if the event type of either the request of the repsonse did not contain a messageId field.

See Also:

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

requestResponse

IResponseWrapper requestResponse(Event requestEvent,
                                 EventType responseEventType,
                                 long timeout)
                                 throws ResponseTimeoutException,
                                        EngineException,
                                        EventServiceException

Emulate a synchronous RPC call to the Correlator by sending an event and awaiting a matching response event (blocking call with timeout).

Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Note: this is a blocking call, but with a timeout.

Parameters:

requestEvent - the request Event to be sent to the Correlator.

responseEventType - the expected EventType of the response Event from the Correlator.

timeout - the maximum time (in milliseconds) to wait for a response.

Returns:

the response Event from the Correlator, inside the wrapper that is used for locking when response sequencing is enforced.

Throws:

ResponseTimeoutException - if the timeout is exceeded without receiving the response.

EngineException - if there was a problem sending the request.

EventServiceException - if the event type of either the request of the repsonse did not contain a messageId field.

asyncRequestResponse

void asyncRequestResponse(IResponseListener responseListener,
                          Event requestEvent,
                          EventType responseEventType)
                          throws EngineException,
                                 EventServiceException

Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call).

Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

The responseListener will be notified of any exceptions thrown during the asynchronous call. The possible exceptions are:
ResponseTimeoutException if the timeout is exceeded without receiving the response.
EngineException if there was a problem sending the request.
EventServiceException if the event type of either the request of the repsonse did not contain a messageId field.

The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Note: this is a non-blocking call. The method will return as soon as the request is sent, and then at a later time when the response is received it will be passed to the supplied callback method. A ResponseTimeoutException would be given to the responseListener if the default timeout for this channel is exceeded. See also IEventService.addChannel(String, Map), DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS, and ChannelConfig
The request is sent on the client thread (whichever thread calls this method).
The client callback handleResponse() method will be called on a background thread.
The client callback handleException() method will be called on a background thread.

Parameters:

responseListener - the object implementing the callback interface.

requestEvent - the request Event to be sent to the Correlator.

responseEventType - the expected EventType of the response Event from the Correlator.

Throws:

EngineException - if there was a problem sending the request.

EventServiceException - if the event type of either the request of the repsonse did not contain a messageId field.

See Also:

DEFAULT_REQUEST_RESPONSE_TIMEOUT_MS

asyncRequestResponse

void asyncRequestResponse(IResponseListener responseListener,
                          Event requestEvent,
                          EventType responseEventType,
                          long timeout)
                          throws EngineException,
                                 EventServiceException

Emulate an asynchronous RPC call to the Correlator by sending an event, and then invoking a callback when a matching response event is received (non-blocking call, with timeout).

Both the request event, and the response event must contain an integer field called messageId. This service will allocate a value to that field in the request event, and will await a response event of the specified type that contains a messageId field of the same value.

The responseListener will be notified of any exceptions thrown during the asynchronous call. The possible exceptions are:
ResponseTimeoutException if the timeout is exceeded without receiving the response.
EngineException if there was a problem sending the request.
EventServiceException if the event type of either the request of the repsonse did not contain a messageId field.

The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Note: this is a non-blocking call. The method will return as soon as the request is sent, and then at a later time when the response is received it will be passed to the supplied callback method. If a response is not received within the specified timeout period, the callback will be "unregistered".
The request is sent on the client thread (whichever thread calls this method).
The client callback handleResponse() method will be called on a background thread.
The client callback handleException() method will be called on a background thread.

Parameters:

responseListener - the object implementing the callback interface.

requestEvent - the request Event to be sent to the Correlator.

responseEventType - the expected EventType of the response Event from the Correlator.

timeout - the maximum time (in milliseconds) to wait for a response.

Throws:

EngineException - if there was a problem sending the request.

EventServiceException - if the event type of either the request of the repsonse did not contain a messageId field.

setLateResponseListener

void setLateResponseListener(IEventListener eventListener)

Register the single IEventListener that will be notified of any "late" responses to either synchronous or asynchronous request-response calls.

This callback will be invoked if a call had been made to one of the timeout versions of the request-response methods, but the response was received after the timeout period had elapsed.

Parameters:

eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.

See Also:

EventListenerAdapter

addEventListener

void addEventListener(IEventListener eventListener)

Add an IEventListener that will be notified of every event (of a pre-registered type) that is received by this EventServiceChannel instance.

Note The listener will only be notified about events that are of a type registered with the parser. Clients must first use registerEventType(EventType) to register the event types in which they are interested. All other event types will be ignored (parse errors will be logged).

Parameters:

eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.

See Also:

EventListenerAdapter

addEventListener

void addEventListener(IEventListener eventListener,
                      EventType eventType)

Add an IEventListener that will be notified of every event, of the specified EventType, that is received by this EventServiceChannel instance.

The specified EventType will be automatically added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Parameters:

eventListener - the object implementing the callback interface - only the single-event handleEvent(Event) method will be called.

eventType - the single EventType filter.

See Also:

EventListenerAdapter

removeEventListener

void removeEventListener(IEventListener eventListener)

Remove a previously registered IEventListener that was listening to all events received.

Parameters:

eventListener - the object implementing the callback interface that is to be removed.

removeEventListener

void removeEventListener(IEventListener eventListener,
                         EventType eventType)

Remove a previously registered IEventListener that was listening to all events received of the specified EventType.

The specified EventType will NOT be removed from the types understood by the EventParser used by this EventServiceChannel.

Parameters:

eventListener - the object implementing the callback interface that is to be removed.

eventType - the single EventType filter.

registerEventType

void registerEventType(EventType eventType)

Register an arbitrary EventType with this EventServiceChannel.

This method can be used in conjunction with a listener that is listening to all (unfiltered) events received.

The specified EventType will be added to the types understood by the EventParser used by this EventServiceChannel. Any existing EventType definition will be overwritten.

Parameters:

eventType - a single EventType to be registered.

unregisterEventType

void unregisterEventType(EventType eventType)

Unregister an arbitrary EventType from this EventServiceChannel.

The specified EventType will be removed from the types understood by the EventParser used by this EventServiceChannel.

Parameters:

eventType - a single EventType to be unregistered.

isDestroyed

boolean isDestroyed()

Determine if this EventServiceChannel channel (not the Correlator) is destroyed, which is true if it has been removed from the parent EventService using IEventService.removeChannel(String).

Returns:

true if already destroyed, false otherwise.