You are on page 1of 487
Reference Documentation Version: 4.5.0 provided by

Reference Documentation

Version: 4.5.0

provided by

Reference Documentation Version: 4.5.0 provided by

Table of Contents

Preface

xviii

  • 1. Technology Overview

..................................................................................................................

1

  • 1.1. Introduction to CEP and event stream analysis

1

  • 1.2. CEP and relational databases

1

  • 1.3. The Esper engine for CEP

1

  • 1.4. Required 3rd Party Libraries

2

  • 2. Event Representations

3

  • 2.1. Event Underlying Java Objects

3

  • 2.2. Event Properties

.................................................................................................................

4

  • 2.2.1. Escape Characters

4

  • 2.3. Dynamic Event Properties

..................................................................................................

5

  • 2.4. Fragment and Fragment Type

6

  • 2.5. Plain-Old Java Object Events

7

  • 2.5.1. Java Object Event Properties

7

  • 2.5.2. Property Names

8

  • 2.5.3. Constants and Enumeration

9

  • 2.5.4. Parameterized Types

9

  • 2.5.5. Setter Methods for Indexed and Mapped Properties

10

  • 2.5.6. Known Limitations

10

  • 2.6. java.util.Map Events

10

Overview

  • 2.6.1. ..............................................................................................................

10

Map Properties

  • 2.6.2. ......................................................................................................

11

  • 2.6.3. ....................................................................................................

Map Supertypes

12

  • 2.6.4. Advanced Map Property Types

12

  • 2.6.4.1. Nested Properties

........................................................................................

12

  • 2.6.4.2. Map Event Type Properties

13

  • 2.6.4.3. One-to-Many Relationships

14

  • 2.7. org.w3c.dom.Node XML Events

14

  • 2.7.1. Schema-Provided XML Events

16

Getting Started

  • 2.7.1.1. ...........................................................................................

16

  • 2.7.1.2. Property Expressions and Namespaces

16

  • 2.7.1.3. Property Expression to XPath Rewrite

17

Array Properties

  • 2.7.1.4. .........................................................................................

17

  • 2.7.1.5. Dynamic Properties

....................................................................................

18

  • 2.7.1.6. Transposing Properties

18

Event Sender

  • 2.7.1.7. ..............................................................................................

19

Limitations

  • 2.7.1.8. .................................................................................................

19

  • 2.7.2. No-Schema-Provided XML Events

19

  • 2.7.3. Explicitly-Configured Properties

19

  • 2.7.3.1. Simple Explicit Property

.............................................................................

20

  • 2.7.3.2. Explicit Property Casting and Parsing

20

 
  • 2.7.3.3. Node and Nodeset Explicit Property

20

  • 2.8. Additional Event Representations

......................................................................................

21

  • 2.9. Updating, Merging and Versioning Events

22

  • 2.10. Coarse-Grained Events

22

  • 2.11. Event Objects Instantiated and Populated by Insert Into

22

 
  • 2.12. Comparing Event Types

24

  • 3. Processing Model

25

Esper - Event Stream and Complex Event Processing for Java

Introduction

  • 3.1. .....................................................................................................................

25

  • 3.2. ....................................................................................................................

Insert Stream

25

  • 3.3. Insert and Remove Stream

26

  • 3.4. Filters and Where-clauses

27

Time Windows

  • 3.5. ................................................................................................................

29

3.5.1.

Time Window

29

3.5.2.

Time Batch

30

Batch Windows

  • 3.6. ................................................................................................................

31

  • 3.7. Aggregation and Grouping

................................................................................................

32

3.7.1.

Insert and Remove Stream

32

3.7.2.

Output for Aggregation and Group-By

32

3.7.2.1.

Un-aggregated and Un-grouped

...................................................................

33

3.7.2.2.

Fully Aggregated and Un-grouped

33

3.7.2.3.

Aggregated and Un-Grouped

33

3.7.2.4.

Fully Aggregated and Grouped

34

3.7.2.5.

Aggregated and Grouped

34

  • 3.8. Event Visibility and Current Time

34

  • 4. Context and Context Partitions

35

  • 4.1. Introduction

35

  • 4.2. Context Declaration

36

4.2.1.

Keyed Segmented Context

36

4.2.1.1.

Multiple Stream Definitions

38

4.2.1.2.

Filters

38

4.2.1.3.

Multiple Properties Per Event Type

38

4.2.1.4.

Built-In Context Properties

39

4.2.1.5.

Examples of Joins

39

4.2.2.

Hash Segmented Context

.......................................................................................

40

4.2.2.1.

Multiple Stream Definitions

41

4.2.2.2.

Filters

41

4.2.2.3.

Built-In Context Properties

..........................................................................

42

4.2.2.4.

Performance Considerations

42

4.2.3.

Category Segmented Context

.................................................................................

42

4.2.3.1.

Built-In Context Properties

43

4.2.4.

Non-Overlapping Context

43

4.2.5.

Overlapping Context

..............................................................................................

44

4.2.5.1.

Built-In Context Properties

45

4.2.6.

Context Conditions

................................................................................................

46

4.2.6.1.

Filter Context Condition

..............................................................................

46

4.2.6.2.

Pattern Context Condition

47

4.2.6.3.

Crontab Context Condition

..........................................................................

48

4.2.6.4.

Time Period Context Condition

48

  • 4.3. Context Nesting

...............................................................................................................

48

4.3.1.

Built-In Nested Context Properties

49

  • 4.4. Partitioning Without Context Declaration

50

  • 4.5. Output When Context Partition Ends

51

  • 4.6. Context and Named Window

............................................................................................

52

  • 4.7. Operations on Specific Context Partitions

53

  • 5. EPL Reference: Clauses

54

EPL Introduction

  • 5.1. ..............................................................................................................

54

  • 5.2. ......................................................................................................................

EPL Syntax

55

5.2.1.

Specifying Time Periods

55

5.2.2.

Using Comments

56

Esper - Event Stream and Complex Event Processing for Java

  • 5.2.3. Reserved Keywords

56

Escaping Strings

  • 5.2.4. ....................................................................................................

57

  • 5.2.5. ............................................................................................................

Data Types

57

5.2.5.1.

Data Type of Constants

58

5.2.5.2.

BigInteger and BigDecimal

59

Annotation

  • 5.2.6. ............................................................................................................

59

5.2.6.1.

Application-Provided Annotations

59

5.2.6.2.

Built-In Annotations

60

5.2.6.3.

@Name

61

5.2.6.4.

@Description

61

5.2.6.5.

@Tag

62

5.2.6.6.

@Priority

62

5.2.6.7.

@Drop

62

5.2.6.8.

@Hint

62

5.2.6.9.

@Hook

63

5.2.6.10. @Audit

