[
https://issues.apache.org/jira/browse/FLINK-6198?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16032976#comment-16032976
]
ASF GitHub Bot commented on FLINK-6198:
---------------------------------------
Github user dawidwys commented on a diff in the pull request:
https://github.com/apache/flink/pull/4041#discussion_r119607252
--- Diff: docs/dev/libs/cep.md ---
@@ -98,48 +128,105 @@ val result: DataStream[Alert] =
patternStream.select(createAlert(_))
</div>
</div>
-Note that we use Java 8 lambdas in our Java code examples to make them
more succinct.
-
## The Pattern API
-The pattern API allows you to quickly define complex event patterns.
-
-Each pattern consists of multiple stages or what we call states.
-In order to go from one state to the next, the user can specify conditions.
-These conditions can be the contiguity of events or a filter condition on
an event.
-
-Each pattern has to start with an initial state:
+The pattern API allows you to quickly define complex pattern sequences
that you want to extract
+from your input stream.
+
+Each such complex pattern sequence consists of multiple simple patterns,
i.e. patterns looking for
+individual events with the same properties. These simple patterns are
called **states**. A complex pattern
+can be seen as a graph of such states, where transition from one state to
the next happens based on user-specified
+*conditions*, e.g. `event.getName().equals("start")`. A *match* is a
sequence of input events which visit all
+states of the complex pattern graph, through a sequence of valid state
transitions.
+
+<span class="label label-danger">Attention</span> Each state must have a
unique name to identify the matched
+events later on.
+
+<span class="label label-danger">Attention</span> State names **CANNOT**
contain the character `:`.
+
+In the remainder, we start by describing how to define [States](#states),
before describing how you can
+combine individual states into [Complex Patterns](#combining-states).
+
+### Individual States
+
+A **State** can be either a *singleton* state, or a *looping* one.
Singleton states accept a single event,
+while looping ones accept more than one. In pattern matching symbols, in
the pattern `a b+ c? d` (or `a`,
+followed by *one or more* `b`'s, optionally followed by a `c`, followed by
a `d`), `a`, `c?`, and `d` are
+singleton patterns, while `b+` is a looping one (see
[Quantifiers](#quantifiers)). In addition, each state
+can have one or more *conditions* based on which it accepts events (see
[Conditions](#conditions)).
+
+#### Quantifiers
+
+In FlinkCEP, looping patterns can be specified using the methods:
`pattern.oneOrMore()`, for states that expect one or
+more occurrences of a given event (e.g. the `b+` mentioned previously),
and `pattern.times(#ofTimes)` for states that
+expect a specific number of occurrences of a given type of event, e.g. 4
`a`'s. All states, looping or not, can be made
+optional using the `pattern.optional()` method. For a state named `start`,
the following are valid quantifiers:
+
+ <div class="codetabs" markdown="1">
+ <div data-lang="java" markdown="1">
+ {% highlight java %}
+ // expecting 4 occurrences
+ start.times(4);
+
+ // expecting 0 or 4 occurrences
+ start.times(4).optional();
+
+ // expecting 1 or more occurrences
+ start.oneOrMore();
+
+ // expecting 0 or more occurrences
+ start.oneOrMore().optional();
+ {% endhighlight %}
+ </div>
+
+ <div data-lang="scala" markdown="1">
+ {% highlight scala %}
+ // expecting 4 occurrences
+ start.times(4)
+
+ // expecting 0 or 4 occurrences
+ start.times(4).optional()
+
+ // expecting 1 or more occurrences
+ start.oneOrMore()
+
+ // expecting 0 or more occurrences
+ start.oneOrMore().optional()
+ {% endhighlight %}
+ </div>
+ </div>
+
+#### Conditions
+
+At every state, and in order to go from one state to the next, you can
specify additional **conditions**.
+These conditions can be related to:
+
+ 1. a [property of the incoming event](#conditions-on-properties), e.g.
its value should be larger than 5,
+ or larger than the average value of the previously accepted events.
+
+ 2. the [contiguity of the matching events](#conditions-on-contiguity),
e.g. detect pattern `a,b,c` without
--- End diff --
I would move this to the combining patterns section. It is easier to reason
about after understanding the contiguity between single patterns/states.
> Update the documentation of the CEP library to include all the new features.
> ----------------------------------------------------------------------------
>
> Key: FLINK-6198
> URL: https://issues.apache.org/jira/browse/FLINK-6198
> Project: Flink
> Issue Type: Sub-task
> Components: CEP
> Affects Versions: 1.3.0
> Reporter: Kostas Kloudas
> Assignee: Kostas Kloudas
> Priority: Critical
> Fix For: 1.3.0
>
>
> New features to include:
> * Iterative Functions
> * Quantifiers
> * Time handling
> * Migration from FilterFunction to IterativeCondition
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
