public class EventDispatcher
extends java.lang.Object
Title: Framework Support Library
Description: Defines an Event Dispatcher
for arbitrary intra-JVM events.
Event Dispatcher
performs the function of an event multi-caster within the scope of a given JVM.
The mechanism allows classes that implement the descendants of EventListener
interface to register with the
dispatcher to receive events based on a given EventId
, filter pattern
(see Filter
for detailed information about filters) or Event Selector
.
EventListener
- a synchronous event listener called via direct dispatchEventAsyncConsumer
- an asynchronous event listener called via it's internal event queueRequestListener
- a request processor called via targeted request by nameEventDatagram
with a matching EventId
pattern is passed to the dispatcher via the
raiseEvent(com.streamscape.sdo.ImmutableEventDatagram)
method, the appropriate listener(s) will be notified and their EventListener.onEvent(com.streamscape.sdo.ImmutableEventDatagram)
method will be called. Each listener is passed a reference to the EventDatagram
object. The data element of the
object is final
and may not be modified. However, an event may be canceled or its
status otherwise modified. Event listeners may simply implement the supplied interface or may be
started as threads. Listener threads are managed and controlled by the dispatcher mechanism.
Creating an Event Dispatcher
All access to the event dispatcher is thru the main EventDispatcher
object. The example below
illustrates how to create an instance of a dispatcher.
EventDispatcher dispatcher = new EventDispatcher();
dispatcher.start();
Raising Events
Posting an event to the dispatcher is accomplished by creating an Event
object that implements the
ImmutableEventDatagram
and passing it to the raiseEvent(com.streamscape.sdo.ImmutableEventDatagram)
method.
Event event = new Event("event.example");
dispatcher.raiseEvent(event)
Registering Event Handlers
Event listeners are registered by creating an object that implements the EventListener
interface.
Each listener is wrapped in the EventConsumer
instance (consumer contains working information related with its listener).
Below is an example of a simple event listener.
class MyListener implements EventListener { public void onEvent(ImmutableEventDatagram event) throws EventDispatcherException { System.out.println("Received event: '" + event.getEventId() + "'."); } } ... // Registers a listener. dispatcher.createConsumer("MyConsumer", "event.example", null, new MyListener());
Event Selectors are a way of selectively filtering events by criteria stored in the header fields
and user-defined properties of an Event Datagram
. Selectors are considered part of the
Event Fabric's
EPL (Event Processing Language) and are at the heart of the Reactive Programming
paradigm. Event selectors are used in consumer components, event triggers, STREAM collections and
Service Event Handlers to conditionally process events based on their content. Only events whose header and
property values match the selector are delivered to the event consumer.
The application fabric optimizes selector performance by pushing match logic execution into the dispatcher of the event producer. This technique ensures that only events in which consumers have registered an interest are actually raised. Dispatcher based filtering is extremely efficient, capable of processing hundreds of thousands of events per second without significant impact on throughput or latency of the system.
The selector is an extension of the Message Selector capability as outlined in the Java Messaging Service (JMS) specification. Similar to JMS an event selector is a String whose syntax is based on a subset of the SQL-92 conditional expression syntax with several notable differences.
Example Selection Clause:
( PaymentIndicator IS NOT NULL ) AND ( TransferDate > datetime( '17.03.10 01:36' ) ) AND PaymentFileName MATCHES '.\*\.xml'
( BranchIdentifier BETWEEN 0 AND CaymanId_MAX ) AND ( AccountName LIKE 'T_x%' ) AND StartDate IN ( Domain.Valid_Dates )
Event selectors can indirectly reference payload of certain event types. DataEvents
,
DeltaEvents
as well as other event datagrams that support Event Annotations may export
payload values into user-defined event properties, thereby allowing event data to be used
in selector expressions, facilitating content-based communications.
An event selector matches the event if the selector evaluates to true. This is done by the dispatcher and is always performed local to the event producer in contrast with standard TCP/IP based multi-cast. A selector allows users to specify almost any match conditions on event property values. If a selector is specified, the match condition must be satisfied for an event to be consumed. The following common symbols and keywords can be used in a selector expression:
'(', ')', '=', '<', '>', '!=', '<>', '<=', '>=', 'true', 'false', 'and', 'or', 'not', 'null', 'is null', 'is not null', 'between', 'not between', '+', '-', '*', '/', 'in', 'not in', 'datetime', 'like', 'not like', 'escape', '%', '_', 'matches', 'not matches'.
The syntax of the comparator clause is similar to that of the Java language if
statement, however
comparator operands such as '=', 'and', 'or', 'not' are used instead of '==', '&&', '||',
'!'. Here are examples and their equivalent expressions:
x is null ~ x = null x is not null ~ x != null x between 1 and 2 ~ (x >= 1) and (x <= 2) x not between 1 and 2 ~ (x < 1) or (x > 2) str in ('Value1', 'Value2', 'Value3') ~ (str = 'Value1') or (str = 'Value2') or (str = 'Value3') str not in ('Value1', 'Value2', 'Value3') ~ (str != 'Value1') and (str != 'Value2') and (str != 'Value3')
The function datetime()
is used for comparing dates in different
formats. For example to check if the event property dateProperty
occurs before January 1, 2010
the following expression may be used:
dateProperty < datetime('01.01.2010')Keywords
like
, not like
, escape
, %
, _
are used to check string
properties (similar to the SQL language). The like
clause tests a string
property for partial match and not like
is a negation of the same test.
The keyword %
denotes partial inclusion (including empty) set of characters and the _
keyword means any single character. An escaping symbol can be specified via the escape
keyword, for example: escape '\'
.
Keywords matches
and not matches
are used for matching string
properties based on regular expressions. For regular expressions syntax see
documentation on regular expressions in Java
.
Match Examples
Consider we have an event with the following properties:
severity = 'Critical' source = 'DB_Database.main' time = '03/17/10 01:36:37.193' level = 3The following table shows the value of selector expressions for this event:
Expression | Value |
---|---|
notExistentProperty | false |
notExistentProperty = 5 | false |
severity is null | false |
(level < 4) and (severity != null) | true |
(level between 2 and 4) or (severity = NULL) | true |
((level + 1) / 4 * 2) not between 2 and 4 | false |
not (severity in ('Critical', 'Warning') or (level > 4)) | false |
time > datetime('16.03.2010 01:36:37.193') | true |
source like 'DB\_Database_main' escape '\' | true |
source not like '%Database.%' | false |
source matches '.*_Database\.[a-z]+' | true |
source not matches '\w+Database\.main' | false |
Selector syntax
An event selector is a String
whose syntax is based on a subset of the SQL92 conditional expression
syntax. The event selector extends capabilities defined in the JMS specification of selectors by introducing regular expression matching and
by allowing dispatchers to define dynamic lookup value collections that may be used in the extended IN
clause.
If the value of a event selector is an empty string, the value is treated as a null and indicates that there is no selector for
the event consumer.
The order of evaluation of an event selector is from left to right within precedence level. Parentheses can be used to change this order.
Predefined selector literals and operator names are shown here in uppercase; however, they are case insensitive.
A selector can contain:
'literal'
and 'literal''s'
. Like
string literals in the Java programming language, these use the
Unicode character encoding.
57
, -957
, and
+62
; numbers in the range of long
are
supported. Exact numeric literals use the integer literal
syntax of the Java programming language.
7E3
and -57.9E2
, or a
numeric value with a decimal, such as 7.
,
-95.7
, and +6.2
; numbers in the range of
double
are supported. Approximate literals use the
floating-point literal syntax of the Java programming language.
TRUE
and FALSE
.
Character.isJavaLetter
returns true. This includes '_'
and '$'
.
A letter or digit is any character for which the method
Character.isJavaLetterOrDigit
returns true.
NULL
,
TRUE
, and FALSE
.
NOT
, AND
,
OR
, BETWEEN
, LIKE
,
IN
, IS
, or ESCAPE
.
NULL
.
myEvent.setStringProperty("NumberOfOrders", "2");The following expression in an event selector would evaluate to false, because a string cannot be used in an arithmetic expression:
"NumberOfOrders > 1"
eventSource, eventId, durable, eventKey, eventGroupId, correlationId,
saToken, eventReplyTo, eventForwardTo, timeStamp, eventExpiration,
dataProtected, principal, credential, acl, coalesced
.
true
matches; a selector that evaluates to
false
or unknown does not match.
()
for ordering expression evaluation
is supported.
NOT
,
AND
, OR
=
, >
, >=
,
<
, <=
, <>
(not equal)
NULL
, the value of the expression is unknown.
=
and
<>
. Two strings are equal
if and only if they contain the same sequence of characters.
+
, -
(unary)
*
, /
(multiplication and division)
+
, -
(addition and subtraction)
arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2
AND arithmetic-expr3
(comparison operator)
"age BETWEEN 15 AND 19"
is
equivalent to
"age >= 15 AND age <= 19"
"age NOT BETWEEN 15 AND 19"
is equivalent to
"age < 15 OR age > 19"
identifier [NOT] IN (string-literal1,
string-literal2,...)
(comparison operator where
identifier
has a String
or
NULL
value)
"Country IN (' UK', 'US', 'France')"
is true for
'UK'
and false for 'Peru'
; it is
equivalent to the expression
"(Country = ' UK') OR (Country = ' US') OR (Country = ' France')"
"Country NOT IN (' UK', 'US', 'France')"
is false for 'UK'
and true for 'Peru'
; it
is equivalent to the expression
"NOT ((Country = ' UK') OR (Country = ' US') OR (Country = ' France'))"
IN
or NOT IN
operation is NULL
, the value of the operation is
unknown.
identifier [NOT] LIKE pattern-value [ESCAPE
escape-character]
(comparison operator, where
identifier
has a String
value;
pattern-value
is a string literal where
'_'
stands for any single character; '%'
stands for any sequence of characters, including the empty sequence;
and all other characters stand for themselves. The optional
escape-character
is a single-character string
literal whose character is used to escape the special meaning of the
'_'
and '%'
in
pattern-value
.)
"phone LIKE '12%3'"
is true for
'123'
or '12993'
and false for
'1234'
"word LIKE 'l_se'"
is true for
'lose'
and false for 'loose'
"underscored LIKE '\_%' ESCAPE '\'"
is true for '_foo'
and false for 'bar'
"phone NOT LIKE '12%3'"
is false for
'123'
or '12993'
and true for
'1234'
identifier
of a LIKE
or
NOT LIKE
operation is NULL
, the value
of the operation is unknown.
identifier IS NULL
(comparison operator that tests
for a null header field value or a missing property value)
"prop_name IS NULL"
identifier IS NOT NULL
(comparison operator that
tests for the existence of a non-null header field value or a property
value)
"prop_name IS NOT NULL"
As noted above, property values may be NULL
. The evaluation
of selector expressions containing NULL
values is defined by
SQL92 NULL
semantics. A brief description of these semantics
is provided here.
SQL treats a NULL
value as unknown. Comparison or arithmetic
with an unknown value always yields an unknown value.
The IS NULL
and IS NOT NULL
operators convert
an unknown value into the respective TRUE
and
FALSE
values.
The boolean operators use three-valued logic as defined by the following tables:
The definition of the AND
operator
| AND | T | F | U +------+-------+-------+------- | T | T | F | U | F | F | F | F | U | U | F | U +------+-------+-------+-------
The definition of the OR
operator
| OR | T | F | U +------+-------+-------+-------- | T | T | T | T | F | T | F | U | U | T | U | U +------+-------+-------+-------
The definition of the NOT
operator
| NOT +------+------ | T | F | F | T | U | U +------+-------
Copyright: Copyright (c) 2009
Company: StreamScape Technologies
Constructor and Description |
---|
EventDispatcher()
Constructs a new dispatcher.
|
Modifier and Type | Method and Description |
---|---|
void |
addEventCache(java.lang.String eventFilter,
int maxSize,
CacheThresholdAction thresholdAction)
Adds a new event cache.
|
void |
clear()
Clears the dispatcher.
|
EventAsyncConsumer |
createAsyncConsumer(java.lang.String consumerName,
java.lang.String eventFilter,
java.lang.String eventSelector,
EventListener listener)
Creates a new event asynchronous consumer and adds this consumer to the dispatcher.
|
EventConsumer |
createConsumer(java.lang.String consumerName,
java.lang.String eventFilter,
java.lang.String eventSelector,
EventListener listener)
Creates a new event asynchronous consumer and adds this consumer to the dispatcher.
|
DomainConstraint |
createDomainConstraint(java.lang.String name,
java.lang.String description,
java.util.Set values)
Creates a new Domain Constraint with the specified parameters.
|
RangeConstraint |
createRangeConstraint(java.lang.String name,
java.lang.String description,
java.lang.Object minValue,
java.lang.Object maxValue)
Creates a new Range Constraint with the specified parameters.
|
EventRequestConsumer |
createRequestConsumer(java.lang.String consumerName,
RequestListener listener)
Creates a new event request consumer and adds this consumer to the dispatcher.
|
void |
dropAsyncConsumer(java.lang.String consumerName)
Drops an event asynchronous consumer with the specified name.
|
void |
dropConsumer(java.lang.String consumerName)
Drops an event consumer with the specified name.
|
void |
dropDomainConstraint(java.lang.String name)
Drops a Domain Constraint with the specified name.
|
void |
dropRangeConstraint(java.lang.String name)
Drops a Range Constraint with the specified name.
|
void |
dropRequestConsumer(java.lang.String consumerName)
Drops an event request consumer with the specified name.
|
boolean |
existsAsyncConsumer(java.lang.String consumerName)
Checks if an event asynchronous consumer with the specified name exists.
|
boolean |
existsConsumer(java.lang.String consumerName)
Checks if an event consumer with the specified name exists.
|
boolean |
existsRequestConsumer(java.lang.String consumerName)
Checks if an event request consumer with the specified name exists.
|
EventAsyncConsumer |
getAsyncConsumer(java.lang.String consumerName)
Finds and returns an event asynchronous consumer with the specified name.
|
java.util.List |
getAsyncConsumers()
Returns a list of event asynchronous consumers of the dispatcher.
|
EventConsumer |
getConsumer(java.lang.String consumerName)
Finds and returns an event consumer with the specified name.
|
java.util.List |
getConsumers()
Returns a list of event consumers of the dispatcher.
|
DomainConstraint |
getDomainConstraint(java.lang.String name)
Finds and returns a Domain Constraint with the specified name.
|
java.util.List |
getDomainConstraints()
Returns a list of Domain Constraints.
|
EventCache |
getEventCache(java.lang.String eventFilter)
Returns an event cache associated with the specified simple event filter.
|
java.util.List |
getEventCaches()
Returns a list of all event caches.
|
RangeConstraint |
getRangeConstraint(java.lang.String name)
Finds and returns a Range Constraint with the specified name.
|
java.util.List |
getRangeConstraints()
Returns a list of Range Constraints.
|
EventRequestConsumer |
getRequestConsumer(java.lang.String consumerName)
Finds and returns an event request consumer with the specified name.
|
java.util.List |
getRequestConsumers()
Returns a list of event request consumers of the dispatcher.
|
void |
raiseEvent(ImmutableEventDatagram event)
Raises the specified event.
|
ImmutableEventDatagram |
raiseRequest(EventDatagram request,
RequestDistributionStrategy distributionStrategy,
ReplyMatchStrategy matchStrategy,
long timeout)
Raises the specified request and waits until a reply will be received or waiting period will expire.
|
ImmutableEventDatagram |
raiseRequest(EventRequestConsumer consumer,
ImmutableEventDatagram request,
long timeout)
Raises the specified request and waits until a reply will be received or waiting period will expire.
|
void |
removeEventCache(java.lang.String eventFilter)
Removes event cache associated with the specified simple event filter.
|
void |
reset()
Resets the dispatcher.
|
void |
start()
Starts the dispatcher.
|
void |
stop()
Stops the dispatcher.
|
public EventConsumer createConsumer(java.lang.String consumerName, java.lang.String eventFilter, java.lang.String eventSelector, EventListener listener) throws EventDispatcherException, FilterFormatException, SelectorFormatException
consumerName
- the name of the new consumer.eventFilter
- the event filter of the new consumer.eventSelector
- the event selector of the new consumer.listener
- the event listener associated with the new consumer.EventDispatcherException
- if a consumer with the specified name already exists.FilterFormatException
- if the event filter has invalid format.SelectorFormatException
- if the event selector has invalid format.public EventAsyncConsumer createAsyncConsumer(java.lang.String consumerName, java.lang.String eventFilter, java.lang.String eventSelector, EventListener listener) throws EventDispatcherException, FilterFormatException, SelectorFormatException
consumerName
- the name of the new consumer.eventFilter
- the event filter of the new consumer.eventSelector
- the event selector of the new consumer.listener
- the event listener associated with the new consumer.EventDispatcherException
- if a consumer with the specified name already exists.FilterFormatException
- if the event filter has invalid format.SelectorFormatException
- if the event selector has invalid format.public EventRequestConsumer createRequestConsumer(java.lang.String consumerName, RequestListener listener) throws EventDispatcherException
consumerName
- the name of the new consumer.listener
- the event listener associated with the new consumer.EventDispatcherException
- if a consumer with the specified name already exists.public void dropConsumer(java.lang.String consumerName)
consumerName
- the name of the consumer to be dropped.public void dropAsyncConsumer(java.lang.String consumerName)
consumerName
- the name of the consumer to be dropped.public void dropRequestConsumer(java.lang.String consumerName)
consumerName
- the name of the consumer to be dropped.public EventConsumer getConsumer(java.lang.String consumerName)
consumerName
- the name of the found consumer.public EventAsyncConsumer getAsyncConsumer(java.lang.String consumerName)
consumerName
- the name of the found consumer.public EventRequestConsumer getRequestConsumer(java.lang.String consumerName)
consumerName
- the name of the found consumer.public boolean existsConsumer(java.lang.String consumerName)
consumerName
- the name of consumer to be checked.true
if the consumer exists, false
otherwise.public boolean existsAsyncConsumer(java.lang.String consumerName)
consumerName
- the name of consumer to be checked.true
if the consumer exists, false
otherwise.public boolean existsRequestConsumer(java.lang.String consumerName)
consumerName
- the name of consumer to be checked.true
if the consumer exists, false
otherwise.public java.util.List getConsumers()
public java.util.List getAsyncConsumers()
public java.util.List getRequestConsumers()
public void addEventCache(java.lang.String eventFilter, int maxSize, CacheThresholdAction thresholdAction) throws EventDispatcherException, FilterFormatException
eventFilter
- the simple event filter associated with the cache.maxSize
- the cache size (maximum number of events which the cache can contain).thresholdAction
- the type of action that is performed if the cache is overflowed.EventDispatcherException
- if maxSize
is not positive or
if a cache with the specified event filter already exists.FilterFormatException
- if the event filter has invalid format.public void removeEventCache(java.lang.String eventFilter) throws FilterFormatException
eventFilter
- the simple event filter associated with the removed cache.FilterFormatException
- if the event filter has invalid format.public EventCache getEventCache(java.lang.String eventFilter) throws FilterFormatException
eventFilter
- the simple event filter associated with the cache.null
if the cache is not found.FilterFormatException
- if the event filter has invalid format.public java.util.List getEventCaches()
public void raiseEvent(ImmutableEventDatagram event) throws EventDispatcherException, EventException
event
- the event to be raised.EventDispatcherException
- if the dispatcher is not started.EventException
- if some error occurs during processing of the event in the listener.
This exception won't be raised for asynchronous listeners (EventAsyncConsumer
).public ImmutableEventDatagram raiseRequest(EventRequestConsumer consumer, ImmutableEventDatagram request, long timeout) throws EventDispatcherException, RequestException
consumer
- the consumer which will process the request.request
- the request to be raised.timeout
- the waiting time for reply (in milliseconds).EventDispatcherException
- if the dispatcher is not started or
if the consumer is not found or
if other error occurs.RequestException
- if some error occurs during processing of the request in the listener.public ImmutableEventDatagram raiseRequest(EventDatagram request, RequestDistributionStrategy distributionStrategy, ReplyMatchStrategy matchStrategy, long timeout) throws EventDispatcherException, EventException
request
- the request to be raised.distributionStrategy
- the strategy used for a distribution of the request.matchStrategy
- the strategy used for a matching of the reply.timeout
- the waiting time for reply (in milliseconds).EventDispatcherException
- if the dispatcher is not started or
if other error occurs.EventException
- if some error occurs during a processing of the event in the listener.
This exception won't be raised for asynchronous listeners (EventAsyncConsumer
).public DomainConstraint createDomainConstraint(java.lang.String name, java.lang.String description, java.util.Set values) throws EventDispatcherException
name
- the domain name.description
- the domain description.values
- the domain values.EventDispatcherException
- if a domain with the specified name already exists.public void dropDomainConstraint(java.lang.String name)
name
- the name of a domain to be dropped.public DomainConstraint getDomainConstraint(java.lang.String name)
name
- the name of a domain to be looked up.null if the corresponding domain was not found.
public java.util.List getDomainConstraints()
public RangeConstraint createRangeConstraint(java.lang.String name, java.lang.String description, java.lang.Object minValue, java.lang.Object maxValue) throws EventDispatcherException
name
- the range name.description
- the range description.EventDispatcherException
- if a range with the specified name already exists.public void dropRangeConstraint(java.lang.String name)
name
- the name of a range to be dropped.public RangeConstraint getRangeConstraint(java.lang.String name)
name
- the name of a range to be looked up.null if the corresponding range was not found.
public java.util.List getRangeConstraints()
public void start()
public void stop()
public void clear() throws EventDispatcherException
EventDispatcherException
public void reset() throws EventDispatcherException
EventDispatcherException
Copyright © 2015-2024 StreamScape Technologies. All rights reserved.