63

  • 5.2.7. Expression Declaration

63

Script Declaration

  • 5.2.8. ..................................................................................................

64

  • 5.2.9. Referring to a Context

64

  • 5.3. Choosing Event Properties And Events: the Select Clause

65

  • 5.3.1. Choosing all event properties: select *

65

  • 5.3.2. Choosing specific event properties

66

  • 5.3.3. Expressions

...........................................................................................................

66

  • 5.3.4. Renaming event properties

.....................................................................................

66

  • 5.3.5. Choosing event properties and events in a join

66

  • 5.3.6. Choosing event properties and events from a pattern

67

  • 5.3.7. Selecting insert and remove stream events

...............................................................

68

  • 5.3.8. Qualifying property names and stream names

69

  • 5.3.9. Select Distinct

69

5.3.10. Transposing an Expression Result to a Stream

70

  • 5.4. Specifying Event Streams: the From Clause

70

  • 5.4.1. Filter-based Event Streams

.....................................................................................

70

5.4.1.1.

Specifying an Event Type

71

5.4.1.2.

Specifying Filter Criteria

71

5.4.1.3.

Filtering Ranges

.........................................................................................

72

5.4.1.4.

Filtering Sets of Values

72

5.4.1.5.

Filter Limitations

73

  • 5.4.2. Pattern-based Event Streams

73

  • 5.4.3. Specifying Views

..................................................................................................

73

  • 5.4.4. Multiple Data Window Views

74

  • 5.4.5. Using the Stream Name

76

  • 5.5. Specifying Search Conditions: the Where Clause

...............................................................

76

  • 5.6. Aggregates and grouping: the Group-by Clause and the Having Clause

77

  • 5.6.1. Using aggregate functions

......................................................................................

77

  • 5.6.2. Organizing statement results into groups: the Group-by clause

78

  • 5.6.3. Selecting groups of events: the Having clause

.........................................................

80

  • 5.6.4. How the stream filter, Where, Group By and Having clauses interact

81

  • 5.6.5. Comparing Keyed Segmented Context, the Group By clause and the std:groupwin view

 

81

  • 5.7. Stabilizing and Controlling Output: the Output Clause

82

  • 5.7.1. Output Clause Options

...........................................................................................

82

5.7.1.1.

Controlling Output Using an Expression

84

Esper - Event Stream and Complex Event Processing for Java

5.7.1.2. Suppressing Output With After

86

  • 5.7.2. Aggregation, Group By, Having and Output clause interaction

86

  • 5.7.3. Runtime Considerations

87

  • 5.8. Sorting Output: the Order By Clause

88

  • 5.9. Limiting Row Count: the Limit Clause

88

  • 5.10. Merging Streams and Continuous Insertion: the Insert Into Clause

89

  • 5.10.1. Transposing a Property To a Stream

90

  • 5.10.2. Merging Streams By Event Type

..........................................................................

91

  • 5.10.3. Merging Disparate Types of Events: Variant Streams

91

  • 5.10.4. Decorated Events

.................................................................................................

92

  • 5.10.5. Event as a Property

93

  • 5.10.6. Instantiating and Populating an Underlying Event Object

93

  • 5.10.7. Transposing an Expression Result

93

  • 5.11. Subqueries

93

  • 5.11.1. The 'exists' Keyword

95

  • 5.11.2. The 'in' and 'not in' Keywords

96

  • 5.11.3. The 'any' and 'some' Keywords

96

  • 5.11.4. The 'all' Keyword

97

  • 5.11.5. Multi-Column Selection

97

  • 5.11.6. Multi-Row Selection

98

  • 5.11.7. Hints Related to Subqueries

99

  • 5.12. Joining Event Streams

..................................................................................................

100

  • 5.12.1. Introducing Joins

...............................................................................................

100

  • 5.12.2. Inner (Default) Joins

..........................................................................................

101

  • 5.12.3. Outer, Left and Right Joins

102

  • 5.12.4. Unidirectional Joins

...........................................................................................

103

  • 5.12.5. Hints Related to Joins

104

  • 5.13. Accessing Relational Data via SQL

105

  • 5.13.1. Joining SQL Query Results

................................................................................

106

  • 5.13.2. SQL Query and the EPL Where Clause

107

  • 5.13.3. Outer Joins With SQL Queries

108

  • 5.13.4. Using Patterns to Request (Poll) Data

108

  • 5.13.5. Polling SQL Queries via Iterator

109

  • 5.13.6. JDBC Implementation Overview ........................................................................

109

  • 5.13.7. Oracle Drivers and No-Metadata Workaround

109

  • 5.13.8. SQL Input Parameter and Column Output Conversion

110

  • 5.13.9. SQL Row POJO Conversion

..............................................................................

110

  • 5.14. Accessing Non-Relational Data via Method Invocation

111

  • 5.14.1. Joining Method Invocation Results

.....................................................................

111

  • 5.14.2. Polling Method Invocation Results via Iterator

112

  • 5.14.3. Providing the Method

112

  • 5.14.4. Using a Map Return Type

113

  • 5.15. Creating and Using Named Windows

114

  • 5.15.1. Creating Named Windows: the Create Window clause

114

  • 5.15.1.1. Creation by Modelling after an Existing Type

115

  • 5.15.1.2. Creation By Defining Columns Names and Types

116

  • 5.15.1.3. Dropping or Removing Named Windows

117

  • 5.15.2. Inserting Into Named Windows

..........................................................................

117

  • 5.15.2.1. Named Windows Holding Decorated Events

118

  • 5.15.2.2. Named Windows Holding Events As Property

118

  • 5.15.3. Selecting From Named Windows

........................................................................

118

  • 5.15.4. Triggered Select on Named Windows: the On Select clause

119

Esper - Event Stream and Complex Event Processing for Java

  • 5.15.5. Triggered Playback from Named Windows: the On Insert clause

121

  • 5.15.6. Populating a Named Window from an Existing Named Window

122

  • 5.15.7. Updating Named Windows: the On Update clause

...............................................

122

  • 5.15.8. Deleting From Named Windows: the On Delete clause

124

5.15.8.1. Using Patterns in the On Delete Clause

125

  • 5.15.9. Triggered Upsert using the On-Merge Clause

125

  • 5.15.10. Explicitly Indexing Named Windows

................................................................

128

  • 5.15.11. Versioning and Revision Event Type Use with Named Windows

130

  • 5.16. Declaring an Event Type: Create Schema

131

  • 5.16.1. Declare an Event Type by Providing Names and Types

131

  • 5.16.2. Declare an Event Type by Providing a Class Name

133

  • 5.16.3. Declare a Variant Stream

133

  • 5.17. Splitting and Duplicating Streams

134

  • 5.18. Variables and Constants

