~~CLOSETOC~~
<html><font color=#990000 size="+2"><b>Event Fabric™ Users Guide</b></font></html>

The big picture of communications here


=====Overview=====

The event fabric is..


=====Discovery Modules=====
In order to find other nodes, client s and service engines alike must use discovery

=====User Defined Discovery=====

=====The Exchange Dispatcher=====
A critical component that is the central messaging agent within each service engine.  Configured by the serial form artifact.. etc..


<code xml>
<?xml version="1.0"?>
<FabricExchange>
  <deliveryThreadPoolSize>0</deliveryThreadPoolSize>
  <replyTimeout>30</replyTimeout>
  <allowFullMesh>false</allowFullMesh>
  <scavenger>
    <reconnectAttempts>0</reconnectAttempts>
    <reconnectInterval>30</reconnectInterval>
  </scavenger>
  <anonymousRegistration>true</anonymousRegistration>
</FabricExchange>

</code>

=====Defining a Topology=====

More information on how to define the topology of a sysplex

====Full Mesh Topology====
The multicastWaitingTime parameter specifies how long a service engine will wait for a response to its own discovery request from other nodes.  Note that at startup a service engine will block and wait for a response regardless of whether or not Full Mesh is enabled, thus slowing down service engine startup time.

====Ad-Hoc Topology====

=====Client Applications=====

====Client Connections (Runtime Context)====

====Client Connections (Client Context)====

====Client Context Imports====

The client context allows importing of critical artifacts necessary for establishing its operating environment, thereby facilitating a Zero-Footprint Install and initialization of a client application.  The application’s full state, related Java Archives, External Java libraries (CLASSPATH) and meta-data associated with data marshaling can be initialized as part of a standard connection to the application fabric.

Once a connection to the application fabric is established client applications may use IMPORT calls in order

-	Event Prototypes
-	EXT JARs are added to the system CLASSPATH of the client
-	Packages are loaded into the local Class Loader of the Application and added to the Package Manifest
-	Application State and Operational Data can be pulled in from the runtime’s Data Space and cached locally by the ClientContext as a series of Structured Data Objects.

====Zero-Maintenance Clients====


=====Content Aware Communication=====

=====Event Prototype Entitlement=====

Event entitlements provide an access control mechanism for protecting events against access by un-authorized users.  Entitlements are expressed as Access Control Lists that indicates whether certain participants may produce or consume events of a specific type.  For example, consider a Data Event that provides the latest price of a particular stock.  Users may wish to restrict the ability to raise such events only to an authorized user group in order to prevent the possibility of a rouge service publishing fake prices.

 	Note
	This feature is currently experimental and may not function fully.  Please check release notes for availability and any changes. 

====Event Level Security====

The event datagram security API provides a set of business functions that allow system developers to manipulate event data in a secure fashion.  While these functions are part of the event fabric, they provide a value-added layer beyond the TLP network protocol that allows users to secure event content and protect it against illegal modification, viewing and re-distribution.

The Access Control List allows users to specifcy 


 	Note
	This feature is currently experimental and may not function fully.  Please check release notes for availability and any changes. 

====Security Properties====

^ Property    ^ Data Type     ^ Description     ^
| principal   |	String	       | The name of the principal security entity that has protected the event from public access. |
| credential  | byte[]	       | The credential (key) used to protect the event from public access. |
| acl	      | AccessControl  | The access control list object for this event.  Meaningful only if the event has been protected. |

====Event Access Control List (ACL)====

====Protecting Events====

Cer

====Certified Event Delivery====

=====Annotating Events=====

Annotating events allows users to turn event payload data into searchable arguments that may be used for event filtering, routing and query (when events are stored in data collections).

Annotations are declared at the time of event prototype creation by using the Event Datagram Factory API.  

<code java>

// Init runtime..
this.ctx = RuntimeContext.getInstance();

// Create a prototype for the event
this.evFactory = this.ctx.getEventDatagramFactory();
RowEvent e = (RowEvent) this.evFactory.newEventInstance("RowEvent");

// Define a row event
RowMetaData descriptor = new RowMetaData(); 
descriptor.addColumn("SYMBOL");
descriptor.addColumn("TRADE_PRICE");
..
e.init(descriptor);     

// Declare annotated row elements
e.addAnnotation("Symbol", "//row/SYMBOL");
e.addAnnotation("TradePrice", "//row/TRADE_PRICE");   

</code>

Alternatively, the same operation can be performed thru the SLANG command line interface.

<code dsql>
create event prototype 
</code>


=====Raising Events=====

====User Defined Events====

<code java>
// Initialize client context
this.ctx = ClientContext.getInstance();
this.factory = new FabricConnectionFactory();
this.factory.setURL("tlp://localhost:5000");
this.connection = this.factory.createConnection("Admin", "admin"); 

