[
https://issues.apache.org/jira/browse/FLINK-6198?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16032944#comment-16032944
]
ASF GitHub Bot commented on FLINK-6198:
---------------------------------------
Github user tzulitai commented on a diff in the pull request:
https://github.com/apache/flink/pull/4041#discussion_r119604721
--- 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
+ non-matching events between any matching ones.
+
+The latter refers to "looping" states, i.e. states that can accept more
than one event, e.g. the `b+` in `a b+ c`,
+which searches for one or more `b`'s.
+
+##### Conditions on Properties
--- End diff --
I found this title to be very "hidden" in the content, in that its
subsection titles "Iterative Conditions" and "Simple Conditions" where actually
more prominent.
Not really sure if this can be addressed though, just pointing out an
observation on the built docs.
> 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)