135

  • 5.18.1. Creating Variables: the Create Variable clause

136

  • 5.18.2. Setting Variable Values: the On Set clause

137

  • 5.18.3. Using Variables

138

  • 5.18.4. Object-Type Variables

.......................................................................................

138

  • 5.18.5. Class and Event-Type Variables

139

  • 5.19. Contained-Event Selection

139

  • 5.19.1. Select Clause in a Contained-Event Selection

141

  • 5.19.2. Where Clause in a Contained-Event Selection

143

  • 5.19.3. Contained-Event Selection and Joins

143

  • 5.19.4. Sentence and Word Example

144

  • 5.19.5. More Examples

145

  • 5.20. Updating an Insert Stream: the Update IStream Clause

146

  • 5.20.1. Immutability and Updates

148

  • 5.21. Controlling Event Delivery : The For Clause

148

6. EPL Reference: Patterns

.........................................................................................................

150

  • 6.1. Event Pattern Overview

150

  • 6.2. How to use Patterns

........................................................................................................

150

  • 6.2.1. .....................................................................................................

Pattern Syntax

151

Patterns in EPL

  • 6.2.2. ...................................................................................................

151

  • 6.2.3. Subscribing to Pattern Events

152

  • 6.2.4. Pulling Data from Patterns

152

  • 6.2.5. Pattern Error Reporting

153

  • 6.3. Operator Precedence

.......................................................................................................

153

  • 6.4. Filter Expressions In Patterns

154

  • 6.4.1. Controlling Event Consumption

155

  • 6.5. Pattern Operators

156

  • 6.5.1. Every

156

6.5.1.1.

Limiting Subexpression Lifetime

158

6.5.1.2.

Every Operator Example

159

6.5.1.3.

Sensor Example

159

Every-Distinct

  • 6.5.2. .....................................................................................................

160

  • 6.5.3. ................................................................................................................

Repeat

161

Repeat-Until

  • 6.5.4. .......................................................................................................

162

6.5.4.1.

Unbound Repeat

.......................................................................................

163

6.5.4.2.

Bound Repeat Overview

163

6.5.4.3.

Bound Repeat - Open Ended Range

164

6.5.4.4.

Bound Repeat - High Endpoint Range

164

6.5.4.5.

Bound Repeat - Bounded Range

164

Esper - Event Stream and Complex Event Processing for Java

 

6.5.4.6.

164

 

6.5.5.

And

165

6.5.6.

Or

166

6.5.7.

Not

166

6.5.8.

Followed-by

167

 

6.5.8.1.

Limiting Sub-Expression Count

.................................................................

167

6.5.8.2.

Limiting Engine-wide Sub-Expression Count

168

 

6.5.9.

Pattern Guards

.....................................................................................................

168

 

6.5.9.1.

The timer:within Pattern Guard

169

6.5.9.2.

The timer:withinmax Pattern Guard

170

6.5.9.3.

The while Pattern Guard

............................................................................

170

6.5.9.4.

Guard Time Interval Expressions

171

6.5.9.5.

171

6.6.

Pattern Atoms

 

171

6.6.1.

Filter Atoms

171

6.6.2.

Time-based Observer Atoms

172

 

6.6.2.1.

timer:interval

172

6.6.2.2.

timer:at

172

  • 7. EPL Reference: Match Recognize

175

7.1.

Overview

 

175

7.2.

Comparison of Match Recognize and EPL Patterns

175

7.3.

Syntax

...........................................................................................................................

176

7.3.1.

Syntax Example

177

7.4.

Pattern and Pattern Operators

178

7.4.1.

Operator Precedence

178

7.4.2.

Concatenation .....................................................................................................

178

7.4.3.

Alternation ..........................................................................................................

179

7.4.4.

Quantifiers Overview

179

7.4.5.

Variables Can be Singleton or Group

....................................................................

180

 

7.4.5.1.

Additional Aggregation Functions

180

 

7.4.6.

Eliminating Duplicate Matches

181

7.4.7.

Greedy Or Reluctant

............................................................................................

181

7.4.8.

Quantifier - One Or More (+ and +?)

182

7.4.9.

Quantifier - Zero Or More (* and *?)

183

7.4.10. Quantifier - Zero Or One (? and ??)

183

7.5.

Define Clause

 

184

7.5.1.

The Prev Operator

184

7.6.

Measure Clause

185

7.7.

Datawindow-Bound

185

7.8.

Interval

186

7.9.

Use with Different Event Types

187

7.10. Limitations

 

188

  • 8. EPL Reference: Operators

189

8.1.

Arithmetic Operators

189

8.2.

Logical And Comparison Operators

189

8.2.1.

Null-Value Comparison Operators

189

8.3.

Concatenation Operators

190

8.4.

Binary Operators

............................................................................................................

190

8.5.

Array Definition Operator

191

8.6.

Dot Operator

..................................................................................................................

191

8.6.1.

Duck Typing

192

8.7.

The 'in' Keyword

192

Esper - Event Stream and Complex Event Processing for Java

  • 8.7.1. 'in' for Range Selection

193

  • 8.8. The 'between' Keyword

194

  • 8.9. The 'like' Keyword

.........................................................................................................

195

  • 8.10. The 'regexp' Keyword

195

  • 8.11. The 'any' and 'some' Keywords

196

  • 8.12. The 'all' Keyword

.........................................................................................................

196

  • 8.13. The 'new' Keyword

197

9. EPL Reference: Functions

.......................................................................................................

199

  • 9.1. Single-row Function Reference

.......................................................................................

199

  • 9.1.1. The Case Control Flow Function

201

  • 9.1.2. The Cast Function

...............................................................................................

201

  • 9.1.3. The Coalesce Function

202

  • 9.1.4. The Current_Timestamp Function

202

  • 9.1.5. The Exists Function

.............................................................................................

202

  • 9.1.6. The Instance-Of Function

202

  • 9.1.7. The Min and Max Functions

203

  • 9.1.8. The Previous Function

203

  • 9.1.8.1. Restrictions

205

  • 9.1.8.2. Comparison to the prior Function

205

  • 9.1.9. The Previous-Tail Function

205

  • 9.1.9.1. Restrictions

206

  • 9.1.10. The Previous-Window Function

207

Restrictions

  • 9.1.10.1. ............................................................................................

207

  • 9.1.11. The Previous-Count Function

207

Restrictions

  • 9.1.11.1. ............................................................................................

208

  • 9.1.12. The Prior Function

208

  • 9.1.13. The Type-Of Function

209

  • 9.2. Aggregate Functions

.......................................................................................................

210

  • 9.2.1. SQL-Standard Functions

......................................................................................

210

  • 9.2.2. Data Window Aggregation Functions

212

  • 9.2.2.1. First Aggregation Function

