Esper ReferenceVersion 4.8.0by Esper Team and EsperTech Inc. [http://esper.codehaus.org]

Copyright 2006 - 2012 by EsperTech Inc.

Preface ........................................................................................................................... xix 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 .................................................................................. 2 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 ................................................................................... 5 2.2.2. Expression as Key or Index Value ............................................................ 6 2.3. Dynamic Event Properties ................................................................................... 7 2.4. Fragment and Fragment Type ............................................................................. 9 2.5. Plain-Old Java Object Events .............................................................................. 9 2.5.1. Java Object Event Properties .................................................................. 10 2.5.2. Property Names ..................................................................................... 11 2.5.3. Constants and Enumeration .................................................................... 12 2.5.4. Parameterized Types .............................................................................. 2.5.5. Setter Methods for Indexed and Mapped Properties .................................. 2.5.6. Known Limitations .................................................................................. 2.6. java.util.Map Events .......................................................................................... 2.6.1. Overview ............................................................................................... 2.6.2. Map Properties ...................................................................................... 2.6.3. Map Supertypes ..................................................................................... 2.6.4. Advanced Map Property Types ............................................................... 2.7. Object-array (Object[]) Events ............................................................................ 2.7.1. Overview ............................................................................................... 2.7.2. Object-Array Properties .......................................................................... 2.7.3. Object-Array Supertype .......................................................................... 2.7.4. Advanced Object-Array Property Types ................................................... 2.8. org.w3c.dom.Node XML Events ......................................................................... 2.8.1. Schema-Provided XML Events ................................................................ 2.8.2. No-Schema-Provided XML Events ........................................................... 2.8.3. Explicitly-Configured Properties ............................................................... 2.9. Additional Event Representations ....................................................................... 2.10. Updating, Merging and Versioning Events ........................................................ 2.11. Coarse-Grained Events ................................................................................... 2.12. Event Objects Instantiated and Populated by Insert Into ..................................... 2.13. Comparing Event Representations ................................................................... 3. Processing Model ...................................................................................................... 3.1. Introduction ....................................................................................................... 3.2. Insert Stream .................................................................................................... 3.3. Insert and Remove Stream ................................................................................ 3.4. Filters and Where-clauses ................................................................................. 13 13 14 14 14 15 16 17 19 19 20 21 22 24 26 31 31 33 34 34 35 36 39 39 39 40 42

iii

Esper Reference

3.5. Time Windows .................................................................................................. 44 3.5.1. Time Window ......................................................................................... 44 3.5.2. Time Batch ............................................................................................ 3.6. Batch Windows ................................................................................................. 3.7. Aggregation and Grouping ................................................................................. 3.7.1. Insert and Remove Stream ..................................................................... 3.7.2. Output for Aggregation and Group-By ...................................................... 3.8. Event Visibility and Current Time ....................................................................... 4. Context and Context Partitions ................................................................................. 4.1. Introduction ....................................................................................................... 4.2. Context Declaration ........................................................................................... 4.2.1. Context-Provided Properties ................................................................... 4.2.2. Keyed Segmented Context ..................................................................... 4.2.3. Hash Segmented Context ....................................................................... 4.2.4. Category Segmented Context ................................................................. 4.2.5. Non-Overlapping Context ........................................................................ 4.2.6. Overlapping Context ............................................................................... 4.2.7. Context Conditions ................................................................................. 4.3. Context Nesting ................................................................................................ 4.3.1. Built-In Nested Context Properties ........................................................... 4.4. Partitioning Without Context Declaration ............................................................. 4.5. Output When Context Partition Ends .................................................................. 4.6. Context and Named Window ............................................................................. 4.7. Operations on Specific Context Partitions ........................................................... 5. EPL Reference: Clauses ............................................................................................ 5.1. EPL Introduction ............................................................................................... 5.2. EPL Syntax ...................................................................................................... 5.2.1. Specifying Time Periods ......................................................................... 5.2.2. Using Comments .................................................................................... 5.2.3. Reserved Keywords ............................................................................... 5.2.4. Escaping Strings .................................................................................... 5.2.5. Data Types ............................................................................................ 5.2.6. Annotation ............................................................................................. 5.2.7. Expression Declaration ........................................................................... 5.2.8. Script Declaration ................................................................................... 5.2.9. Referring to a Context ............................................................................ 5.3. Choosing Event Properties And Events: the Select Clause .................................. 5.3.1. Choosing all event properties: select * ..................................................... 5.3.2. Choosing specific event properties .......................................................... 5.3.3. Expressions ........................................................................................... 5.3.4. Renaming event properties ..................................................................... 5.3.5. Choosing event properties and events in a join ........................................ 5.3.6. Choosing event properties and events from a pattern ............................... 5.3.7. Selecting insert and remove stream events .............................................. 45 46 47 47 48 50 51 51 52 53 53 57 61 62 64 67 70 71 72 73 75 76 77 77 78 79 79 80 81 81 84 89 91 91 91 92 93 93 94 94 95 96

iv

5.3.8. Qualifying property names and stream names .......................................... 97 5.3.9. Select Distinct ........................................................................................ 98 5.3.10. Transposing an Expression Result to a Stream ...................................... 98 5.4. Specifying Event Streams: the From Clause ....................................................... 98 5.4.1. Filter-based Event Streams ..................................................................... 99 5.4.2. Pattern-based Event Streams ................................................................ 103 5.4.3. Specifying Views .................................................................................. 103 5.4.4. Multiple Data Window Views ................................................................. 104 5.4.5. Using the Stream Name ....................................................................... 106 5.5. Specifying Search Conditions: the Where Clause .............................................. 107 5.6. Aggregates and grouping: the Group-by Clause and the Having Clause .............. 108 5.6.1. Using aggregate functions ..................................................................... 108 5.6.2. Organizing statement results into groups: the Group-by clause ................ 109 5.6.3. Selecting groups of events: the Having clause ........................................ 112 5.6.4. How the stream filter, Where, Group By and Having clauses interact ........ 113 5.6.5. Comparing Keyed Segmented Context, the Group By clause and the std:groupwin view .......................................................................................... 114 5.7. Stabilizing and Controlling Output: the Output Clause ........................................ 5.7.1. Output Clause Options ......................................................................... 5.7.2. Aggregation, Group By, Having and Output clause interaction .................. 5.7.3. Runtime Considerations ........................................................................ 5.8. Sorting Output: the Order By Clause ................................................................ 5.9. Limiting Row Count: the Limit Clause ............................................................... 5.10. Merging Streams and Continuous Insertion: the Insert Into Clause .................... 5.10.1. Transposing a Property To a Stream ................................................... 5.10.2. Merging Streams By Event Type ......................................................... 5.10.3. Merging Disparate Types of Events: Variant Streams ............................ 5.10.4. Decorated Events ............................................................................... 5.10.5. Event as a Property ............................................................................ 5.10.6. Instantiating and Populating an Underlying Event Object ....................... 5.10.7. Transposing an Expression Result ....................................................... 5.11. Subqueries .................................................................................................... 5.11.1. The 'exists' Keyword ........................................................................... 5.11.2. The 'in' and 'not in' Keywords .............................................................. 5.11.3. The 'any' and 'some' Keywords ........................................................... 5.11.4. The 'all' Keyword ................................................................................ 5.11.5. Multi-Column Selection ....................................................................... 5.11.6. Multi-Row Selection ............................................................................ 5.11.7. Hints Related to Subqueries ................................................................ 5.12. Joining Event Streams ................................................................................... 5.12.1. Introducing Joins ................................................................................ 5.12.2. Inner (Default) Joins ........................................................................... 5.12.3. Outer, Left and Right Joins ................................................................. 5.12.4. Unidirectional Joins ............................................................................. 115 115 120 122 122 123 124 126 127 127 129 129 130 130 130 133 134 134 135 136 137 138 139 139 141 142 144

v

Esper Reference

5.12.5. Hints Related to Joins ......................................................................... 145 5.13. Accessing Relational Data via SQL ................................................................ 146 5.13.1. Joining SQL Query Results ................................................................. 5.13.2. SQL Query and the EPL Where Clause ............................................... 5.13.3. Outer Joins With SQL Queries ............................................................ 5.13.4. Using Patterns to Request (Poll) Data .................................................. 5.13.5. Polling SQL Queries via Iterator .......................................................... 5.13.6. JDBC Implementation Overview .......................................................... 5.13.7. Oracle Drivers and No-Metadata Workaround ....................................... 5.13.8. SQL Input Parameter and Column Output Conversion ........................... 5.13.9. SQL Row POJO Conversion ............................................................... 5.14. Accessing Non-Relational Data via Method Invocation ..................................... 5.14.1. Joining Method Invocation Results ....................................................... 5.14.2. Polling Method Invocation Results via Iterator ....................................... 5.14.3. Providing the Method .......................................................................... 5.14.4. Using a Map Return Type ................................................................... 5.15. Creating and Using Named Windows ............................................................. 5.15.1. Creating Named Windows: the Create Window clause .......................... 5.15.2. Inserting Into Named Windows ............................................................ 5.15.3. Selecting From Named Windows ......................................................... 5.15.4. Triggered Select on Named Windows: the On Select clause .................. 5.15.5. Triggered Select+Delete on Named Windows: the On Select Delete clause ........................................................................................................... 5.15.6. Populating a Named Window from an Existing Named Window .............. 5.15.7. Updating Named Windows: the On Update clause ................................ 5.15.8. Deleting From Named Windows: the On Delete clause .......................... 5.15.9. Triggered Upsert using the On-Merge Clause ....................................... 5.15.10. Explicitly Indexing Named Windows ................................................... 5.15.11. Versioning and Revision Event Type Use with Named Windows ........... 5.16. Declaring an Event Type: Create Schema ...................................................... 5.16.1. Declare an Event Type by Providing Names and Types ......................... 5.16.2. Declare an Event Type by Providing a Class Name .............................. 5.16.3. Declare a Variant Stream .................................................................... 5.17. Splitting and Duplicating Streams ................................................................... 5.18. Variables and Constants ................................................................................ 5.18.1. Creating Variables: the Create Variable clause ..................................... 5.18.2. Setting Variable Values: the On Set clause .......................................... 5.18.3. Using Variables .................................................................................. 5.18.4. Object-Type Variables ......................................................................... 5.18.5. Class and Event-Type Variables .......................................................... 5.19. Declaring Global Expressions And Scripts: Create Expression .......................... 5.19.1. Declaring a Global Expression ............................................................ 5.19.2. Declaring a Global Script .................................................................... 5.20. Contained-Event Selection ............................................................................. 147 149 150 151 151 151 152 153 153 154 154 155 156 157 158 159 162 165 166 169 169 170 172 175 179 181 183 183 187 187 188 190 190 192 194 194 195 195 196 197 197

vi

5.20.1. Select Clause in a Contained-Event Selection ...................................... 200 5.20.2. Where Clause in a Contained-Event Selection ...................................... 203 5.20.3. Contained-Event Selection and Joins ................................................... 5.20.4. Sentence and Word Example .............................................................. 5.20.5. More Examples .................................................................................. 5.20.6. Contained-Event Limitations ................................................................ 5.21. Updating an Insert Stream: the Update IStream Clause ................................... 5.21.1. Immutability and Updates .................................................................... 5.22. Controlling Event Delivery : The For Clause .................................................... 6. EPL Reference: Patterns .......................................................................................... 6.1. Event Pattern Overview ................................................................................... 6.2. How to use Patterns ....................................................................................... 6.2.1. Pattern Syntax ..................................................................................... 6.2.2. Patterns in EPL .................................................................................... 6.2.3. Subscribing to Pattern Events ............................................................... 6.2.4. Pulling Data from Patterns .................................................................... 6.2.5. Pattern Error Reporting ......................................................................... 6.3. Operator Precedence ...................................................................................... 6.4. Filter Expressions In Patterns .......................................................................... 6.4.1. Controlling Event Consumption ............................................................. 6.5. Pattern Operators ........................................................................................... 6.5.1. Every ................................................................................................... 6.5.2. Every-Distinct ....................................................................................... 6.5.3. Repeat ................................................................................................. 6.5.4. Repeat-Until ......................................................................................... 6.5.5. And ..................................................................................................... 6.5.6. Or ........................................................................................................ 6.5.7. Not ...................................................................................................... 6.5.8. Followed-by .......................................................................................... 6.5.9. Pattern Guards ..................................................................................... 6.6. Pattern Atoms ................................................................................................. 6.6.1. Filter Atoms ......................................................................................... 6.6.2. Time-based Observer Atoms ................................................................. 7. EPL Reference: Match Recognize ............................................................................ 7.1. Overview ........................................................................................................ 7.2. Comparison of Match Recognize and EPL Patterns ........................................... 7.3. Syntax ............................................................................................................ 7.3.1. Syntax Example ................................................................................... 7.4. Pattern and Pattern Operators ......................................................................... 7.4.1. Operator Precedence ............................................................................ 7.4.2. Concatenation ...................................................................................... 7.4.3. Alternation ............................................................................................ 7.4.4. Quantifiers Overview ............................................................................ 7.4.5. Variables Can be Singleton or Group .................................................... 203 205 206 207 207 209 210 213 213 214 214 215 215 216 217 217 218 220 221 221 226 228 230 233 235 235 236 238 242 243 243 247 247 247 248 249 251 251 251 252 252 253

vii

Esper Reference

7.4.6. Eliminating Duplicate Matches ............................................................... 253 7.4.7. Greedy Or Reluctant ............................................................................ 254 7.4.8. Quantifier - One Or More (+ and +?) ..................................................... 7.4.9. Quantifier - Zero Or More (* and *?) ...................................................... 7.4.10. Quantifier - Zero Or One (? and ??) .................................................... 7.5. Define Clause ................................................................................................. 7.5.1. The Prev Operator ............................................................................... 7.6. Measure Clause .............................................................................................. 7.7. Datawindow-Bound ......................................................................................... 7.8. Interval ........................................................................................................... 7.9. Use with Different Event Types ........................................................................ 7.10. Limitations .................................................................................................... 8. EPL Reference: Operators ....................................................................................... 8.1. Arithmetic Operators ....................................................................................... 8.2. Logical And Comparison Operators .................................................................. 8.2.1. Null-Value Comparison Operators ......................................................... 8.3. Concatenation Operators ................................................................................. 8.4. Binary Operators ............................................................................................. 8.5. Array Definition Operator ................................................................................. 8.6. Dot Operator ................................................................................................... 8.6.1. Duck Typing ......................................................................................... 8.7. The 'in' Keyword ............................................................................................. 8.7.1. 'in' for Range Selection ......................................................................... 8.8. The 'between' Keyword ................................................................................... 8.9. The 'like' Keyword ........................................................................................... 8.10. The 'regexp' Keyword .................................................................................... 8.11. The 'any' and 'some' Keywords ...................................................................... 8.12. The 'all' Keyword ........................................................................................... 8.13. The 'new' Keyword ........................................................................................ 9. EPL Reference: Functions ....................................................................................... 9.1. Single-row Function Reference ........................................................................ 9.1.1. The Case Control Flow Function ........................................................... 9.1.2. The Cast Function ................................................................................ 9.1.3. The Coalesce Function ......................................................................... 9.1.4. The Current_Timestamp Function .......................................................... 9.1.5. The Exists Function .............................................................................. 9.1.6. The Instance-Of Function ...................................................................... 9.1.7. The Istream Function ............................................................................ 9.1.8. The Min and Max Functions .................................................................. 9.1.9. The Previous Function .......................................................................... 9.1.10. The Previous-Tail Function .................................................................. 9.1.11. The Previous-Window Function ........................................................... 9.1.12. The Previous-Count Function .............................................................. 9.1.13. The Prior Function .............................................................................. 255 256 257 257 258 259 259 260 261 262 263 263 263 263 264 264 265 265 266 267 268 269 270 271 271 272 273 275 275 277 277 278 279 279 279 280 281 281 283 285 287 287

viii

9.1.14. The Type-Of Function ......................................................................... 288 9.2. Aggregate Functions ....................................................................................... 290 9.2.1. SQL-Standard Functions ....................................................................... 9.2.2. Data Window Aggregation Functions ..................................................... 9.2.3. Additional Aggregation Functions ........................................................... 9.3. User-Defined Functions ................................................................................... 9.4. Select-Clause transpose Function .................................................................... 9.4.1. Transpose with Insert-Into ..................................................................... 10. EPL Reference: Enumeration Methods .................................................................. 10.1. Overview ...................................................................................................... 10.2. Example Events ............................................................................................ 10.3. How to Use .................................................................................................. 10.3.1. Syntax ............................................................................................... 10.3.2. Introductory Examples ........................................................................ 10.3.3. Input, Output and Limitations ............................................................... 10.4. Inputs ........................................................................................................... 10.4.1. Subquery Results ............................................................................... 10.4.2. Named Window .................................................................................. 10.4.3. Event Property ................................................................................... 10.4.4. Data Window Aggregation ................................................................... 10.4.5. prev, prevwindow and prevtail Single-Row Functions as Input ................ 10.4.6. Single-Row Function or UDF ............................................................... 10.4.7. Declared Expression ........................................................................... 10.4.8. Variables ............................................................................................ 10.5. Example ....................................................................................................... 10.6. Reference ..................................................................................................... 10.6.1. Aggregate .......................................................................................... 10.6.2. AllOf .................................................................................................. 10.6.3. AnyOf ................................................................................................ 10.6.4. Average ............................................................................................. 10.6.5. CountOf ............................................................................................. 10.6.6. Except ............................................................................................... 10.6.7. FirstOf ................................................................................................ 10.6.8. GroupBy ............................................................................................ 10.6.9. Intersect ............................................................................................. 10.6.10. LastOf .............................................................................................. 10.6.11. LeastFrequent .................................................................................. 10.6.12. Max ................................................................................................. 10.6.13. MaxBy .............................................................................................. 10.6.14. Min .................................................................................................. 10.6.15. MinBy .............................................................................................. 10.6.16. MostFrequent ................................................................................... 10.6.17. OrderBy and OrderByDesc ................................................................ 10.6.18. Reverse ........................................................................................... 290 292 296 299 301 302 305 305 309 310 310 311 312 312 313 314 315 316 316 317 318 319 319 320 320 321 321 322 322 323 324 324 325 326 326 327 327 328 329 329 330 330

ix

Esper Reference

10.6.19. SelectFrom ....................................................................................... 331 10.6.20. SequenceEqual ................................................................................ 331 10.6.21. SumOf ............................................................................................. 10.6.22. Take ................................................................................................ 10.6.23. TakeLast .......................................................................................... 10.6.24. TakeWhile ........................................................................................ 10.6.25. TakeWhileLast .................................................................................. 10.6.26. ToMap ............................................................................................. 10.6.27. Union ............................................................................................... 10.6.28. Where .............................................................................................. 11. EPL Reference: Date-Time Methods ....................................................................... 11.1. Overview ...................................................................................................... 11.2. How to Use .................................................................................................. 11.2.1. Syntax ............................................................................................... 11.3. Calendar and Formatting Reference ............................................................... 11.3.1. Between ............................................................................................. 11.3.2. Format ............................................................................................... 11.3.3. Get (By Field) .................................................................................... 11.3.4. Get (By Name) ................................................................................... 11.3.5. Minus ................................................................................................. 11.3.6. Plus ................................................................................................... 11.3.7. RoundCeiling ...................................................................................... 11.3.8. RoundFloor ........................................................................................ 11.3.9. RoundHalf .......................................................................................... 11.3.10. Set (By Field) ................................................................................... 11.3.11. WithDate .......................................................................................... 11.3.12. WithMax ........................................................................................... 11.3.13. WithMin ............................................................................................ 11.3.14. WithTime .......................................................................................... 11.3.15. ToCalendar ...................................................................................... 11.3.16. ToDate ............................................................................................. 11.3.17. ToMillisec ......................................................................................... 11.4. Interval Algebra Reference ............................................................................ 11.4.1. Examples ........................................................................................... 11.4.2. Interval Algebra Parameters ................................................................ 11.4.3. Performance ....................................................................................... 11.4.4. Limitations .......................................................................................... 11.4.5. After .................................................................................................. 11.4.6. Before ................................................................................................ 11.4.7. Coincides ........................................................................................... 11.4.8. During ................................................................................................ 11.4.9. Finishes ............................................................................................. 11.4.10. Finished By ...................................................................................... 11.4.11. Includes ........................................................................................... 332 332 333 333 334 335 335 336 337 337 340 340 342 342 343 343 343 344 344 344 345 345 345 346 346 347 347 347 347 348 348 348 349 349 350 350 351 352 353 354 355 356

x

11.4.12. Meets ............................................................................................... 357 11.4.13. Met By ............................................................................................. 358 11.4.14. Overlaps .......................................................................................... 11.4.15. Overlapped By .................................................................................. 11.4.16. Starts ............................................................................................... 11.4.17. Started By ........................................................................................ 12. EPL Reference: Views ............................................................................................ 12.1. A Note on View Parameters .......................................................................... 12.2. Data Window Views ...................................................................................... 12.2.1. Length window (win:length) ................................................................. 12.2.2. Length batch window (win:length_batch) .............................................. 12.2.3. Time window (win:time) ....................................................................... 12.2.4. Externally-timed window (win:ext_timed) .............................................. 12.2.5. Time batch window (win:time_batch) .................................................... 12.2.6. Externally-timed batch window (win:ext_timed_batch) ............................ 12.2.7. Time-Length combination batch window (win:time_length_batch) ........... 12.2.8. Time-Accumulating window (win:time_accum) ...................................... 12.2.9. Keep-All window (win:keepall) ............................................................. 12.2.10. First Length (win:firstlength) ............................................................... 12.2.11. First Time (win:firsttime) .................................................................... 12.2.12. Expiry Expression (win:expr) ............................................................. 12.2.13. Expiry Expression Batch (win:expr_batch) .......................................... 12.3. Standard view set ......................................................................................... 12.3.1. Unique (std:unique) ............................................................................ 12.3.2. Grouped Data Window (std:groupwin) .................................................. 12.3.3. Size (std:size) .................................................................................... 12.3.4. Last Event (std:lastevent) .................................................................... 12.3.5. First Event (std:firstevent) ................................................................... 12.3.6. First Unique (std:firstunique) ................................................................ 12.4. Statistics views .............................................................................................. 12.4.1. Univariate statistics (stat:uni) ............................................................... 12.4.2. Regression (stat:linest) ........................................................................ 12.4.3. Correlation (stat:correl) ........................................................................ 12.4.4. Weighted average (stat:weighted_avg) ................................................. 12.5. Extension View Set ....................................................................................... 12.5.1. Sorted Window View (ext:sort) ............................................................ 12.5.2. Ranked Window View (ext:rank) .......................................................... 12.5.3. Time-Order View (ext:time_order) ........................................................ 13. EPL Reference: Data Flow ..................................................................................... 13.1. Introduction ................................................................................................... 13.2. Usage ........................................................................................................... 13.2.1. Overview ............................................................................................ 13.2.2. Syntax ............................................................................................... 13.3. Built-in Operators .......................................................................................... 358 359 360 361 363 366 367 367 367 368 368 369 371 372 373 374 374 374 375 377 379 379 380 382 384 384 385 385 385 386 388 388 390 390 391 392 395 395 395 395 397 402

xi

Esper Reference

13.3.1. BeaconSource .................................................................................... 402 13.3.2. EPStatementSource ............................................................................ 404 13.3.3. EventBusSink ..................................................................................... 13.3.4. EventBusSource ................................................................................. 13.3.5. Filter .................................................................................................. 13.3.6. LogSink .............................................................................................. 13.3.7. Select ................................................................................................ 13.4. API ............................................................................................................... 13.4.1. Declaring a Data Flow ........................................................................ 13.4.2. Instantiating a Data Flow .................................................................... 13.4.3. Executing a Data Flow ........................................................................ 13.4.4. Instantiation Options ........................................................................... 13.4.5. Start Captive ...................................................................................... 13.4.6. Data Flow Punctuation with Markers .................................................... 13.4.7. Exception Handling ............................................................................. 13.5. Examples ...................................................................................................... 13.6. Operator Implementation ............................................................................... 13.6.1. Sample Operator Acting as Source ...................................................... 13.6.2. Sample Tokenizer Operator ................................................................. 13.6.3. Sample Aggregator Operator ............................................................... 14. API Reference ........................................................................................................ 14.1. API Overview ................................................................................................ 14.2. The Service Provider Interface ....................................................................... 14.3. The Administrative Interface ........................................................................... 14.3.1. Creating Statements ........................................................................... 14.3.2. Receiving Statement Results ............................................................... 14.3.3. Setting a Subscriber Object ................................................................. 14.3.4. Adding Listeners ................................................................................. 14.3.5. Using Iterators .................................................................................... 14.3.6. Managing Statements ......................................................................... 14.3.7. Runtime Configuration ........................................................................ 14.4. The Runtime Interface ................................................................................... 14.4.1. Event Sender ..................................................................................... 14.4.2. Receiving Unmatched Events .............................................................. 14.4.3. On-Demand Snapshot Query Execution ............................................... 14.5. Event and Event Type ................................................................................... 14.5.1. Event Type Metadata .......................................................................... 14.5.2. Event Object ...................................................................................... 14.5.3. Query Example .................................................................................. 14.5.4. Pattern Example ................................................................................. 14.6. Engine Threading and Concurrency ............................................................... 14.6.1. Advanced Threading ........................................................................... 14.6.2. Processing Order ................................................................................ 14.7. Controlling Time-Keeping ............................................................................... 405 406 407 408 408 410 410 411 412 413 413 414 415 415 416 417 418 419 421 421 421 423 423 424 425 430 431 433 433 434 435 435 436 437 438 439 439 441 442 444 446 447

xii

14.7.1. Controlling Time Using Time Span Events ............................................ 449 14.7.2. Additional Time-Related APIs .............................................................. 450 14.8. Time Resolution ............................................................................................ 14.9. Service Isolation ............................................................................................ 14.9.1. Overview ............................................................................................ 14.9.2. Example: Suspending a Statement ...................................................... 14.9.3. Example: Catching up a Statement from Historical Data ........................ 14.9.4. Isolation for Insert-Into ........................................................................ 14.9.5. Isolation for Named Windows .............................................................. 14.9.6. Runtime Considerations ...................................................................... 14.10. Exception Handling ...................................................................................... 14.11. Condition Handling ...................................................................................... 14.12. Statement Object Model .............................................................................. 14.12.1. Building an Object Model .................................................................. 14.12.2. Building Expressions ......................................................................... 14.12.3. Building a Pattern Statement ............................................................. 14.12.4. Building a Select Statement .............................................................. 14.12.5. Building a Create-Variable and On-Set Statement ............................... 14.12.6. Building Create-Window, On-Delete and On-Select Statements ............ 14.13. Prepared Statement and Substitution Parameters .......................................... 14.14. Engine and Statement Metrics Reporting ...................................................... 14.14.1. Engine Metrics .................................................................................. 14.14.2. Statement Metrics ............................................................................. 14.15. Event Rendering to XML and JSON ............................................................. 14.15.1. JSON Event Rendering Conventions and Options ............................... 14.15.2. XML Event Rendering Conventions and Options ................................. 14.16. Plug-in Loader ............................................................................................. 14.17. Interrogating EPL Annotations ...................................................................... 14.18. Context Partition Selection ........................................................................... 14.18.1. Selectors .......................................................................................... 14.19. Test and Assertion Support .......................................................................... 14.19.1. EPAssertionUtil Summary ................................................................. 14.19.2. SupportUpdateListener Summary ....................................................... 14.19.3. Usage Example ................................................................................ 15. Configuration ......................................................................................................... 15.1. Programmatic Configuration ........................................................................... 15.2. Configuration via XML File ............................................................................. 15.3. XML Configuration File .................................................................................. 15.4. Configuration Items ....................................................................................... 15.4.1. Events represented by Java Classes ................................................... 15.4.2. Events represented by java.util.Map ..................................................... 15.4.3. Events represented by Object[] (Object-array) ...................................... 15.4.4. Events represented by org.w3c.dom.Node ........................................... 15.4.5. Events represented by Plug-in Event Representations ........................... 451 451 451 453 454 455 455 456 456 457 457 458 459 460 461 461 462 463 464 466 466 466 468 468 468 470 470 472 472 473 473 474 477 477 478 478 478 479 484 486 487 492

xiii

Esper Reference

15.4.6. Class and package imports ................................................................. 493 15.4.7. Cache Settings for From-Clause Method Invocations ............................ 494 15.4.8. Variables ............................................................................................ 15.4.9. Relational Database Access ................................................................ 15.4.10. Engine Settings related to Concurrency and Threading ........................ 15.4.11. Engine Settings related to Event Metadata ......................................... 15.4.12. Engine Settings related to View Resources ........................................ 15.4.13. Engine Settings related to Logging .................................................... 15.4.14. Engine Settings related to Variables ................................................... 15.4.15. Engine Settings related to Patterns .................................................... 15.4.16. Engine Settings related to Scripts ...................................................... 15.4.17. Engine Settings related to Stream Selection ....................................... 15.4.18. Engine Settings related to Time Source ............................................. 15.4.19. Engine Settings related to Metrics Reporting ...................................... 15.4.20. Engine Settings related to Language and Locale ................................. 15.4.21. Engine Settings related to Expression Evaluation ................................ 15.4.22. Engine Settings related to Execution of Statements ............................. 15.4.23. Engine Settings related to Exception Handling .................................... 15.4.24. Engine Settings related to Condition Handling ..................................... 15.4.25. Revision Event Type ......................................................................... 15.4.26. Variant Stream ................................................................................. 15.5. Type Names ................................................................................................. 15.6. Runtime Configuration ................................................................................... 15.7. Logging Configuration .................................................................................... 15.7.1. Log4j Logging Configuration ................................................................ 16. Development Lifecycle ........................................................................................... 16.1. Authoring ...................................................................................................... 16.2. Testing ......................................................................................................... 16.3. Debugging .................................................................................................... 16.3.1. @Audit Annotation .............................................................................. 16.4. Packaging and Deploying Overview ............................................................... 16.5. EPL Modules ................................................................................................ 16.6. The Deployment Administrative Interface ........................................................ 16.6.1. Reading Module Content ..................................................................... 16.6.2. Ordering Multiple Modules ................................................................... 16.6.3. Deploying and Undeploying ................................................................. 16.6.4. Listing Deployments ............................................................................ 16.6.5. State Transitioning a Module ............................................................... 16.6.6. Best Practices .................................................................................... 16.7. J2EE Packaging and Deployment .................................................................. 16.7.1. J2EE Deployment Considerations ........................................................ 16.7.2. Servlet Context Listener ...................................................................... 17. Integration and Extension ...................................................................................... 17.1. Overview ...................................................................................................... 494 495 502 506 507 508 511 511 512 513 513 514 516 516 519 521 522 522 524 525 526 526 527 529 529 529 529 529 531 531 533 534 534 534 535 535 536 536 536 537 541 541

xiv

17.2. Virtual Data Window ...................................................................................... 541 17.2.1. How to Use ........................................................................................ 542 17.2.2. Implementing the Factory .................................................................... 17.2.3. Implementing the Virtual Data Window ................................................. 17.2.4. Implementing the Lookup .................................................................... 17.3. Single-Row Function ..................................................................................... 17.3.1. Implementing a Single-Row Function ................................................... 17.3.2. Configuring the Single-Row Function Name .......................................... 17.3.3. Value Cache ...................................................................................... 17.3.4. Single-Row Functions in Filter Predicate Expressions ............................ 17.3.5. Exception Handling ............................................................................. 17.4. Derived-value and Data Window View ............................................................ 17.4.1. Implementing a View Factory .............................................................. 17.4.2. Implementing a View .......................................................................... 17.4.3. View Contract ..................................................................................... 17.4.4. Configuring View Namespace and Name ............................................. 17.4.5. Requirement for Data Window Views ................................................... 17.4.6. Requirement for Grouped Views .......................................................... 17.5. Aggregation Function ..................................................................................... 17.5.1. Implementing an Aggregation Function Factory .................................... 17.5.2. Implementing an Aggregation Function ................................................ 17.5.3. Configuring the Aggregation Function Name ......................................... 17.5.4. Accepting Multiple Parameters ............................................................ 17.5.5. Dot-Operator Use ............................................................................... 17.6. Pattern Guard ............................................................................................... 17.6.1. Implementing a Guard Factory ............................................................ 17.6.2. Implementing a Guard Class ............................................................... 17.6.3. Configuring Guard Namespace and Name ........................................... 17.7. Pattern Observer ........................................................................................... 17.7.1. Implementing an Observer Factory ...................................................... 17.7.2. Implementing an Observer Class ......................................................... 17.7.3. Configuring Observer Namespace and Name ....................................... 17.8. Event Type And Event Object ........................................................................ 17.8.1. How It Works ..................................................................................... 17.8.2. Steps ................................................................................................. 17.8.3. URI-based Resolution ......................................................................... 17.8.4. Example ............................................................................................. 18. Script Support ........................................................................................................ 18.1. Overview ...................................................................................................... 18.2. Syntax .......................................................................................................... 18.3. Examples ...................................................................................................... 18.4. Built-In EPL Script Attributes .......................................................................... 18.5. Performance Notes ....................................................................................... 18.6. Additional Notes ............................................................................................ 544 546 547 549 549 549 550 551 551 551 552 554 555 555 556 556 557 557 559 561 561 562 562 563 564 565 565 566 567 568 569 569 570 570 571 579 579 579 580 581 581 582

xv

Esper Reference

19. Examples, Tutorials, Case Studies ......................................................................... 583 19.1. Examples Overview ....................................................................................... 583 19.2. 19.3. 19.4. 19.5. Running the Examples .................................................................................. AutoID RFID Reader ..................................................................................... Runtime Configuration ................................................................................... JMS Server Shell and Client .......................................................................... 19.5.1. Overview ............................................................................................ 19.5.2. JMS Messages as Events ................................................................... 19.5.3. JMX for Remote Dynamic Statement Management ............................... 19.6. Market Data Feed Monitor ............................................................................. 19.6.1. Input Events ....................................................................................... 19.6.2. Computing Rates Per Feed ................................................................. 19.6.3. Detecting a Fall-off ............................................................................. 19.6.4. Event generator .................................................................................. 19.7. OHLC Plug-in View ....................................................................................... 19.8. Transaction 3-Event Challenge ...................................................................... 19.8.1. The Events ........................................................................................ 19.8.2. Combined event ................................................................................. 19.8.3. Real time summary data ..................................................................... 19.8.4. Find problems .................................................................................... 19.8.5. Event generator .................................................................................. 19.9. Self-Service Terminal .................................................................................... 19.9.1. Events ............................................................................................... 19.9.2. Detecting Customer Check-in Issues ................................................... 19.9.3. Absence of Status Events ................................................................... 19.9.4. Activity Summary Data ........................................................................ 19.9.5. Sample Application for J2EE Application Server ................................... 19.10. Assets Moving Across Zones - An RFID Example .......................................... 19.11. StockTicker ................................................................................................. 19.12. MatchMaker ................................................................................................ 19.13. Named Window Query ................................................................................. 19.14. Sample Virtual Data Window ........................................................................ 19.15. Quality of Service ........................................................................................ 19.16. Trivia Geeks Club ........................................................................................ 20. Performance ........................................................................................................... 20.1. Performance Results ..................................................................................... 20.2. Performance Tips .......................................................................................... 20.2.1. Understand how to tune your Java virtual machine ............................... 20.2.2. Compare Esper to other solutions ........................................................ 20.2.3. Input and Output Bottlenecks .............................................................. 20.2.4. Advanced Theading ............................................................................ 20.2.5. Select the underlying event rather than individual fields ......................... 20.2.6. Prefer stream-level filtering over post-data-window filtering .................... 20.2.7. Reduce the use of arithmetic in expressions ......................................... 585 585 586 586 586 587 587 588 588 588 588 589 589 590 590 590 590 591 591 591 591 592 592 593 593 595 595 596 596 596 596 597 599 599 599 599 600 600 601 601 601 603

xvi

20.2.8. Remove Unneccessary Constructs ...................................................... 603 20.2.9. End Pattern Sub-Expressions .............................................................. 603 20.2.10. Consider using EventPropertyGetter for fast access to event properties.. 604 20.2.11. Consider casting the underlying event ................................................ 605 20.2.12. Turn off logging and audit ................................................................. 605 20.2.13. Disable view sharing ......................................................................... 605 20.2.14. Tune or disable delivery order guarantees .......................................... 606 20.2.15. Use a Subscriber Object to Receive Events ........................................ 606 20.2.16. Consider Data Flows ......................................................................... 607 20.2.17. High-Arrival-Rate Streams and Single Statements ............................... 607 20.2.18. Subqueries versus Joins And Where-clause And Data Windows ........... 608 20.2.19. Patterns and Pattern Sub-Expression Instances .................................. 609 20.2.20. Pattern Sub-Expression Instance Versus Data Window Use ................. 611 20.2.21. The Keep-All Data Window ............................................................... 611 20.2.22. Statement Design for Reduced Memory Consumption - Diagnosing OutOfMemoryError ......................................................................................... 611 20.2.23. Performance, JVM, OS and hardware ................................................ 612 20.2.24. Consider using Hints ......................................................................... 20.2.25. Optimizing Stream Filter Expressions ................................................. 20.2.26. Statement and Engine Metric Reporting ............................................. 20.2.27. Expression Evaluation Order and Early Exit ........................................ 20.2.28. Large Number of Threads ................................................................. 20.2.29. Context Partition Related Information ................................................. 20.2.30. Prefer Constant Variables over Non-Constant Variables ...................... 20.2.31. Prefer Object-array Events ................................................................ 20.2.32. Composite or Compound Keys .......................................................... 20.2.33. Notes on Query Planning .................................................................. 20.2.34. Query Planning Index Hints ............................................................... 20.3. Using the performance kit .............................................................................. 20.3.1. How to use the performance kit ........................................................... 20.3.2. How we use the performance kit ......................................................... 21. References ............................................................................................................. 21.1. Reference List ............................................................................................... A. Output Reference and Samples ................................................................................. A.1. Introduction and Sample Data ......................................................................... A.2. Output for Un-aggregated and Un-grouped Queries .......................................... A.2.1. No Output Rate Limiting ....................................................................... A.2.2. Output Rate Limiting - Default ............................................................... A.2.3. Output Rate Limiting - Last ................................................................... A.2.4. Output Rate Limiting - First ................................................................... A.2.5. Output Rate Limiting - Snapshot ........................................................... A.3. Output for Fully-aggregated and Un-grouped Queries ....................................... A.3.1. No Output Rate Limiting ....................................................................... A.3.2. Output Rate Limiting - Default ............................................................... 613 613 614 614 615 615 615 616 616 617 617 618 618 622 623 623 625 625 627 627 628 630 631 632 634 634 636

xvii

Esper Reference

A.3.3. Output Rate Limiting - Last ................................................................... 637 A.3.4. Output Rate Limiting - First ................................................................... 638 A.3.5. Output Rate Limiting - Snapshot ........................................................... A.4. Output for Aggregated and Un-grouped Queries ............................................... A.4.1. No Output Rate Limiting ....................................................................... A.4.2. Output Rate Limiting - Default ............................................................... A.4.3. Output Rate Limiting - Last ................................................................... A.4.4. Output Rate Limiting - First ................................................................... A.4.5. Output Rate Limiting - Snapshot ........................................................... A.5. Output for Fully-aggregated and Grouped Queries ............................................ A.5.1. No Output Rate Limiting ....................................................................... A.5.2. Output Rate Limiting - Default ............................................................... A.5.3. Output Rate Limiting - All ..................................................................... A.5.4. Output Rate Limiting - Last ................................................................... A.5.5. Output Rate Limiting - First ................................................................... A.5.6. Output Rate Limiting - Snapshot ........................................................... A.6. Output for Aggregated and Grouped Queries .................................................... A.6.1. No Output Rate Limiting ....................................................................... A.6.2. Output Rate Limiting - Default ............................................................... A.6.3. Output Rate Limiting - All ..................................................................... A.6.4. Output Rate Limiting - Last ................................................................... A.6.5. Output Rate Limiting - First ................................................................... A.6.6. Output Rate Limiting - Snapshot ........................................................... B. Reserved Keywords ................................................................................................... Index ............................................................................................................................. 639 641 641 642 643 645 646 648 648 649 651 652 654 655 656 657 658 659 661 662 664 667 671

xviii

PrefaceAnalyzing 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 requiring high throughput processing. And applications may need to be flexible and react to changes in requirements 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 information 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 http://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 19.1, Examples Overview 9. Finally to test drive Esper performance, read Chapter 20, Performance

xix

xx

Chapter 1.

Chapter 1. Technology Overview1.1. Introduction to CEP and event stream analysisThe 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, aggregate 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 databasesRelational 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 generally have good query performance. Yet they are not optimized to provide immediate, real-time query results required for CEP and event stream analysis.

1

Chapter 1. Technology Overview

1.3. The Esper engine for CEPThe Esper engine works a bit like a database turned upside-down. Instead of storing the data and running queries 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 continuous rather than only when a query is submitted. Esper provides two principal methods or mechanisms to process events: event patterns and event stream queries. Esper offers an event pattern language to specify expression-based event pattern matching. Underlying the pattern matching engine is a state machine implementation. This method of event processing matches expected sequences 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 LibrariesEsper 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 required for build-time only. MySQL connector library is used for testing SQL integration and is required for running the automated test suite.

2

Chapter 2.

Chapter 2. Event RepresentationsThis 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 15.4, Configuration Items for startup-time configuration and Section 14.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 14.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 ObjectsAn 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 ObjectsJava Classjava.lang.Object

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

java.util.Map

Map

are implementations of the java.util.Map interface where each map entry is a propery value. Object-array events are arrays of objects (type Object[]) where each array element is a property value. XML document object model (DOM). XML - Streaming API for XML (StAX) - Apache Axiom (provided by EsperIO package). Plug-in event representation via the extension API.

events

Object[] (array of object)

org.w3c.dom.Node org.apache.axiom.om.OMDocument or OMElement

Application classes

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

3

Chapter 2. Event Representations

Event representations have the following in common: All event representations support nested, indexed and mapped properties (aka. property expression), as explained 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 statements. The Apache Axiom event representation is an exception and does not currently allow transposing event properties but does allow transposing the event itself. The Java object, Map and Object-array 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 transform 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 different 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 PropertiesEvent 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 PropertiesType Simple Indexed Description A property that has a single value that may be retrieved. An indexed property stores an ordered collection of objects (all of the same type) that can be individually accessed by an integervalued, non-negative index (or subscript). Syntaxname

ExamplesensorId

name[index]

sensor[0]

4

Escape Characters

Type Mapped

Description A mapped property stores a keyed collection of objects (all of the same type). A nested property is a property that lives within another property of an event.

Syntaxname('key')

Examplesensor('light')

Nested

name.nestedname

sensor.value

Combinations

are

also

possible.

For

example,

a

valid

combination

could

be

person.address('home').street[0].

You may use any expression as a mapped property key or indexed property index by putting the expression within parenthesis after the mapped or index property name. Please find examples below.

2.2.1. Escape CharactersIf your application uses java.util.Map, Object[] (object-array) or XML to represent events, then event property names may themselves contain the dot ('.') character. The backslash ('\') character can be used to escape dot characters in property names, allowing a property name to contain dot characters. For example, the EPL as shown below expects a property by name part1.part2 to exist on event type MyEvent:

select part1\.part2 from MyEvent

Sometimes your event properties may overlap with EPL language keywords or contain spaces or other special characters. In this case you may use the backwards apostrophe ` (aka. back tick) character to escape the property name. The next example assumes a Quote event that has a property by name order, while order is also a reserved keyword:

select `order`, price as `price.for.goods` from Quote

When escaping mapped or indexed properties, make sure the back tick character appears outside of the map key or index. The next EPL selects event properties that have names that contain spaces (e.g. candidate book), have the tick special character (e.g. children's books), are an indexed property (e.g. children's books[0]) and a mapped property that has a reserved keyword as part of the property name (e.g. book select('isbn')):

5

Chapter 2. Event Representations

select `candidate book` , `children's books`[0], `book select`('isbn') from MyEventType

2.2.2. Expression as Key or Index ValueThe key or index expression must be placed in parenthesis. When using an expression as key for a mapped property, the expression must return a String-typed value. When using an expression as index for an indexed property, the expression must return an int-typed value. This example below uses Java classes to illustrate;The same principles apply to all event representations. Assume a class declares these properties (getters not shown for brevity):

public class MyEventType { String myMapKey; int myIndexValue; int myInnerIndexValue; Map innerTypesMap; // mapped property InnerType[] innerTypesArray; // indexed property } public class InnerType { String name; int[] ids; }

A sample EPL statement demonstrating expressions as map keys or indexes is:

select innerTypesMap('somekey'), innerTypesMap(myMapKey), expression) innerTypesArray[1], innerTypesArray(myIndexValue) (an expression) from MyEventType

// returns map value for 'somekey' // returns map value for myMapKey value (an // returns array value at index 1 // returns array value at index myIndexValue

The dot-operator can be used to access methods on the value objects returned by the mapped or indexed properties. By using the dot-operator the syntax follows the chained method invocation described at Section 8.6, Dot Operator. A sample EPL statement demonstra