// Identify ourselves to the fabric..
ClientId id = new ClientId();
id.setName("Admin");
id.setDomain("finance.com");
this.connection.setClientId(id);
this.connection.open();
             
// Obtain the datagram factory
EventDatagramFactory evFactory = this.ctx.getEventDatagramFactory();

// Make a new event of type DataEvent
DataEvent e = (DataEvent) evFactory.newEventInstance("DataEvent");
// Add user-defined property 
e.setEventStringProperty("AccountId", "2FC3");

// Create a data objects.. assumes this was defined as a valid Semantic Type    AccountUpdate update = new AccountUpdate ();
// Set the event's SDO content
e.setData(update);

// Obtain the prototype factory and create the event prototype
DatagramPrototypeFactory dtFactory = ctx.getDatagramPrototypeFactory();  
dtFactory.addDataEventPrototype("AcctUp", "event.update.Account", e);
// Bind the event to the producer
this.connection.bindProducerFor("event.update.Account"); 

// Create an event, reusing the event object
e = (DataEvent) this.evFactory.createEvent("event.update.Account");

// Raise Event with a GLOBAL scope for all to see
this.connection.raiseEvent(e, EventScope.GLOBAL, 0);
</code>


====Raising Exceptions====

====Raising Advisories====


====Raising Exceptions====






=====Consuming Events=====

====Event consumers ====


===Example of Exception Listener===

In this example a generic exception listener is created that can consume Service Framework Exceptions that are raised by hosted service components.  A connection is established and identified by specifying a unique clientId object.  Note the use of event scope to narrow the listener scope only to notifications that are raised within the application engine instance.   This consumer will not receive events from other nodes in the sysplex. 

<code java>
// Initialize client context
this.ctx = ClientContext.getInstance();

// Create an event fabric connection 
this.factory = new FabricConnectionFactory();
this.factory.setURL("tlp://localhost:5000");
this.connection = this.factory.createConnection("Admin", "admin");
 
// Identify ourselves to the fabric by setting Client Id (optional)..
ClientId id = new ClientId();
id.setName("Admin");
id.setDomain("MyApp");
this.connection.setClientId(id);

// Open the connection
this.connection.open();
                 
// Create a listener object..   
ErrorListener listener = new ErrorListener();

// Service Framework Exception prototypes are already part of client context
// No additional event prototype definition is necessary
EventAsyncConsumer c1 = this.connection.createEventAsyncConsumer("ErrorListener", listener, "exception.service.Framework", null, EventScope.OBSERVABLE, true);   
       
c1.start();
</code>

The actual error listener class is implemented as follows:

<code java>
   class ErrorListener implements FabricEventListener
   {
       	
// Implement an event listener callback 
       	public void onEvent(ImmutableEventDatagram event)
       	{
// Optional eventId check as listeners can accept many events 
            	if(event.getEventId().equals("exception.service.Framework"))
              	  {
              	  ServiceFrameworkException excp = (ServiceFrameworkException) event; 
              	  System.out.println("Received Error: \n\n" + excp.getMessage());
              	  }
       	}    
    }
</code>


<WRAP round tip>
 	
	In this example an asynchronous consumer is implemented.  This improves throughput at the expense of increasing latency as the listener’s consumer object buffers events in the internal event queue.  Events are delivered by an internal consumer thread that may be inspected using the SLANG environment if needed.  Consumer behavior may be tuned prior to the start() method call allowing for event queue depth and delivery cycle configuration. 

Asynchronous consumers do not impact event producers.  The raiseEvent() method returns immediately and does not block waiting for the onEvent() method to complete. 
</WRAP>


=====Event Flow Processing Patterns=====

Event

====Acknowledge-Based Processing====

Event consumers 

====Acknowledge and Forward Events====

Event consumers 

====Staged Event Processing====

Event consumers 

=====Event Selectors=====

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 Fabic'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.

     * Event Selectors support advanced date comparison and date range arithmetic
     * Event Selectors allow for regular expression matching of property values
     * Event Selectors may match on Domain and Range collections allowing criteria to be changed dynamically
     * Event Receivers may dynamically change selection criteria between receive operations, thus querying the event stream
     * Event Selectors may be pre-validated for reuse, eliminating run-time syntax errors
     * Selection may be performed against Annotated Fields, allowing data-aware filtering by payload content
     * 
Example Clause

<code slang>

        ( 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 )
 
</code>

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:

<code dsql>

     '(', ')', '=', '<', '>', '!=', '<>', '<=', '>=', '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'.

</code>

 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:

<code dsql>

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')

</code>
                                               
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:

<code dsql>
     dateProperty < datetime('01.01.2010')
</code>

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    = 3''
 
The 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:

•	Literals
o	A string literal is enclosed in single quotes, with a single quote represented by doubled single quote; for example, 'literal' and 'literal''s'. Like string literals in the Java programming language, these use the Unicode character encoding.
o	An exact numeric literal is a numeric value without a decimal point, such as 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.
o	An approximate numeric literal is a numeric value in scientific notation, such as 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.
o	The boolean literals TRUE and FALSE.

•	Identifiers:
o	An identifier is an unlimited-length sequence of letters and digits, the first of which must be a letter. A letter is any character for which the methodCharacter.isJavaLetter returns true. This includes '_' and '$'. A letter or digit is any character for which the methodCharacter.isJavaLetterOrDigit returns true.
o	Identifiers cannot be the names NULL, TRUE, and FALSE.
o	Identifiers cannot be NOT, AND, OR, BETWEEN, LIKE, IN, IS, or ESCAPE.
o	Identifiers are either header field references or property references. The type of a property value in an event selector corresponds to the type used to set the property. If a property that does not exist in an event is referenced, its value is NULL.
o	The conversions that apply to the get methods for properties do not apply when a property is used in an event selector expression. For example, suppose you set a property as a string value, as in the following:
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"
o	Identifiers are case-sensitive.
o	Event header field references are restricted to eventSource, eventId, durable, eventKey, eventGroupId, correlationId, saToken, eventReplyTo, eventForwardTo, timeStamp, eventExpiration, dataProtected, principal, credential, acl, coalesced.
•	White space is the same as that defined for the Java programming language: space, horizontal tab, form feed, and line terminator.
•	Expressions:
o	A selector is a conditional expression; a selector that evaluates to true matches; a selector that evaluates to false or unknown does not match.
o	Arithmetic expressions are composed of themselves, arithmetic operations, identifiers (whose value is treated as a numeric literal), and numeric literals.
o	Conditional expressions are composed of themselves, comparison operations, and logical operations.
•	Standard bracketing () for ordering expression evaluation is supported.
•	Logical operators in precedence order: NOT, AND, OR
•	Comparison operators: =, >, >=, <, <=, <> (not equal)
o	Only like type values can be compared. One exception is that it is valid to compare exact numeric values and approximate numeric values; the type conversion required is defined by the rules of numeric promotion in the Java programming language. If the comparison of non-like type values is attempted, the value of the operation is false. If either of the type values evaluates to NULL, the value of the expression is unknown.
o	String and boolean comparison is restricted to = and <>. Two strings are equal if and only if they contain the same sequence of characters.
•	Arithmetic operators in precedence order:
o	+, - (unary)
o	*, / (multiplication and division)
o	+, - (addition and subtraction)
o	Arithmetic operations must use numeric promotion in the Java programming language.
•	arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3 (comparison operator)
o	"age BETWEEN 15 AND 19" is equivalent to "age >= 15 AND age <= 19"
o	"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)
o	"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')"
o	"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'))"
o	If identifier of an 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.)
o	"phone LIKE '12%3'" is true for '123' or '12993' and false for '1234'
o	"word LIKE 'l_se'" is true for 'lose' and false for 'loose'
o	"underscored LIKE '\_%' ESCAPE '\'" is true for '_foo' and false for 'bar'
o	"phone NOT LIKE '12%3'" is false for '123' or '12993' and true for '1234'
o	If 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)
o	"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)
o	"prop_name IS NOT NULL"
Null Values
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:
AND Operator
 | AND  |   T   |   F   |   U
 +------+-------+-------+-------
 |  T   |   T   |   F   |   U
 |  F   |   F   |   F   |   F
 |  U   |   U   |   F   |   U
 +------+-------+-------+-------
OR Operator
 | OR   |   T   |   F   |   U
 +------+-------+-------+--------
 |  T   |   T   |   T   |   T
 |  F   |   T   |   F   |   U
 |  U   |   T   |   U   |   U
 +------+-------+-------+-------
NOT Operator
 | NOT
 +------+------
 |  T   |   F
 |  F   |   T
 |  U   |   U
 +------+-------
 


Selector Constraints
Event selectors support the notion of CONSTRAINT objects that allow selectors to function in a non-deterministic fashion, meaning that their conditions will be determined at execution time.  Constraint objects make it possible for user to change the selection criteria without re-creating a SELECTOR by referencing contrain objects wihin an IN clause.

DOMAIN CONSTRAINT


RANGE CONSTRAINT
Selecting Events from a Stream
Event selectors can be used in combination with event fabric API methods for receiving events 









Event Filters
tbd

Filtering Events from a Stream

<html>
<img src="/dokuwiki/_media/icons_large/bowlerhat-transp.png" alt="Smiley face" height="46" width="46" style="margin-left:-6px;">
<a href="/dokuwiki/start" style="margin-left:-1em; font-weight:bold; color:#990000">Back</a>
</html> 