212

  • 9.2.2.2. Last Aggregation Function

........................................................................

213

  • 9.2.2.3. Window Aggregation Function

214

  • 9.2.3. Additional Aggregation Functions

214

  • 9.3. User-Defined Functions

217

  • 9.4. Select-Clause transpose Function

219

  • 9.4.1. Transpose with Insert-Into

219

10. EPL Reference: Enumeration Methods

221

Overview

  • 10.1. .....................................................................................................................

221

Example Events

  • 10.2. ...........................................................................................................

225

  • 10.3. ..................................................................................................................

How to Use

226

  • 10.3.1. Syntax

226

  • 10.3.2. Introductory Examples

.......................................................................................

227

  • 10.3.3. Input, Output and Limitations

227

  • 10.4. Inputs

..........................................................................................................................

228

Subquery Results

  • 10.4.1. ...............................................................................................

228

Named Window

  • 10.4.2. ................................................................................................

229

  • 10.4.3. ..................................................................................................

Event Property

230

  • 10.4.4. Data Window Aggregation

230

  • 10.4.5. prev, prevwindow and prevtail Single-Row Functions as Input

231

  • 10.4.6. Single-Row Function or UDF

231

  • 10.4.7. Declared Expression

232

Esper - Event Stream and Complex Event Processing for Java

10.5.

Example

......................................................................................................................

232

10.6.

Reference

....................................................................................................................

233

10.6.1.

Aggregate

.........................................................................................................

233

10.6.2.

AllOf

................................................................................................................

234

10.6.3.

AnyOf

..............................................................................................................

234

10.6.4.

Average

............................................................................................................

234

10.6.5.

CountOf

............................................................................................................

235

10.6.6.

Except

10.6.7.

FirstOf

..............................................................................................................

235

..............................................................................................................

236

10.6.8.

GroupBy

...........................................................................................................

236

10.6.9.

Intersect

............................................................................................................

237

10.6.10.

LastOf

.............................................................................................................

237

  • 10.6.11. LeastFrequent

..................................................................................................

237

10.6.12.

Max

................................................................................................................

238

10.6.13.

MaxBy

............................................................................................................

238

10.6.14.

Min

.................................................................................................................

239

10.6.15.

MinBy

............................................................................................................

239

  • 10.6.16. MostFrequent

..................................................................................................

240

  • 10.6.17. OrderBy and OrderByDesc

...............................................................................

240

10.6.18.

Reverse

...........................................................................................................

241

  • 10.6.19. SelectFrom

......................................................................................................

241

  • 10.6.20. SequenceEqual

................................................................................................

241

10.6.21.

SumOf

............................................................................................................

242

10.6.22.

Take

...............................................................................................................

242

10.6.23.

TakeLast

.........................................................................................................

242

  • 10.6.24. TakeWhile

......................................................................................................

243

  • 10.6.25. TakeWhileLast

................................................................................................

243

10.6.26.

ToMap

............................................................................................................

244

10.6.27.

Union

..............................................................................................................

244

10.6.28.

Where

.............................................................................................................

244

11. EPL Reference: Date-Time Methods

.....................................................................................

246

11.1.

Overview

.....................................................................................................................

246

11.2.

How to Use

..................................................................................................................

249

11.2.1.

Syntax

..............................................................................................................

249

  • 11.3. Calendar and Formatting Reference

...............................................................................

250

11.3.1.

Between

............................................................................................................

250

11.3.2.

Format

..............................................................................................................

251

  • 11.3.3. Get (By Field)

...................................................................................................

251

  • 11.3.4. Get (By Name)

..................................................................................................

252

  • 11.3.5. Minus ...............................................................................................................

252

  • 11.3.6. Plus ..................................................................................................................

252

  • 11.3.7. RoundCeiling

....................................................................................................

252

  • 11.3.8. RoundFloor .......................................................................................................

253

  • 11.3.9. RoundHalf

........................................................................................................

253

  • 11.3.10. Set (By Field)

..................................................................................................

253

11.3.11.

WithDate

........................................................................................................

254

11.3.12.

WithMax

.........................................................................................................

254

11.3.13.

WithMin

.........................................................................................................

254

  • 11.3.14. WithTime

........................................................................................................

254

  • 11.3.15. ToCalendar

.....................................................................................................

255

  • 11.3.16. ToDate ............................................................................................................

255

  • 11.3.17. ToMillisec

.......................................................................................................

255

Esper - Event Stream and Complex Event Processing for Java

  • 11.4. Interval Algebra Reference

 

255

11.4.1.

After

257

11.4.2.

Before

257

11.4.3.

Coincides

258

11.4.4.

During

259

11.4.5.

Finishes

260

11.4.6.

Finished By

260

11.4.7.

Includes

261

11.4.8.

Meets

262

11.4.9.

Met By

262

11.4.10.

Overlaps ..........................................................................................................

263

11.4.11.

Overlapped By

263

11.4.12.

Starts

264

11.4.13.

Started By

265

  • 12. EPL Reference: Views

 

266

  • 12.1. Window views

.............................................................................................................

268

  • 12.1.1. Length window (win:length)

..............................................................................

269

  • 12.1.2. Length batch window (win:length_batch)

269

  • 12.1.3. Time window (win:time)

....................................................................................

269

  • 12.1.4. Externally-timed window (win:ext_timed)

270

  • 12.1.5. Time batch window (win:time_batch)

270

  • 12.1.6. Time-Length combination batch window (win:time_length_batch)

271

  • 12.1.7. Time-Accumulating window (win:time_accum)

272

  • 12.1.8. Keep-All window (win:keepall)

 

273

  • 12.1.9. First Length (win:firstlength)

273

  • 12.1.10. First Time (win:firsttime)

273

  • 12.1.11. Expiry Expression (win:expr)

...........................................................................

274

  • 12.1.12. Expiry Expression Batch (win:expr_batch)

275

  • 12.2. Standard view set

.........................................................................................................

277

  • 12.2.1. Unique (std:unique)

...........................................................................................

277

  • 12.2.2. Grouped Data Window (std:groupwin)

 

277

  • 12.2.3. Size (std:size)

....................................................................................................

279

  • 12.2.4. Last Event (std:lastevent)

 

280

  • 12.2.5. First Event (std:firstevent)

..................................................................................

281

  • 12.2.6. First Unique (std:firstunique)

281

  • 12.3. Statistics views

281

  • 12.3.1. Univariate statistics (stat:uni)

281

  • 12.3.2. Regression (stat:linest)

282

  • 12.3.3. Correlation (stat:correl)

284

  • 12.3.4. Weighted average (stat:weighted_avg)

284

  • 12.4. Extension View Set

285

  • 12.4.1. Sorted Window View (ext:sort)

