Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "VIATRA/CEP/Language"

< VIATRA‎ | CEP
(The VIATRA-CEP framework)
(Rules)
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
=VIATRA-CEP User's guide=
+
=Atomic event patterns=
The following contents introduce the VIATRA-CEP complex event processing stack and its main features. Basic knowledge on [http://en.wikipedia.org/wiki/Complex_event_processing complex event processing] is advised, although not strictly required. Should this guide prove to be insufficient, please do not hesitate to ask your question on our [mailto:viatra-dev@eclipse.org mailing list].
+
 
+
==Getting started==
+
===The VIATRA-CEP framework===
+
The VIATRA-CEP is the part of the VIATRA stack. The framework consist of the following components:
+
*a model-driven '''event processing engine''';
+
*a '''textual domain-specific language''' (VEPL - the VIATRA Event Processing Language) for defining atomic and complex event patterns and executable actions to trigger on observed event patterns;
+
*supporting functionality, like a cutting-edge IDE with validation, code generation and different wizards to facilitate an efficient modeling workflow.
+
 
+
====Default workflow====
+
//TODO
+
 
+
====Use cases====
+
//TODO
+
 
+
===Language essentials===
+
This section is a brief overview on the features of the VIATRA Event Processing Language (VEPL).
+
====Atomic event patterns====
+
 
  '''AtomicEvent''' ''name'' '''('''''parameters''''')''' '''{'''''body'''''}'''
 
  '''AtomicEvent''' ''name'' '''('''''parameters''''')''' '''{'''''body'''''}'''
 
*The name of the atomic event must be unique among the model.
 
*The name of the atomic event must be unique among the model.
Line 25: Line 7:
 
From this structure, two types of source code is generated: atomic events and atomic event patterns. The former ones are used by applications to be instantiated and forwarded to the engine; while the latter ones are actual patterns which can be reused in /link complex event pattern definitions or /link rules.
 
From this structure, two types of source code is generated: atomic events and atomic event patterns. The former ones are used by applications to be instantiated and forwarded to the engine; while the latter ones are actual patterns which can be reused in /link complex event pattern definitions or /link rules.
  
====Complex event patterns====
+
=Complex event patterns=
 
  '''ComplexEvent''' ''name'' '''('''''parameters''''')''' '''{'''
 
  '''ComplexEvent''' ''name'' '''('''''parameters''''')''' '''{'''
 
       '''definition:''' ''complex pattern definition''
 
       '''definition:''' ''complex pattern definition''
 
  '''}'''
 
  '''}'''
The <tt>definition</tt> block holds the actual pattern. It is built up using [[#Atomic_event_pattern|Atomic event patterns]], [[#IncQuery_event_pattern|IncQuery event patterns]] and other [[#Complex_event_pattern|Complex event patterns]], which are chained together by [[#Complex_event_operator|Complex event operators]]. The definition can be nested using parentheses, although, for the sake of clarity, we recommend avoiding too complex patterns by breaking them into separate [[#Complex_event_pattern|Complex event patterns]] and reusing these patterns in the original definition.
+
The <tt>definition</tt> block holds the actual pattern. It is built up using [[#Atomic_event_patterns|Atomic event patterns]], [[#Query_result_change_event_patterns|Query result change event patterns]] and other [[#Complex_event_patterns|Complex event patterns]], which are chained together by [[#Complex_event_operators|Complex event operators]]. The definition can be nested using parentheses, although, for the sake of clarity, we recommend avoiding too complex patterns by breaking them into separate [[#Complex_event_patterns|Complex event patterns]] and reusing these patterns in the original definition.
  
====Complex event operators====
+
==Complex event operators==
{|
+
{| border="1" cellpadding="5" cellspacing="0" align="center"
! style="text-align:left;"| Operator name
+
|-
 +
! Operator name  
 
! Denotation
 
! Denotation
 
! Meaning
 
! Meaning
Line 48: Line 31:
 
|p<sub>1</sub> <tt>'''AND'''</tt> p<sub>2</sub>
 
|p<sub>1</sub> <tt>'''AND'''</tt> p<sub>2</sub>
 
|Both of the patterns has to appear, but the order does not matter. Rule: p<sub>1</sub> <tt>'''AND'''</tt> p<sub>2</sub> === ((p<sub>1</sub> <tt>'''->'''</tt> p<sub>2</sub>) OR (p<sub>2</sub> <tt>'''->'''</tt> p<sub>1</sub>)).
 
|Both of the patterns has to appear, but the order does not matter. Rule: p<sub>1</sub> <tt>'''AND'''</tt> p<sub>2</sub> === ((p<sub>1</sub> <tt>'''->'''</tt> p<sub>2</sub>) OR (p<sub>2</sub> <tt>'''->'''</tt> p<sub>1</sub>)).
|-
 
|until
 
|p<sub>1</sub> <tt>'''U'''</tt> p<sub>2</sub>
 
|Once the first pattern appears, no else pattern is allowed to appear until the second pattern appears. Rule: p<sub>1</sub> <tt>'''U'''</tt> p<sub>2</sub> === p<sub>1</sub> <tt>'''->'''</tt> p<sub>1</sub> <tt>'''->'''</tt> ... p<sub>2</sub>, unlimited times.
 
 
|-
 
|-
 
|multiplicity
 
|multiplicity
 
|p<tt>'''{'''''n'''''}'''</tt>
 
|p<tt>'''{'''''n'''''}'''</tt>
|The pattern has to appear ''n'' times. Rule: p<tt>'''{'''''n'''''}'''</tt> === p<sub>1</sub> <tt>'''->'''</tt> p<sub>1</sub> <tt>'''->'''</tt> ... p<sub>1</sub>, ''n'' times.
+
|The pattern has to appear ''n'' times, where n is a positive integer. Rule: p<tt>'''{'''''n'''''}'''</tt> === p<sub>1</sub> <tt>'''->'''</tt> p<sub>1</sub> <tt>'''->'''</tt> ... p<sub>1</sub>, ''n'' times.
 +
|-
 +
|"at least once" multiplicity
 +
| p<tt>'''{+}'''</tt>
 +
|The pattern has to appear at least once.
 
|-
 
|-
 
|within timewindow
 
|within timewindow
Line 88: Line 71:
 
These are considered as the '''normal''' cases.
 
These are considered as the '''normal''' cases.
  
====IncQuery event patterns====
+
=Query result change event patterns=
  '''IQPatternEvent''' ''name'' '''('''''parameters''''')''' '''{'''
+
  '''QueryResultChangeEvent''' ''name'' '''('''''parameters''''')''' '''{'''
       '''iqPatternRef:''' ''name of the referred IncQuery pattern''
+
       '''query:''' ''name of the referred model query''
       '''iqChangeType:''' ''NEW_MATCH_FOUND or EXISTING_MATCH_LOST''
+
       ('''resultChangeType:''' ''NEW_MATCH_FOUND or EXISTING_MATCH_LOST'')?
 
  '''}'''
 
  '''}'''
IncQuery event patterns are specific types of [[#Atomic_event_pattern|Atomic event patterns]]. They arise from an underlying EMF model observed by an EMF-IncQuery engine. When the referred IncQuery pattern is found (NEW_MATCH_FOUND) or lost (EXISTING_MATCH_LOST), a generated bridge component between the IncQuery engine and the CEP engine generates an event and forwards it to the CEP engine. IncQuery event patterns can be reused in [[#Complex_event_pattern|Complex event patterns]], just like simple [[#Atomic_event_pattern|Atomic event patterns]].
+
Query result change event patterns are specific types of [[#Atomic_event_patterns|Atomic event patterns]]. They arise from an underlying EMF model observed by a query engine. When the referred query is found (NEW_MATCH_FOUND) or lost (EXISTING_MATCH_LOST), a generated bridge component between the query engine and the CEP engine generates an event and forwards it to the CEP engine. Query result change event patterns can be reused in [[#Complex_event_patterns|Complex event patterns]], just like simple [[#Atomic_event_patterns|Atomic event patterns]].
 +
The default query engine supporting this feature is [http://www.eclipse.org/incquery/ EMF-IncQuery].
  
====Rules====
+
=Rules=
 
  '''Rule''' ''name'' '''{'''
 
  '''Rule''' ''name'' '''{'''
 
       '''events:''' ''comma separated list of complex patterns''
 
       '''events:''' ''comma separated list of complex patterns''
Line 110: Line 94:
 
Rules connect defined event patterns with executable actions. If any of the event patterns in the <tt>events</tt> block is observed, the related action is executed. One can define actions either by the <tt>action</tt> block and write the executable code snippet in-place; or by using the <tt>actionHandler</tt>, which gives a reference to an external class implementing the IActionHandler interface. In the former case, the action is defined using [https://wiki.eclipse.org/Xbase Xbase], in the latter case via Java, Scala, or any other JVM language.
 
Rules connect defined event patterns with executable actions. If any of the event patterns in the <tt>events</tt> block is observed, the related action is executed. One can define actions either by the <tt>action</tt> block and write the executable code snippet in-place; or by using the <tt>actionHandler</tt>, which gives a reference to an external class implementing the IActionHandler interface. In the former case, the action is defined using [https://wiki.eclipse.org/Xbase Xbase], in the latter case via Java, Scala, or any other JVM language.
  
====Packages and Usages====
+
==Accessing parameter bindings and observed event instances==
 +
The bound parameters can be obtained as follows:
 +
ruleInstance.atom.parameterTable.parameterBindings
 +
 
 +
Atomic event instances building up the matched event pattern can be obtained as follows:
 +
ruleInstance.atom.observedAtomicEventInstances
 +
 
 +
=Packages and Imports=
 
  '''package''' ''name''
 
  '''package''' ''name''
 
VEPL allows the model to be organized into different packages and reuse those packages in other ones by usages. Every model begins with a package declaration, which is a hierarchical identifier. For example: <tt>'''package''' com.company.cepproject</tt>.
 
VEPL allows the model to be organized into different packages and reuse those packages in other ones by usages. Every model begins with a package declaration, which is a hierarchical identifier. For example: <tt>'''package''' com.company.cepproject</tt>.
  '''uses''' ''package name with wildcard or a specific class in a package''
+
  '''import''' ''package name with wildcard or a specific class in a package''
  '''uses-patterns''' ''IncQuery pattern package''
+
  '''import-queries''' ''model query pattern package''
The <tt>uses</tt> keyword imports other VEPL packages or source code packages; the <tt>uses-patterns</tt> keyword imports IncQuery patterns to be used in [[#IncQuery_event_patterns|IncQuery event patterns]].
+
The <tt>import</tt> keyword imports other VEPL packages or source code packages; the <tt>import-queries</tt> keyword imports model queries to be used in [[#Query_result_change_event_patterns|Query result change event patterns]].
 
+
==Setting up the environment==
+
 
+
#Download the latest [https://eclipse.org/downloads/packages/eclipse-modeling-tools/lunasr1 Eclipse Luna Modeling] (currently SR1) package.
+
#Install the following plugins or import their source plug-ins into a running Eclipse instance:
+
#; EMF-IncQuery 0.9.0 : [http://download.eclipse.org/incquery/updates/integration CI update site]
+
#; VIATRA 0.7.0 (required components are VIATRA2-EMF and VIATRA-CEP) : [https://hudson.eclipse.org/viatra/job/viatra2-emf-master/lastSuccessfulBuild/artifact/releng/org.eclipse.viatra2.emf.update/target/repository/ CI update site]
+
 
+
==Examples==
+
You can find demonstrative examples [[VIATRA2/CEP/Examples|here]].
+
 
+
==Important links==
+
*[https://bugs.eclipse.org/bugs/buglist.cgi?component=CEP&list_id=10827336&product=Viatra&resolution=--- VIATRA-CEP Bugzilla]
+
*our mailing list: [mailto:viatra-dev@eclipse.org viatra-dev@eclipse.org]
+
*[http://link.springer.com/chapter/10.1007%2F978-3-319-11653-2_5 A paper on VIATRA-CEP from MoDELS 2014] (Available for download from [http://msdl.cs.mcgill.ca/people/istvan/publications/viatra-cep-models2014 here].)
+

Revision as of 08:51, 21 May 2015

Atomic event patterns

AtomicEvent name (parameters) {body}
  • The name of the atomic event must be unique among the model.
  • The parameters are typed and use the JVM type hierarchy. An example parameter list could be (name:String, id:int). Parameters are evaluated at runtime. To see the main motivation behind this, see the Complex event patterns.
  • The body is currently not in used, but it will be soon: https://bugs.eclipse.org/bugs/show_bug.cgi?id=440748.

From this structure, two types of source code is generated: atomic events and atomic event patterns. The former ones are used by applications to be instantiated and forwarded to the engine; while the latter ones are actual patterns which can be reused in /link complex event pattern definitions or /link rules.

Complex event patterns

ComplexEvent name (parameters) {
     definition: complex pattern definition
}

The definition block holds the actual pattern. It is built up using Atomic event patterns, Query result change event patterns and other Complex event patterns, which are chained together by Complex event operators. The definition can be nested using parentheses, although, for the sake of clarity, we recommend avoiding too complex patterns by breaking them into separate Complex event patterns and reusing these patterns in the original definition.

Complex event operators

Operator name Denotation Meaning
followed by p1 -> p2 Both patterns have to appear in the specified order.
or p1 OR p2 One of the patterns has to appear.
and p1 AND p2 Both of the patterns has to appear, but the order does not matter. Rule: p1 AND p2 === ((p1 -> p2) OR (p2 -> p1)).
multiplicity p{n} The pattern has to appear n times, where n is a positive integer. Rule: p{n} === p1 -> p1 -> ... p1, n times.
"at least once" multiplicity p{+} The pattern has to appear at least once.
within timewindow p[t] Once the first element of the pattern is observed (i.e. the patterns "starts to build up"), the rest of the pattern has to be observed within t milliseconds.


It is possible to combine the multiplicity and the timewindow operators, although the following rules hold.

1. Single atomic event pattern in a complex event definition.

ComplexEvent ce1(){
     definition: atomic1
}

This will result in a warning, since does not add anything to the atomic definition and therefore, it is considered as an anti-pattern.

2. Single atomic event pattern with a timewindow operator, but without a multiplicity operator.

ComplexEvent ce2(){
     definition: atomic1[100]
}

This will result in an error, since it is not meaningful to specify constraints over elements with point-semantics in a given dimension. (In this case: the time dimension of an atomic event pattern.)

3. Single atomic event pattern with a multiplicity operator and an optional timewindow operator.

ComplexEvent ce3a(){
     definition: atomic1{10}
}
ComplexEvent ce3b(){
    definition: atomic1{10}[100]
}

These are considered as the normal cases.

Query result change event patterns

QueryResultChangeEvent name (parameters) {
     query: name of the referred model query
     (resultChangeType: NEW_MATCH_FOUND or EXISTING_MATCH_LOST)?
}

Query result change event patterns are specific types of Atomic event patterns. They arise from an underlying EMF model observed by a query engine. When the referred query is found (NEW_MATCH_FOUND) or lost (EXISTING_MATCH_LOST), a generated bridge component between the query engine and the CEP engine generates an event and forwards it to the CEP engine. Query result change event patterns can be reused in Complex event patterns, just like simple Atomic event patterns. The default query engine supporting this feature is EMF-IncQuery.

Rules

Rule name {
     events: comma separated list of complex patterns
     action {
          executable code block using Xbase syntax
     }
}
Rule name {
     events: comma separated list of complex patterns
     actionHandler: reference to an action handler, i.e. a class implementing the IActionHandler interface
}

Rules connect defined event patterns with executable actions. If any of the event patterns in the events block is observed, the related action is executed. One can define actions either by the action block and write the executable code snippet in-place; or by using the actionHandler, which gives a reference to an external class implementing the IActionHandler interface. In the former case, the action is defined using Xbase, in the latter case via Java, Scala, or any other JVM language.

Accessing parameter bindings and observed event instances

The bound parameters can be obtained as follows:

ruleInstance.atom.parameterTable.parameterBindings

Atomic event instances building up the matched event pattern can be obtained as follows:

ruleInstance.atom.observedAtomicEventInstances

Packages and Imports

package name

VEPL allows the model to be organized into different packages and reuse those packages in other ones by usages. Every model begins with a package declaration, which is a hierarchical identifier. For example: package com.company.cepproject.

import package name with wildcard or a specific class in a package
import-queries model query pattern package

The import keyword imports other VEPL packages or source code packages; the import-queries keyword imports model queries to be used in Query result change event patterns.

Back to the top