285

  • 12.4.2. Time-Order View (ext:time_order)

286

  • 13. API Reference

.......................................................................................................................

288

  • 13.1. API Overview

 

288

  • 13.2. The Service Provider Interface

288

  • 13.3. The Administrative Interface

289

  • 13.3.1. Creating Statements

...........................................................................................

289

  • 13.3.2. Receiving Statement Results

 

290

  • 13.3.3. Setting a Subscriber Object

................................................................................

291

 
  • 13.3.3.1. Row-By-Row Delivery

292

  • 13.3.3.2. Multi-Row Delivery

294

Esper - Event Stream and Complex Event Processing for Java

13.3.3.3.

No-Parameter Update Method

295

13.3.4.

Adding Listeners

295

13.3.4.1.

Subscription Snapshot and Atomic Delivery

295

13.3.5.

Using Iterators

...................................................................................................

296

13.3.6.

Managing Statements

297

13.3.7.

Runtime Configuration

297

  • 13.4. The Runtime Interface

298

13.4.1.

Event Sender

.....................................................................................................

298

13.4.2.

Receiving Unmatched Events

299

13.4.3.

On-Demand Snapshot Query Execution

299

13.4.3.1.

On-Demand Query API

300

  • 13.5. Event and Event Type

...................................................................................................

300

13.5.1.

Event Type Metadata

301

13.5.2.

Event Object

.....................................................................................................

301

13.5.3.

Query Example

302

13.5.4.

Pattern Example

303

  • 13.6. Engine Threading and Concurrency

304

13.6.1.

Advanced Threading

..........................................................................................

305

13.6.1.1.

Inbound Threading

..................................................................................

306

13.6.1.2.

Outbound Threading

...............................................................................

307

13.6.1.3.

Timer Execution Threading

307

13.6.1.4.

Route Execution Threading

.....................................................................

307

13.6.1.5.

Threading Service Provider Interface

307

13.6.2.

Processing Order

...............................................................................................

307

13.6.2.1.

Competing Statements

.............................................................................

308

13.6.2.2.

Competing Events in a Work Queue

308

  • 13.7. Controlling Time-Keeping

............................................................................................

308

13.7.1.

Controlling Time Using Time Span Events

310

13.7.2.

Additional Time-Related APIs

311

Time Resolution

  • 13.8. ...........................................................................................................

311

Service Isolation

  • 13.9. ...........................................................................................................

311

13.9.1.

Overview

311

13.9.2.

Example: Suspending a Statement

313

13.9.3.

Example: Catching up a Statement from Historical Data

313

13.9.4.

Isolation for Insert-Into

314

13.9.5.

Isolation for Named Windows

314

13.9.6.

Runtime Considerations

314

  • 13.10. Exception Handling

315

  • 13.11. Condition Handling

315

  • 13.12. Statement Object Model

..............................................................................................

316

  • 13.12.1. Building an Object Model

316

  • 13.12.2. Building Expressions

.......................................................................................

317

  • 13.12.3. Building a Pattern Statement

318

  • 13.12.4. Building a Select Statement

..............................................................................

318

  • 13.12.5. Building a Create-Variable and On-Set Statement

319

  • 13.12.6. Building Create-Window, On-Delete and On-Select Statements

319

  • 13.13. Prepared Statement and Substitution Parameters

320

  • 13.14. Engine and Statement Metrics Reporting

321

Engine Metrics

  • 13.14.1. ................................................................................................

322

Statement Metrics

  • 13.14.2. ............................................................................................

322

  • 13.15. Event Rendering to XML and JSON

............................................................................

323

  • 13.15.1. JSON Event Rendering Conventions and Options

323

Esper - Event Stream and Complex Event Processing for Java

 

13.15.2.

XML Event Rendering Conventions and Options

324

13.16.

Plug-in Loader

...........................................................................................................

324

13.17.

Interrogating EPL Annotations

325

13.18.

Context Partition Selection

325

13.18.1.

Selectors

326

13.19.

Test and Assertion Support

.........................................................................................

327

13.19.1.

EPAssertionUtil Summary

327

13.19.2.

SupportUpdateListener Summary

328

13.19.3.

328

14. Configuration

330

  • 14.1. Programmatic Configuration

330

  • 14.2. Configuration via XML File

330

  • 14.3. XML Configuration File

331

  • 14.4. Configuration Items

331

 
  • 14.4.1. Events represented by Java Classes

.....................................................................

331

  • 14.4.1.1. Package of Java Event Classes

.................................................................

331

  • 14.4.1.2. Event type name to Java class mapping

....................................................

331

  • 14.4.1.3. Non-JavaBean and Legacy Java Event Classes

332

  • 14.4.1.4. Specifying Event Properties for Java Classes

333

  • 14.4.1.5. Turning off Code Generation

333

  • 14.4.1.6. Case Sensitivity and Property Names

334

  • 14.4.1.7. Factory and Copy Method

334

  • 14.4.1.8. Start and End Timestamp

........................................................................

335

  • 14.4.2. Events represented by java.util.Map

....................................................................

335

  • 14.4.3. Events represented by org.w3c.dom.Node

336

  • 14.4.3.1. Schema Resource

....................................................................................

337

  • 14.4.3.2. Explicit XPath Property

...........................................................................

337

  • 14.4.3.3. Absolute or Deep Property Resolution

338

  • 14.4.3.4. XPath Variable and Function Resolver

339

  • 14.4.3.5. Auto Fragment

........................................................................................

339

  • 14.4.3.6. XPath Property Expression

339

  • 14.4.3.7. Event Sender Setting

...............................................................................

339

  • 14.4.3.8. Start and End Timestamp

339

  • 14.4.4. Events represented by Plug-in Event Representations

340

  • 14.4.4.1. Enabling an Custom Event Representation

340

  • 14.4.4.2. Adding Plug-in Event Types

340

  • 14.4.4.3. Setting Resolution URIs

340

  • 14.4.5. Class and package imports

340

  • 14.4.6. Cache Settings for From-Clause Method Invocations

341

  • 14.4.7. Variables

341

  • 14.4.8. Relational Database Access

................................................................................

342

  • 14.4.8.1. Connections obtained via DataSource

.......................................................

342

  • 14.4.8.2. Connections obtained via DataSource Factory

343

  • 14.4.8.3. Connections obtained via DriverManager

344

  • 14.4.8.4. Connections-level settings

.......................................................................

344

  • 14.4.8.5. Connections lifecycle settings

345

Cache settings

  • 14.4.8.6. .........................................................................................

345

  • 14.4.8.7. Column Change Case

346

  • 14.4.8.8. SQL Types Mapping

346

Metadata Origin

  • 14.4.8.9. ......................................................................................

347

  • 14.4.9. Engine Settings related to Concurrency and Threading

.........................................

347

  • 14.4.9.1. Preserving the order of events delivered to listeners

347

Esper - Event Stream and Complex Event Processing for Java

  • 14.4.9.2. Preserving the order of events for insert-into streams

348

  • 14.4.9.3. Internal Timer Settings

348

  • 14.4.9.4. Advanced Threading Options

349

  • 14.4.9.5. Engine Fair Locking

349

  • 14.4.10. Engine Settings related to Event Metadata

350

  • 14.4.10.1. Java Class Property Names, Case Sensitivity and Accessor Style

350

  • 14.4.11. Engine Settings related to View Resources

........................................................

350

  • 14.4.11.1. Sharing View Resources between Statements

350

  • 14.4.11.2. Configuring Multi-Expiry Policy Defaults

351

  • 14.4.12. Engine Settings related to Logging

351

  • 14.4.12.1. Execution Path Debug Logging

351

  • 14.4.12.2. Query Plan Logging

352

JDBC Logging

  • 14.4.12.3. ......................................................................................

352

Audit Logging

  • 14.4.12.4. ......................................................................................

352

  • 14.4.13. Engine Settings related to Variables

..................................................................

353

  • 14.4.13.1. Variable Version Release Interval

353

  • 14.4.14. Engine Settings related to Patterns

....................................................................

353

  • 14.4.14.1. Followed-By Operator Maximum Subexpression Count

353

  • 14.4.15. Engine Settings related to Scripts

354

  • 14.4.16. Engine Settings related to Stream Selection

354

  • 14.4.16.1. Default Statement Stream Selection

354

  • 14.4.17. Engine Settings related to Time Source

355

  • 14.4.17.1. Default Time Source

355

  • 14.4.18. Engine Settings related to Metrics Reporting

.....................................................

355

  • 14.4.19. Engine Settings related to Language and Locale

357

  • 14.4.20. Engine Settings related to Expression Evaluation

357

  • 14.4.20.1. Integer Division and Division by Zero

357

  • 14.4.20.2. Subselect Evaluation Order

358

  • 14.4.20.3. User-Defined Function or Static Method Cache

358

  • 14.4.20.4. Extended Built-in Aggregation Functions

359

  • 14.4.20.5. Duck Typing

359

  • 14.4.21. Engine Settings related to Execution of Statements

359

  • 14.4.21.1. Prioritized Execution

359

  • 14.4.21.2. Context Partition Fair Locking

360

Disable Locking

  • 14.4.21.3. ....................................................................................

360

Threading Profile

  • 14.4.21.4. ..................................................................................

360

  • 14.4.22. Engine Settings related to Exception Handling

361

  • 14.4.23. Engine Settings related to Condition Handling

361

  • 14.4.24. Revision Event Type

362

  • 14.4.25. Variant Stream

363

  • 14.5. Type Names

.................................................................................................................

364

  • 14.6. Runtime Configuration

364

  • 14.7. Logging Configuration

365

365

15. Development Lifecycle

367

Authoring

  • 15.1. ....................................................................................................................

367

Testing

  • 15.2. ........................................................................................................................

367

  • 15.3. Debugging

...........................................................................................

367

15.3.1. @Audit Annotation

367

  • 15.4. Packaging and Deploying Overview

368

  • 15.5. EPL Modules

...............................................................................................................

369

  • 15.6. The Deployment Administrative Interface

370

Esper - Event Stream and Complex Event Processing for Java

15.6.1.

Reading Module Content

370

15.6.2.

Ordering Multiple Modules

371

15.6.3.

Deploying and Undeploying

371

15.6.4.

Listing Deployments

371

15.6.5.

State Transitioning a Module

371

15.6.6.

Best Practices

372

  • 15.7. J2EE Packaging and Deployment

..................................................................................

372

15.7.1.

J2EE Deployment Considerations

372

15.7.2.

Servlet Context Listener

373

  • 16. Integration and Extension

375

Overview

  • 16.1. .....................................................................................................................

375

  • 16.2. Virtual Data Window

375

16.2.1.

How to Use

.......................................................................................................

376

16.2.1.1.

Query Access Path

376

16.2.2.

Implementing the Factory

377

16.2.3.

Implementing the Virtual Data Window

378

16.2.4.

Implementing the Lookup

379

  • 16.3. Single-Row Function

....................................................................................................

380

16.3.1.

Implementing a Single-Row Function

.................................................................

381

16.3.2.

Configuring the Single-Row Function Name

381

16.3.3.

Value Cache

381

16.3.4.

Single-Row Functions in Filter Predicate Expressions

382

  • 16.4. Derived-value and Data Window View

382

16.4.1.

Implementing a View Factory

383

16.4.2.

Implementing a View

384

16.4.3.

View Contract

385

16.4.4.

Configuring View Namespace and Name

385

16.4.5.

Requirement for Data Window Views

386

16.4.6.

Requirement for Grouped Views

386

  • 16.5. Aggregation Function

...................................................................................................

386

16.5.1.

Implementing an Aggregation Function Factory

387

16.5.2.

Implementing an Aggregation Function

..............................................................

388

16.5.3.

Configuring the Aggregation Function Name

389

16.5.4.

Accepting Multiple Parameters

389

  • 16.6. Pattern Guard

...............................................................................................................

390

16.6.1.

Implementing a Guard Factory

390

16.6.2.

Implementing a Guard Class

...............................................................................

391

16.6.3.

Configuring Guard Namespace and Name

392

  • 16.7. Pattern Observer

392

16.7.1.

Implementing an Observer Factory

392

16.7.2.

Implementing an Observer Class

393

16.7.3.

Configuring Observer Namespace and Name

394

  • 16.8. Event Type And Event Object

394

16.8.1.

How It Works

395

16.8.2.

Steps

395

16.8.3.

URI-based Resolution

396

16.8.4.

Example

............................................................................................................

396

16.8.4.1.

Sample Event Type

396

16.8.4.2.

Sample Event Bean

398

16.8.4.3.

Sample Event Representation

398

16.8.4.4.

Sample Event Bean Factory

399

  • 17. Script Support

401

Esper - Event Stream and Complex Event Processing for Java

17.1.

Overview

401

17.2.

Syntax

401

17.3.

Examples

402

17.4.

Built-In EPL Script Attributes

402

17.5.

Performance Notes

403

17.6.

Additional Notes

403

  • 18. Examples, Tutorials, Case Studies

 

404

18.1.

Examples Overview

.....................................................................................................

404

18.2.

Running the Examples

406

18.3.

AutoID RFID Reader

406

18.4.

Runtime Configuration

407

18.5.

JMS Server Shell and Client

407

18.5.1.

Overview

407

18.5.2.

JMS Messages as Events

....................................................................................

408

18.5.3.

JMX for Remote Dynamic Statement Management

408

18.6.

Market Data Feed Monitor

408

18.6.1.

Input Events

408

18.6.2.

Computing Rates Per Feed

408

18.6.3.

Detecting a Fall-off

409

18.6.4.

Event generator

409

18.7.

OHLC Plug-in View

409

18.8.

Transaction 3-Event Challenge

410

18.8.1.

The Events

410

18.8.2.

Combined event

................................................................................................

410

18.8.3.

Real time summary data

410

18.8.4.

Find problems

411

18.8.5.

Event generator

411

18.9.

Self-Service Terminal

411

18.9.1.

Events

411

18.9.2.

Detecting Customer Check-in Issues

412

18.9.3.

Absence of Status Events

412

18.9.4.

Activity Summary Data

......................................................................................

412

18.9.5.

Sample Application for J2EE Application Server

412

18.9.5.1.

Running the Example

413

18.9.5.2.

Building the Example

..............................................................................

413

18.9.5.3.

Running the Event Simulator and Receiver

413

18.10.

Assets Moving Across Zones - An RFID Example

413

18.11.

StockTicker

414

18.12.

MatchMaker

414

18.13.

Named Window Query

415

18.14.

Sample Virtual Data Window

415

18.15.

Quality of Service

415

18.16.

Trivia Geeks Club

416

  • 19. Performance

417

19.1.

Performance Results

417

19.2.

Performance Tips

.........................................................................................................

417

19.2.1.

Understand how to tune your Java virtual machine

417

19.2.2.

Compare Esper to other solutions

417

19.2.3.

Input and Output Bottlenecks

418

19.2.4.

Advanced Theading

...........................................................................................

418

19.2.5.

Select the underlying event rather than individual fields

.......................................

418

19.2.6.

Prefer stream-level filtering over post-data-window filtering

419

Esper - Event Stream and Complex Event Processing for Java

  • 19.2.7. Reduce the use of arithmetic in expressions

419

  • 19.2.8. Remove Unneccessary Constructs

420

  • 19.2.9. End Pattern Sub-Expressions

..............................................................................

420

  • 19.2.10. Consider using EventPropertyGetter for fast access to event properties

420

  • 19.2.11. Consider casting the underlying event

421

  • 19.2.12. Turn off logging and audit

421

  • 19.2.13. Disable view sharing

........................................................................................

421

  • 19.2.14. Tune or disable delivery order guarantees

..........................................................

422

  • 19.2.15. Use a Subscriber Object to Receive Events

........................................................

422

  • 19.2.16. High-Arrival-Rate Streams and Single Statements

422

  • 19.2.17. Joins And Where-clause And Data Windows

423

  • 19.2.18. Patterns and Pattern Sub-Expression Instances

424

  • 19.2.19. Pattern Sub-Expression Instance Versus Data Window Use

425

  • 19.2.20. The Keep-All Data Window

.............................................................................

425

  • 19.2.21. Statement Design for Reduced Memory Consumption

425

  • 19.2.22. Performance, JVM, OS and hardware

426

  • 19.2.23. Consider using Hints

........................................................................................

426

  • 19.2.24. Optimizing Stream Filter Expressions

...............................................................

427

  • 19.2.25. Statement and Engine Metric Reporting

427

  • 19.2.26. Expression Evaluation Order and Early Exit

427

  • 19.2.27. Large Number of Threads

427

  • 19.2.28. Context Partition Related Information

...............................................................

428

  • 19.2.29. Prefer Constant Variables over Non-Constant Variables

428

  • 19.3. Using the performance kit

.............................................................................................

428

  • 19.3.1. How to use the performance kit

428

431

20. References

432

  • 20.1. Reference List

432

A. Output Reference and Samples

433

A.1. Introduction and Sample Data

433

434

A.2.1. No Output Rate Limiting

434

435

A.2.3. Output Rate Limiting - Last

 

436

A.2.4. Output Rate Limiting - First

437

 

438

A.3. Output for Fully-aggregated and Un-grouped Queries

439

A.3.1. No Output Rate Limiting

439

A.3.2. Output Rate Limiting - Default

440

A.3.3. Output Rate Limiting - Last

 

441

A.3.4. Output Rate Limiting - First

442

 

443

444

A.4.1. No Output Rate Limiting

444

445

A.4.3. Output Rate Limiting - Last

 

446

A.4.4. Output Rate Limiting - First

447

 

448

449

A.5.1. No Output Rate Limiting

449

450

A.5.3. Output Rate Limiting - All

451

Esper - Event Stream and Complex Event Processing for Java

A.5.4. Output Rate Limiting - Last

452

A.5.5. Output Rate Limiting - First

453

454

455

A.6.1. No Output Rate Limiting

455

A.6.2. Output Rate Limiting - Default

456

A.6.3. Output Rate Limiting - All

457

A.6.4. Output Rate Limiting - Last

458

A.6.5. Output Rate Limiting - First

459

460

B. Reserved Keywords

462

Index

466

Preface

Analyzing and reacting to information in real-time oftentimes requires the development of custom applications. Typically these applications must obtain the data to analyze, filter data, derive information and then indicate this information through some form of presentation or communication. Data may arrive with high frequency re- quiring high throughput processing. And applications may need to be flexible and react to changes in require- ments while the data is processed. Esper is an event stream processor that aims to enable a short development cycle from inception to production for these types of applications.

This document is a resource for software developers who develop event driven applications. It also contains in- formation that is useful for business analysts and system architects who are evaluating Esper.

It is assumed that the reader is familiar with the Java programming language.

This document is relevant in all phases of your software development project: from design to deployment and support.

If you are new to Esper, please follow these steps:

  • 1. Read the tutorials, case studies and solution patterns available on the Esper public web site at ht- tp://esper.codehaus.org

  • 2. Read Section 1.1, “Introduction to CEP and event stream analysis” if you are new to CEP and ESP (complex event processing, event stream processing)

  • 3. Read Chapter 2, Event Representations that explains the different ways of representing events to Esper

  • 4. Read Chapter 3, Processing Model to gain insight into EPL continuous query results

  • 5. Read Section 5.1, “EPL Introduction” for an introduction to event stream processing via EPL

  • 6. Read Section 6.1, “Event Pattern Overview” for an overview over event patterns

  • 7. Read Section 7.1, “Overview” for an overview over event patterns using the match recognize syntax.

  • 8. Then glance over the examples Section 18.1, “Examples Overview”

  • 9. Finally to test drive Esper performance, read Chapter 19, Performance

Chapter 1. Technology Overview

  • 1.1. Introduction to CEP and event stream analysis

The Esper engine has been developed to address the requirements of applications that analyze and react to events. Some typical examples of applications are:

Business process management and automation (process monitoring, BAM, reporting exceptions) Finance (algorithmic trading, fraud detection, risk management) Network and application monitoring (intrusion detection, SLA monitoring) Sensor network applications (RFID reading, scheduling and control of fabrication lines, air traffic)

What these applications have in common is the requirement to process events (or messages) in real-time or near real-time. This is sometimes referred to as complex event processing (CEP) and event stream analysis. Key considerations for these types of applications are throughput, latency and the complexity of the logic required.

High throughput - applications that process large volumes of messages (between 1,000 to 100k messages per second) Low latency - applications that react in real-time to conditions that occur (from a few milliseconds to a few seconds) • Complex computations - applications that detect patterns among events (event correlation), filter events, ag- gregate time or length windows of events, join event streams, trigger based on absence of events etc.

The Esper engine was designed to make it easier to build and extend CEP applications.

  • 1.2. CEP and relational databases

Relational databases and the standard query language (SQL) are designed for applications in which most data is fairly static and complex queries are less frequent. Also, most databases store all data on disks (except for in- memory databases) and are therefore optimized for disk access.

To retrieve data from a database an application must issue a query. If an application need the data 10 times per second it must fire the query 10 times per second. This does not scale well to hundreds or thousands of queries per second.

Database triggers can be used to fire in response to database update events. However database triggers tend to be slow and often cannot easily perform complex condition checking and implement logic to react.

In-memory databases may be better suited to CEP applications than traditional relational database as they gen- erally have good query performance. Yet they are not optimized to provide immediate, real-time query results required for CEP and event stream analysis.

  • 1.3. The Esper engine for CEP

The Esper engine works a bit like a database turned upside-down. Instead of storing the data and running quer- ies against stored data, the Esper engine allows applications to store queries and run the data through. Response from the Esper engine is real-time when conditions occur that match queries. The execution model is thus con- tinuous rather than only when a query is submitted.

Technology Overview

Esper provides two principal methods or mechanisms to process events: event patterns and event stream quer- ies.

Esper offers an event pattern language to specify expression-based event pattern matching. Underlying the pat- tern matching engine is a state machine implementation. This method of event processing matches expected se- quences of presence or absence of events or combinations of events. It includes time-based correlation of events.

Esper also offers event stream queries that address the event stream analysis requirements of CEP applications. Event stream queries provide the windows, aggregation, joining and analysis functions for use with streams of events. These queries are following the EPL syntax. EPL has been designed for similarity with the SQL query language but differs from SQL in its use of views rather than tables. Views represent the different operations needed to structure data in an event stream and to derive data from an event stream.

Esper provides these two methods as alternatives through the same API.

1.4. Required 3rd Party Libraries

Esper requires the following 3rd-party libraries at runtime:

ANTLR is the parser generator used for parsing and parse tree walking of the pattern and EPL syntax. Credit goes to Terence Parr at http://www.antlr.org. The ANTLR license is in the lib directory. The library is required for compile-time only. CGLIB is the code generation library for fast method calls. This open source software is under the Apache license. The Apache 2.0 license is in the lib directory. • Apache commons logging is a logging API that works together with LOG4J and other logging APIs. While Apache commons logging is required, the LOG4J log component is not required and can be replaced with SLF4J or other loggers. This open source software is under the Apache license. The Apache 2.0 license is in the lib directory.

Esper requires the following 3rd-party libraries at compile-time and for running the test suite:

JUnit is a great unit testing framework. Its license has also been placed in the lib directory. The library is re-

quired for build-time only. MySQL connector library is used for testing SQL integration and is required for running the automated test suite.

Chapter 2. Event Representations

This section outlines the different means to model and represent events. Esper uses the term event type to describe the type information available for an event representation. Your application may configure predefined event types at startup time or dynamically add event types at runtime via API or EPL syntax. See Section 14.4, “Configuration Items” for startup-time configuration and Section 13.3.7, “Runtime Configuration” for the runtime configuration API.

The EPL create schema syntax allows declaring an event type at runtime using EPL, see Section 5.16, “Declaring an Event Type: Create Schema”.

In Section 13.5, “Event and Event Type” we explain how an event type becomes visible in EPL statements and output events delivered by the engine.

2.1. Event Underlying Java Objects

An event is an immutable record of a past occurrence of an action or state change. Event properties capture the state information for an event.

In Esper, an event can be represented by any of the following underlying Java objects:

Table 2.1. Event Underlying Java Objects

Java Class

Description

java.lang.Object

Any Java POJO (plain-old java object) with getter methods following JavaBean conventions; Legacy Java classes not fol- lowing JavaBean conventions can also serve as events .

java.util.Map

Map events are key-values pairs and can also contain objects, further Map, and arrays thereof.

org.w3c.dom.Node

XML document object model (DOM).

org.apache.axiom.om.OMDocument or OM- Element

XML - Streaming API for XML (StAX) - Apache Axiom (provided by EsperIO package).

Application classes

Plug-in event representation via the extension API.

Esper provides multiple choices for representing an event. There is no absolute need for you to create new Java classes to represent an event.

Event representations have the following in common:

All event representations support nested, indexed and mapped properties (aka. property expression), as ex-

plained in more detail below. There is no limitation to the nesting level. All event representations provide event type metadata. This includes type metadata for nested properties.

• All event representations allow transposing the event itself and parts of all of its property graph into new

events. The term transposing refers to selecting the event itself or event properties that are themselves nestable property graphs, and then querying the event's properties or nested property graphs in further state- ments. The Apache Axiom event representation is an exception and does not currently allow transposing

Event Representations

event properties but does allow transposing the event itself. The Java object and Map representations allow supertypes.

The API behavior for all event representations is the same, with minor exceptions noted in this chapter. The benefits of multiple event representations are:

For applications that already have events in one of the supported representations, there is no need to trans- form events into a Java object before processing. Event representations are exchangeable, reducing or eliminating the need to change statements when the event representation changes. Event representations are interoperable, allowing all event representations to interoperate in same or differ- ent statements. • The choice makes its possible to consciously trade-off performance, ease-of-use, the ability to evolve and effort needed to import or externalize events and use existing event type metadata.

2.2. Event Properties

Event properties capture the state information for an event. Event properties be simple as well as indexed, mapped and nested event properties. The table below outlines the different types of properties and their syntax in an event expression. This syntax allows statements to query deep JavaBean objects graphs, XML structures and Map events.

Table 2.2. Types of Event Properties

Type

Description

 

Syntax

 

Example

 

Simple

A property that has a single value that

   

may be retrieved.

 

name

   

sensorId

   

Indexed

An indexed property stores an ordered

   

collection of objects (all of the same

 

name[index]