back to listing index

Esper Reference

[web search]
Original source (esper.codehaus.org)
Tags: database performance esper
Clipped on: 2014-11-12

Version 5.1.0

Copyright © 2014 EsperTech Inc.


Preface
1. Technology Overview
1.1. Introduction to CEP and event series analysis
1.2. CEP and relational databases
1.3. The Esper engine for CEP
1.4. Required 3rd Party Libraries
2. Event Representations
2.1. Event Underlying Java Objects
2.2. Event Properties
2.2.1. Escape Characters
2.2.2. Expression as Key or Index Value
2.3. Dynamic Event Properties
2.4. Fragment and Fragment Type
2.5. Plain-Old Java Object Events
2.5.1. Java Object Event Properties
2.5.2. Property Names
2.5.3. Parameterized Types
2.5.4. Setter Methods for Indexed and Mapped Properties
2.5.5. 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
3.5. Time Windows
3.5.1. Time Window
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. Context and Tables
4.8. Context and Variables
4.9. 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. Using Constants and Enum Types
5.2.7. Annotation
5.2.8. Expression Alias
5.2.9. Expression Declaration
5.2.10. Script Declaration
5.2.11. 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
5.3.8. Qualifying property names and stream names
5.3.9. Select Distinct
5.3.10. Transposing an Expression Result to a Stream
5.3.11. Selecting EventBean instead of Underlying Event
5.4. Specifying Event Streams: the From Clause
5.4.1. Filter-based Event Streams
5.4.2. Pattern-based Event Streams
5.4.3. Specifying Views
5.4.4. Multiple Data Window Views
5.4.5. Using the Stream Name
5.5. Specifying Search Conditions: the Where Clause
5.6. Aggregates and grouping: the Group-by Clause and the Having Clause
5.6.1. Using aggregate functions
5.6.2. Organizing statement results into groups: the Group-by clause
5.6.3. Using Group-By with Rollup, Cube and Grouping Sets
5.6.4. Selecting groups of events: the Having clause
5.6.5. How the stream filter, Where, Group By and Having clauses interact
5.6.6. Comparing Keyed Segmented Context, the Group By clause and the std:groupwin view
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.10.8. Select-Clause Expression And Inserted-Into Column Event Type
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. Subquery With Group By Clause
5.11.6. Multi-Column Selection
5.11.7. Multi-Row Selection
5.11.8. 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
5.12.5. Hints Related to Joins
5.13. Accessing Relational Data via SQL
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.14.5. Using a Object Array Return Type
5.15. Declaring an Event Type: Create Schema
5.15.1. Declare an Event Type by Providing Names and Types
5.15.2. Declare an Event Type by Providing a Class Name
5.15.3. Declare a Variant Stream
5.16. Splitting and Duplicating Streams
5.17. Variables and Constants
5.17.1. Creating Variables: the Create Variable clause
5.17.2. Setting Variable Values: the On Set clause
5.17.3. Using Variables
5.17.4. Object-Type Variables
5.17.5. Class and Event-Type Variables
5.18. Declaring Global Expressions, Aliases And Scripts: Create Expression
5.18.1. Global Expression Aliases
5.18.2. Global Expression Declarations
5.18.3. Global Scripts
5.19. Contained-Event Selection
5.19.1. Select-Clause in a Contained-Event Selection
5.19.2. Where Clause in a Contained-Event Selection
5.19.3. Contained-Event Selection and Joins
5.19.4. Sentence and Word Example
5.19.5. More Examples
5.19.6. Contained-Event Limitations
5.20. Updating an Insert Stream: the Update IStream Clause
5.20.1. Immutability and Updates
5.21. Controlling Event Delivery : The For Clause
6. EPL Reference: Named Windows And Tables
6.1. Overview
6.1.1. Named Window Overview
6.1.2. Table Overview
6.1.3. Comparing Named Windows And Tables
6.2. Named Window Usage
6.2.1. Creating Named Windows: the Create Window clause
6.2.2. Inserting Into Named Windows
6.2.3. Selecting From Named Windows
6.3. Table Usage
6.3.1. Creating Tables: The Create Table clause
6.3.2. Aggregating Into Table Rows: The Into Table clause
6.3.3. Table Column Keyed-Access Expressions
6.3.4. Inserting Into Tables
6.3.5. Selecting From Tables
6.4. Triggered Select: the On Select clause
6.4.1. Notes on On-Select With Named Windows
6.4.2. Notes on On-Select With Tables
6.4.3. On-Select Compared To Join
6.5. Triggered Select+Delete: the On Select Delete clause
6.6. Updating Data: the On Update clause
6.6.1. Notes on On-Update With Named Windows
6.6.2. Notes on On-Update With Tables
6.7. Deleting Data: the On Delete clause
6.7.1. Using Patterns in the On Delete Clause
6.7.2. Notes on On-Delete With Named Windows
6.7.3. Notes on On-Update With Tables
6.8. Triggered Upsert using the On-Merge Clause
6.8.1. Notes on On-Merge With Named Windows
6.8.2. Notes on On-Merge With Tables
6.9. Explicitly Indexing Named Windows and Tables
6.10. Using Fire-And-Forget Queries with Named Windows and Tables
6.10.1. Inserting Data
6.10.2. Updating Data
6.10.3. Deleting Data
6.11. Versioning and Revision Event Type Use with Named Windows
6.12. Events As Property
7. EPL Reference: Patterns
7.1. Event Pattern Overview
7.2. How to use Patterns
7.2.1. Pattern Syntax
7.2.2. Patterns in EPL
7.2.3. Subscribing to Pattern Events
7.2.4. Pulling Data from Patterns
7.2.5. Pattern Error Reporting
7.2.6. Suppressing Same-Event Matches
7.2.7. Discarding Partially Completed Patterns
7.3. Operator Precedence
7.4. Filter Expressions In Patterns
7.4.1. Controlling Event Consumption
7.4.2. Use With Named Windows and Tables
7.5. Pattern Operators
7.5.1. Every
7.5.2. Every-Distinct
7.5.3. Repeat
7.5.4. Repeat-Until
7.5.5. And
7.5.6. Or
7.5.7. Not
7.5.8. Followed-by
7.5.9. Pattern Guards
7.6. Pattern Atoms
7.6.1. Filter Atoms
7.6.2. Time-based Observer Atoms
8. EPL Reference: Match Recognize
8.1. Overview
8.2. Comparison of Match Recognize and EPL Patterns
8.3. Syntax
8.3.1. Syntax Example
8.4. Pattern and Pattern Operators
8.4.1. Operator Precedence
8.4.2. Concatenation
8.4.3. Alternation
8.4.4. Quantifiers Overview
8.4.5. Variables Can be Singleton or Group
8.4.6. Eliminating Duplicate Matches
8.4.7. Greedy Or Reluctant
8.4.8. Quantifier - One Or More (+ and +?)
8.4.9. Quantifier - Zero Or More (* and *?)
8.4.10. Quantifier - Zero Or One (? and ??)
8.5. Define Clause
8.5.1. The Prev Operator
8.6. Measure Clause
8.7. Datawindow-Bound
8.8. Interval
8.9. Interval-Or-Terminated
8.10. Use with Different Event Types
8.11. Limitations
9. EPL Reference: Operators
9.1. Arithmetic Operators
9.2. Logical And Comparison Operators
9.2.1. Null-Value Comparison Operators
9.3. Concatenation Operators
9.4. Binary Operators
9.5. Array Definition Operator
9.6. Dot Operator
9.6.1. Duck Typing
9.7. The 'in' Keyword
9.7.1. 'in' for Range Selection
9.8. The 'between' Keyword
9.9. The 'like' Keyword
9.10. The 'regexp' Keyword
9.11. The 'any' and 'some' Keywords
9.12. The 'all' Keyword
9.13. The 'new' Keyword
10. EPL Reference: Functions
10.1. Single-row Function Reference
10.1.1. The Case Control Flow Function
10.1.2. The Cast Function
10.1.3. The Coalesce Function
10.1.4. The Current_Timestamp Function
10.1.5. The Exists Function
10.1.6. The Grouping Function
10.1.7. The Grouping_Id Function
10.1.8. The Instance-Of Function
10.1.9. The Istream Function
10.1.10. The Min and Max Functions
10.1.11. The Previous Function
10.1.12. The Previous-Tail Function
10.1.13. The Previous-Window Function
10.1.14. The Previous-Count Function
10.1.15. The Prior Function
10.1.16. The Type-Of Function
10.2. Aggregation Functions
10.2.1. SQL-Standard Functions
10.2.2. Event Aggregation Functions
10.2.3. Approximation Aggregation Functions
10.2.4. Additional Aggregation Functions
10.3. User-Defined Functions
10.4. Select-Clause transpose Function
10.4.1. Transpose with Insert-Into
11. EPL Reference: Enumeration Methods
11.1. Overview
11.2. Example Events
11.3. How to Use
11.3.1. Syntax
11.3.2. Introductory Examples
11.3.3. Input, Output and Limitations
11.4. Inputs
11.4.1. Subquery Results
11.4.2. Named Window
11.4.3. Table
11.4.4. Event Property
11.4.5. Event Aggregation Function
11.4.6. prev, prevwindow and prevtail Single-Row Functions as Input
11.4.7. Single-Row Function, User-Defined Function and Enum Types
11.4.8. Declared Expression
11.4.9. Variables
11.4.10. Substitution Parameters
11.4.11. Match-Recognize Group Variable
11.4.12. Pattern Repeat and Repeat-Until Operators
11.5. Example
11.6. Reference
11.6.1. Aggregate
11.6.2. AllOf
11.6.3. AnyOf
11.6.4. Average
11.6.5. CountOf
11.6.6. DistinctOf
11.6.7. Except
11.6.8. FirstOf
11.6.9. GroupBy
11.6.10. Intersect
11.6.11. LastOf
11.6.12. LeastFrequent
11.6.13. Max
11.6.14. MaxBy
11.6.15. Min
11.6.16. MinBy
11.6.17. MostFrequent
11.6.18. OrderBy and OrderByDesc
11.6.19. Reverse
11.6.20. SelectFrom
11.6.21. SequenceEqual
11.6.22. SumOf
11.6.23. Take
11.6.24. TakeLast
11.6.25. TakeWhile
11.6.26. TakeWhileLast
11.6.27. ToMap
11.6.28. Union
11.6.29. Where
12. EPL Reference: Date-Time Methods
12.1. Overview
12.2. How to Use
12.2.1. Syntax
12.3. Calendar and Formatting Reference
12.3.1. Between
12.3.2. Format
12.3.3. Get (By Field)
12.3.4. Get (By Name)
12.3.5. Minus
12.3.6. Plus
12.3.7. RoundCeiling
12.3.8. RoundFloor
12.3.9. RoundHalf
12.3.10. Set (By Field)
12.3.11. WithDate
12.3.12. WithMax
12.3.13. WithMin
12.3.14. WithTime
12.3.15. ToCalendar
12.3.16. ToDate
12.3.17. ToMillisec
12.4. Interval Algebra Reference
12.4.1. Examples
12.4.2. Interval Algebra Parameters
12.4.3. Performance
12.4.4. Limitations
12.4.5. After
12.4.6. Before
12.4.7. Coincides
12.4.8. During
12.4.9. Finishes
12.4.10. Finished By
12.4.11. Includes
12.4.12. Meets
12.4.13. Met By
12.4.14. Overlaps
12.4.15. Overlapped By
12.4.16. Starts
12.4.17. Started By
13. EPL Reference: Views
13.1. A Note on View Parameters
13.2. Data Window Views
13.2.1. Length window (win:length)
13.2.2. Length batch window (win:length_batch)
13.2.3. Time window (win:time)
13.2.4. Externally-timed window (win:ext_timed)
13.2.5. Time batch window (win:time_batch)
13.2.6. Externally-timed batch window (win:ext_timed_batch)
13.2.7. Time-Length combination batch window (win:time_length_batch)
13.2.8. Time-Accumulating window (win:time_accum)
13.2.9. Keep-All window (win:keepall)
13.2.10. First Length (win:firstlength)
13.2.11. First Time (win:firsttime)
13.2.12. Expiry Expression (win:expr)
13.2.13. Expiry Expression Batch (win:expr_batch)
13.3. Standard view set
13.3.1. Unique (std:unique)
13.3.2. Grouped Data Window (std:groupwin)
13.3.3. Size (std:size)
13.3.4. Last Event (std:lastevent)
13.3.5. First Event (std:firstevent)
13.3.6. First Unique (std:firstunique)
13.4. Statistics views
13.4.1. Univariate statistics (stat:uni)
13.4.2. Regression (stat:linest)
13.4.3. Correlation (stat:correl)
13.4.4. Weighted average (stat:weighted_avg)
13.5. Extension View Set
13.5.1. Sorted Window View (ext:sort)
13.5.2. Ranked Window View (ext:rank)
13.5.3. Time-Order View (ext:time_order)
14. EPL Reference: Data Flow
14.1. Introduction
14.2. Usage
14.2.1. Overview
14.2.2. Syntax
14.3. Built-in Operators
14.3.1. BeaconSource
14.3.2. EPStatementSource
14.3.3. EventBusSink
14.3.4. EventBusSource
14.3.5. Filter
14.3.6. LogSink
14.3.7. Select
14.4. API
14.4.1. Declaring a Data Flow
14.4.2. Instantiating a Data Flow
14.4.3. Executing a Data Flow
14.4.4. Instantiation Options
14.4.5. Start Captive
14.4.6. Data Flow Punctuation with Markers
14.4.7. Exception Handling
14.5. Examples
14.6. Operator Implementation
14.6.1. Sample Operator Acting as Source
14.6.2. Sample Tokenizer Operator
14.6.3. Sample Aggregator Operator
15. API Reference
15.1. API Overview
15.2. The Service Provider Interface
15.3. The Administrative Interface
15.3.1. Creating Statements
15.3.2. Receiving Statement Results
15.3.3. Setting a Subscriber Object
15.3.4. Adding Listeners
15.3.5. Using Iterators
15.3.6. Managing Statements
15.3.7. Runtime Configuration
15.4. The Runtime Interface
15.4.1. Event Sender
15.4.2. Receiving Unmatched Events
15.5. On-Demand Fire-And-Forget Query Execution
15.5.1. On-Demand Query Single Execution
15.5.2. On-Demand Query Prepared Unparameterized Execution
15.5.3. On-Demand Query Prepared Parameterized Execution
15.6. Event and Event Type
15.6.1. Event Type Metadata
15.6.2. Event Object
15.6.3. Query Example
15.6.4. Pattern Example
15.7. Engine Threading and Concurrency
15.7.1. Advanced Threading
15.7.2. Processing Order
15.8. Controlling Time-Keeping
15.8.1. Controlling Time Using Time Span Events
15.8.2. Additional Time-Related APIs
15.9. Time Resolution
15.10. Service Isolation
15.10.1. Overview
15.10.2. Example: Suspending a Statement
15.10.3. Example: Catching up a Statement from Historical Data
15.10.4. Isolation for Insert-Into
15.10.5. Isolation for Named Windows and Tables
15.10.6. Runtime Considerations
15.11. Exception Handling
15.12. Condition Handling
15.13. Statement Object Model
15.13.1. Building an Object Model
15.13.2. Building Expressions
15.13.3. Building a Pattern Statement
15.13.4. Building a Select Statement
15.13.5. Building a Create-Variable and On-Set Statement
15.13.6. Building Create-Window, On-Delete and On-Select Statements
15.14. Prepared Statement and Substitution Parameters
15.15. Engine and Statement Metrics Reporting
15.15.1. Engine Metrics
15.15.2. Statement Metrics
15.16. Event Rendering to XML and JSON
15.16.1. JSON Event Rendering Conventions and Options
15.16.2. XML Event Rendering Conventions and Options
15.17. Plug-in Loader
15.18. Interrogating EPL Annotations
15.19. Context Partition Selection
15.19.1. Selectors
15.20. Context Partition Administration
15.21. Test and Assertion Support
15.21.1. EPAssertionUtil Summary
15.21.2. SupportUpdateListener Summary
15.21.3. Usage Example
16. Configuration
16.1. Programmatic Configuration
16.2. Configuration via XML File
16.3. XML Configuration File
16.4. Configuration Items
16.4.1. Events represented by Java Classes
16.4.2. Events represented by java.util.Map
16.4.3. Events represented by Object[] (Object-array)
16.4.4. Events represented by org.w3c.dom.Node
16.4.5. Events represented by Plug-in Event Representations
16.4.6. Class and package imports
16.4.7. Cache Settings for From-Clause Method Invocations
16.4.8. Variables
16.4.9. Relational Database Access
16.4.10. Engine Settings related to Concurrency and Threading
16.4.11. Engine Settings related to Event Metadata
16.4.12. Engine Settings related to View Resources
16.4.13. Engine Settings related to Logging
16.4.14. Engine Settings related to Variables
16.4.15. Engine Settings related to Patterns
16.4.16. Engine Settings related to Scripts
16.4.17. Engine Settings related to Stream Selection
16.4.18. Engine Settings related to Time Source
16.4.19. Engine Settings related to JMX Metrics
16.4.20. Engine Settings related to Metrics Reporting
16.4.21. Engine Settings related to Language and Locale
16.4.22. Engine Settings related to Expression Evaluation
16.4.23. Engine Settings related to Execution of Statements
16.4.24. Engine Settings related to Exception Handling
16.4.25. Engine Settings related to Condition Handling
16.4.26. Revision Event Type
16.4.27. Variant Stream
16.5. Type Names
16.6. Runtime Configuration
16.7. Logging Configuration
16.7.1. Log4j Logging Configuration
17. Development Lifecycle
17.1. Authoring
17.2. Testing
17.3. Debugging
17.3.1. @Audit Annotation
17.4. Packaging and Deploying Overview
17.5. EPL Modules
17.6. The Deployment Administrative Interface
17.6.1. Reading Module Content
17.6.2. Ordering Multiple Modules
17.6.3. Deploying and Undeploying
17.6.4. Listing Deployments
17.6.5. State Transitioning a Module
17.6.6. Best Practices
17.7. J2EE Packaging and Deployment
17.7.1. J2EE Deployment Considerations
17.7.2. Servlet Context Listener
17.8. Monitoring and JMX
18. Integration and Extension
18.1. Overview
18.2. Virtual Data Window
18.2.1. How to Use
18.2.2. Implementing the Factory
18.2.3. Implementing the Virtual Data Window
18.2.4. Implementing the Lookup
18.3. Single-Row Function
18.3.1. Implementing a Single-Row Function
18.3.2. Configuring the Single-Row Function Name
18.3.3. Value Cache
18.3.4. Single-Row Functions in Filter Predicate Expressions
18.3.5. Single-Row Functions Taking Events as Parameters
18.3.6. Receiving a Context Object
18.3.7. Exception Handling
18.4. Derived-value and Data Window View
18.4.1. Implementing a View Factory
18.4.2. Implementing a View
18.4.3. View Contract
18.4.4. Configuring View Namespace and Name
18.4.5. Requirement for Data Window Views
18.4.6. Requirement for Derived-Value Views
18.4.7. Requirement for Grouped Views
18.5. Aggregation Function
18.5.1. Aggregation Single-Function Development
18.5.2. Aggregation Multi-Function Development
18.6. Pattern Guard
18.6.1. Implementing a Guard Factory
18.6.2. Implementing a Guard Class
18.6.3. Configuring Guard Namespace and Name
18.7. Pattern Observer
18.7.1. Implementing an Observer Factory
18.7.2. Implementing an Observer Class
18.7.3. Configuring Observer Namespace and Name
18.8. Event Type And Event Object
18.8.1. How It Works
18.8.2. Steps
18.8.3. URI-based Resolution
18.8.4. Example
19. Script Support
19.1. Overview
19.2. Syntax
19.3. Examples
19.4. Built-In EPL Script Attributes
19.5. Performance Notes
19.6. Additional Notes
20. Examples, Tutorials, Case Studies
20.1. Examples Overview
20.2. Running the Examples
20.3. AutoID RFID Reader
20.4. Runtime Configuration
20.5. JMS Server Shell and Client
20.5.1. Overview
20.5.2. JMS Messages as Events
20.5.3. JMX for Remote Dynamic Statement Management
20.6. Market Data Feed Monitor
20.6.1. Input Events
20.6.2. Computing Rates Per Feed
20.6.3. Detecting a Fall-off
20.6.4. Event generator
20.7. OHLC Plug-in View
20.8. Transaction 3-Event Challenge
20.8.1. The Events
20.8.2. Combined event
20.8.3. Real time summary data
20.8.4. Find problems
20.8.5. Event generator
20.9. Self-Service Terminal
20.9.1. Events
20.9.2. Detecting Customer Check-in Issues
20.9.3. Absence of Status Events
20.9.4. Activity Summary Data
20.9.5. Sample Application for J2EE Application Server
20.10. Assets Moving Across Zones - An RFID Example
20.11. StockTicker
20.12. MatchMaker
20.13. Named Window Query
20.14. Sample Virtual Data Window
20.15. Sample Cycle Detection
20.16. Quality of Service
20.17. Trivia Geeks Club
21. Performance
21.1. Performance Results
21.2. Performance Tips
21.2.1. Understand how to tune your Java virtual machine
21.2.2. Input and Output Bottlenecks
21.2.3. Theading
21.2.4. Select the underlying event rather than individual fields
21.2.5. Prefer stream-level filtering over where-clause filtering
21.2.6. Reduce the use of arithmetic in expressions
21.2.7. Remove Unneccessary Constructs
21.2.8. End Pattern Sub-Expressions
21.2.9. Consider using EventPropertyGetter for fast access to event properties
21.2.10. Consider casting the underlying event
21.2.11. Turn off logging and audit
21.2.12. Disable view sharing
21.2.13. Tune or disable delivery order guarantees
21.2.14. Use a Subscriber Object to Receive Events
21.2.15. Consider Data Flows
21.2.16. High-Arrival-Rate Streams and Single Statements
21.2.17. Subqueries versus Joins And Where-clause And Data Windows
21.2.18. Patterns and Pattern Sub-Expression Instances
21.2.19. Pattern Sub-Expression Instance Versus Data Window Use
21.2.20. The Keep-All Data Window
21.2.21. Statement Design for Reduced Memory Consumption - Diagnosing OutOfMemoryError
21.2.22. Performance, JVM, OS and hardware
21.2.23. Consider using Hints
21.2.24. Optimizing Stream Filter Expressions
21.2.25. Statement and Engine Metric Reporting
21.2.26. Expression Evaluation Order and Early Exit
21.2.27. Large Number of Threads
21.2.28. Filter Evaluation Tuning
21.2.29. Context Partition Related Information
21.2.30. Prefer Constant Variables over Non-Constant Variables
21.2.31. Prefer Object-array Events
21.2.32. Composite or Compound Keys
21.2.33. Notes on Query Planning
21.2.34. Query Planning Expression Analysis Hints
21.2.35. Query Planning Index Hints
21.2.36. Measuring Throughput
21.2.37. Do not create the same EPL Statement X times
21.2.38. Comparing Single-Threaded and Multi-Threaded Performance
21.2.39. Incremental Versus Recomputed Aggregation for Named Window Events
21.2.40. When Does Memory Get Released
21.2.41. Measure throughput of non-matches as well as matches
21.3. Using the performance kit
21.3.1. How to use the performance kit
21.3.2. How we use the performance kit
22. References
22.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
A.3.3. Output Rate Limiting - Last
A.3.4. Output Rate Limiting - First
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
A.7. Output for Fully-Aggregated, Grouped Queries With Rollup
A.7.1. No Output Rate Limiting
A.7.2. Output Rate Limiting - Default
A.7.3. Output Rate Limiting - All
A.7.4. Output Rate Limiting - Last
A.7.5. Output Rate Limiting - First
A.7.6. Output Rate Limiting - Snapshot
B. Reserved Keywords
Index

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 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 series 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 7.1, “Event Pattern Overview” for an overview over event patterns

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

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

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

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

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 series analysis. Key considerations for these types of applications are throughput, latency and the complexity of the logic required.

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

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 generally have good query performance. Yet they are not optimized to provide immediate, real-time query results required for CEP and event series analysis.

The 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 series queries that address the event series analysis requirements of CEP applications. Event series 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 series and to derive data from an event series.

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

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

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

2.1. Event Underlying Java Objects
2.2. Event Properties
2.2.1. Escape Characters
2.2.2. Expression as Key or Index Value
2.3. Dynamic Event Properties
2.4. Fragment and Fragment Type
2.5. Plain-Old Java Object Events
2.5.1. Java Object Event Properties
2.5.2. Property Names
2.5.3. Parameterized Types
2.5.4. Setter Methods for Indexed and Mapped Properties
2.5.5. 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

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 16.4, “Configuration Items” for startup-time configuration and Section 15.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.15, “Declaring an Event Type: Create Schema”.

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

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:



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 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.

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.



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.

If 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')):

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

The 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<String, InnerType> 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'),  // returns map value for 'somekey'
  innerTypesMap(myMapKey),        // returns map value for myMapKey value (an expression)
  innerTypesArray[1],             // returns array value at index 1
  innerTypesArray(myIndexValue)   // returns array value at index myIndexValue (an expression)
  from MyEventType

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 9.6, “Dot Operator”.

A sample EPL statement demonstrating the dot-operator as well as expressions as map keys or indexes is:

 select innerTypesMap('somekey').ids[1],
  innerTypesMap(myMapKey).getIds(myIndexValue),
  innerTypesArray[1].ids[2],
  innerTypesArray(myIndexValue).getIds(myInnerIndexValue)
  from MyEventType

Please note the following limitations:

  • The square brackets-syntax for indexed properties does now allow expressions and requires a constant index value.

  • When using the dot-operator with mapped or indexed properties that have expressions as map keys or indexes you must follow the chained method invocation syntax.

Dynamic (unchecked) properties are event properties that need not be known at statement compilation time. Such properties are resolved during runtime: they provide duck typing functionality.

The idea behind dynamic properties is that for a given underlying event representation we don't always know all properties in advance. An underlying event may have additional properties that are not known at statement compilation time, that we want to query on. The concept is especially useful for events that represent rich, object-oriented domain models.

The syntax of dynamic properties consists of the property name and a question mark. Indexed, mapped and nested properties can also be dynamic properties:



Dynamic properties always return the java.lang.Object type. Also, dynamic properties return a null value if the dynamic property does not exist on events processed at runtime.

As an example, consider an OrderEvent event that provides an "item" property. The "item" property is of type Object and holds a reference to an instance of either a Service or Product.

Assume that both Service and Product classes provide a property named "price". Via a dynamic property we can specify a query that obtains the price property from either object (Service or Product):

select item.price? from OrderEvent

As a second example, assume that the Service class contains a "serviceName" property that the Product class does not possess. The following query returns the value of the "serviceName" property for Service objects. It returns a null-value for Product objects that do not have the "serviceName" property:

select item.serviceName? from OrderEvent

Consider the case where OrderEvent has multiple implementation classes, some of which have a "timestamp" property. The next query returns the timestamp property of those implementations of the OrderEvent interface that feature the property:

select timestamp? from OrderEvent

The query as above returns a single column named "timestamp?" of type Object.

When dynamic properties are nested, then all properties under the dynamic property are also considered dynamic properties. In the below example the query asks for the "direction" property of the object returned by the "detail" dynamic property:

select detail?.direction from OrderEvent

Above is equivalent to:

select detail?.direction? from OrderEvent

The functions that are often useful in conjunction with dynamic properties are:

  • The cast function casts the value of a dynamic property (or the value of an expression) to a given type.

  • The exists function checks whether a dynamic property exists. It returns true if the event has a property of that name, or false if the property does not exist on that event.

  • The instanceof function checks whether the value of a dynamic property (or the value of an expression) is of any of the given types.

  • The typeof function returns the string type name of a dynamic property.

Dynamic event properties work with all event representations outlined next: Java objects, Map-based, Object-array-based and XML DOM-based events.

Sometimes an event can have properties that are itself events. Esper uses the term fragment and fragment type for such event pieces. The best example is a pattern that matches two or more events and the output event contains the matching events as fragments. In other words, output events can be a composite event that consists of further events, the fragments.

Fragments have the same metadata available as their enclosing composite events. The metadata for enclosing composite events contains information about which properties are fragments, or have a property value that can be represented as a fragment and therefore as an event itself.

Fragments and type metadata can allow your application to navigate composite events without the need for using the Java reflection API and reducing the coupling to the underlying event representation. The API is further described in Section 15.6, “Event and Event Type”.

Plain-old Java object events are object instances that expose event properties through JavaBeans-style getter methods. Events classes or interfaces do not have to be fully compliant to the JavaBean specification; however for the Esper engine to obtain event properties, the required JavaBean getter methods must be present or an accessor-style and accessor-methods may be defined via configuration.

Esper supports JavaBeans-style event classes that extend a superclass or implement one or more interfaces. Also, Esper event pattern and EPL statements can refer to Java interface classes and abstract classes.

Classes that represent events should be made immutable. As events are recordings of a state change or action that occurred in the past, the relevant event properties should not be changeable. However this is not a hard requirement and the Esper engine accepts events that are mutable as well.

The hashCode and equals methods do not need to be implemented. The implementation of these methods by a Java event class does not affect the behavior of the engine in any way.

Please see Chapter 16, Configuration on options for naming event types represented by Java object event classes. Java classes that do not follow JavaBean conventions, such as legacy Java classes that expose public fields, or methods not following naming conventions, require additional configuration. Via configuration it is also possible to control case sensitivity in property name resolution. The relevant section in the chapter on configuration is Section 16.4.1.3, “Non-JavaBean and Legacy Java Event Classes”.

As outlined earlier, the different property types are supported by the standard JavaBeans specification, and some of which are uniquely supported by Esper:

Assume there is an NewEmployeeEvent event class as shown below. The mapped and indexed properties in this example return Java objects but could also return Java language primitive types (such as int or String). The Address object and Employee can themselves have properties that are nested within them, such as a street name in the Address object or a name of the employee in the Employee object.

public class NewEmployeeEvent {
	public String getFirstName();
	public Address getAddress(String type);
	public Employee getSubordinate(int index);
	public Employee[] getAllSubordinates();
}

Simple event properties require a getter-method that returns the property value. In this example, the getFirstName getter method returns the firstName event property of type String.

Indexed event properties require either one of the following getter-methods. A method that takes an integer-type key value and returns the property value, such as the getSubordinate method, or a method that returns an array-type, or a class that implements Iterable. An example is the getAllSubordinates getter method, which returns an array of Employee but could also return an Iterable. In an EPL or event pattern statement, indexed properties are accessed via the property[index] syntax.

Mapped event properties require a getter-method that takes a String-typed key value and returns the property value, such as the getAddress method. In an EPL or event pattern statement, mapped properties are accessed via the property('key') syntax.

Nested event properties require a getter-method that returns the nesting object. The getAddress and getSubordinate methods are mapped and indexed properties that return a nesting object. In an EPL or event pattern statement, nested properties are accessed via the property.nestedProperty syntax.

All event pattern and EPL statements allow the use of indexed, mapped and nested properties (or a combination of these) anywhere where one or more event property names are expected. The below example shows different combinations of indexed, mapped and nested properties in filters of event pattern expressions (each line is a separate EPL statement):

every NewEmployeeEvent(firstName='myName')
every NewEmployeeEvent(address('home').streetName='Park Avenue')
every NewEmployeeEvent(subordinate[0].name='anotherName')
every NewEmployeeEvent(allSubordinates[1].name='thatName')
every NewEmployeeEvent(subordinate[0].address('home').streetName='Water Street')

Similarly, the syntax can be used in EPL statements in all places where an event property name is expected, such as in select lists, where-clauses or join criteria.

select firstName, address('work'), subordinate[0].name, subordinate[1].name
from NewEmployeeEvent
where address('work').streetName = 'Park Ave'

An EPL statement may update indexed or mapped properties of an event, provided the event class exposes the required setter method.

The setter method for indexed properties must be named setPropertyName and must take two parameters: the int-type index and the Object type new value.

The setter method for mapped properties must be named setPropertyName and must take two parameters: the String-type map key and the Object type new map value.

The following is an example event that features a setter method for the props mapped property and for the array indexed property:

public class MyEvent {
  private Map props = new HashMap();
  private Object[] array = new Object[10];

  public void setProps(String name, Object value) {
    props.put(name, value);
  }

  public void setArray(int index, Object value) {
    array[index] = value;
  }
  // ... also provide regular JavaBean getters and setters for all properties

This sample statement updates mapped and indexed property values:

update istream MyEventStream set props('key') = 'abc', array[2] = 100

Events can also be represented by objects that implement the java.util.Map interface. Event properties of Map events are the values in the map accessible through the get method exposed by the java.util.Map interface.

Similar to the Object-array event type, the Map event type takes part in the comprehensive type system that can eliminate the need to use Java classes as event types, thereby making it easier to change types at runtime or generate type information from another source.

A given Map event type can have one or more supertypes that must also be Map event types. All properties available on any of the Map supertypes are available on the type itself. In addition, anywhere within EPL that an event type name of a Map supertype is used, any of its Map subtypes and their subtypes match that expression.

Your application can add properties to an existing Map event type during runtime using the configuration operation updateMapEventType. Properties may not be updated or deleted - properties can only be added, and nested properties can be added as well. The runtime configuration also allows removing Map event types and adding them back with new type information.

After your application configures a Map event type by providing a type name, the type name can be used when defining further Map or Object-array event types by specifying the type name as a property type or an array property type.

One-to-Many relationships in Map event types are represented via arrays. A property in a Map event type may be an array of primitive, an array of Java object, an array of Map or an an array of Object-array.

The engine can process java.util.Map events via the sendEvent(Map map, String eventTypeName) method on the EPRuntime interface. Entries in the Map represent event properties. Keys must be of type java.util.String for the engine to be able to look up event property names specified by pattern or EPL statements.

The engine does not validate Map event property names or values. Your application should ensure that objects passed in as event properties match the create schema property names and types, or the configured event type information when using runtime or static configuration.

Map event properties can be of any type. Map event properties that are Java application objects or that are of type java.util.Map (or arrays thereof) or that are of type Object[] (object-array) (or arrays thereof) offer additional power:

In order to use Map events, the event type name and property names and types must be made known to the engine via Configuration or create schema EPL syntax. Please see examples in Section 5.15, “Declaring an Event Type: Create Schema” and Section 16.4.2, “Events represented by java.util.Map”.

The code snippet below defines a Map event type, creates a Map event and sends the event into the engine. The sample defines the CarLocUpdateEvent event type via runtime configuration interface (create schema or static configuration could have been used instead).

// Define CarLocUpdateEvent event type (example for runtime-configuration interface)
Map<String, Object> def = new HashMap<String, Object>;
def.put("carId", String.class);
def.put("direction", int.class);

epService.getEPAdministrator().getConfiguration().
  addEventType("CarLocUpdateEvent", def);

The CarLocUpdateEvent can now be used in a statement:

select carId from CarLocUpdateEvent.win:time(1 min) where direction = 1
// Create a CarLocUpdateEvent event and send it into the engine for processing
Map<String, Object> event = new HashMap<String, Object>();
event.put("carId", carId);
event.put("direction", direction);

epRuntime.sendEvent(event, "CarLocUpdateEvent");

The engine can also query Java objects as values in a Map event via the nested property syntax. Thus Map events can be used to aggregate multiple data structures into a single event and query the composite information in a convenient way. The example below demonstrates a Map event with a transaction and an account object.

Map event = new HashMap();
event.put("txn", txn);
event.put("account", account);
epRuntime.sendEvent(event, "TxnEvent");

An example statement could look as follows.

select account.id, account.rate * txn.amount 
from TxnEvent.win:time(60 sec) 
group by account.id

Your Map event type may declare one or more supertypes when configuring the type at engine initialization time or at runtime through the administrative interface.

Supertypes of a Map event type must also be Map event types. All property names and types of a supertype are also available on a subtype and override such same-name properties of the subtype. In addition, anywhere within EPL that an event type name of a Map supertype is used, any of its Map subtypes also matches that expression (similar to the concept of interface in Java).

This example assumes that the BaseUpdate event type has been declared and acts as a supertype to the AccountUpdate event type (both Map event types):

epService.getEPAdministrator().getConfiguration().
    addEventType("AccountUpdate", accountUpdateDef, 
    new String[] {"BaseUpdate"});

Your application EPL statements may select BaseUpdate events and receive both BaseUpdate and AccountUpdate events, as well as any other subtypes of BaseUpdate and their subtypes.

// Receive BaseUpdate and any subtypes including subtypes of subtypes
select * from BaseUpdate

Your application Map event type may have multiple supertypes. The multiple inheritance hierarchy between Maps can be arbitrarily deep, however cyclic dependencies are not allowed. If using runtime configuration, supertypes must exist before a subtype to a supertype can be added.

See Section 16.4.2, “Events represented by java.util.Map” for more information on configuring Map event types.

Strongly-typed nested Map-within-Map events can be used to build rich, type-safe event types on the fly. Use the addEventType method on Configuration or ConfigurationOperations for initialization-time and runtime-time type definition, or the create schema EPL syntax.

Noteworthy points are:

For demonstration, in this example our top-level event type is an AccountUpdate event, which has an UpdatedFieldType structure as a property. Inside the UpdatedFieldType structure the example defines various fields, as well as a property by name 'history' that holds a JavaBean class UpdateHistory to represent the update history for the account. The code snippet to define the event type is thus:

Map<String, Object> updatedFieldDef = new HashMap<String, Object>();
updatedFieldDef.put("name", String.class);
updatedFieldDef.put("addressLine1", String.class);
updatedFieldDef.put("history", UpdateHistory.class);
epService.getEPAdministrator().getConfiguration().
    addEventType("UpdatedFieldType", updatedFieldDef);

Map<String, Object> accountUpdateDef = new HashMap<String, Object>();
accountUpdateDef.put("accountId", long.class);
accountUpdateDef.put("fields", "UpdatedFieldType");	
// the latter can also be:  accountUpdateDef.put("fields", updatedFieldDef);

epService.getEPAdministrator().getConfiguration().
    addEventType("AccountUpdate", accountUpdateDef);

The next code snippet populates a sample event and sends the event into the engine:

Map<String, Object> updatedField = new HashMap<String, Object>();
updatedField.put("name", "Joe Doe");
updatedField.put("addressLine1", "40 Popular Street");
updatedField.put("history", new UpdateHistory());

Map<String, Object> accountUpdate = new HashMap<String, Object>();
accountUpdate.put("accountId", 10009901);
accountUpdate.put("fields", updatedField);

epService.getEPRuntime().sendEvent(accountUpdate, "AccountUpdate");

Last, a sample query to interrogate AccountUpdate events is as follows:

select accountId, fields.name, fields.addressLine1, fields.history.lastUpdate
from AccountUpdate

To model repeated properties within a Map, you may use arrays as properties in a Map. You may use an array of primitive types or an array of JavaBean objects or an array of a previously declared Map or object-array event type.

When using a previously declared Map event type as an array property, the literal [] must be appended after the event type name.

This following example defines a Map event type by name Sale to hold array properties of the various types. It assumes a SalesPerson Java class exists and a Map event type by name OrderItem was declared:

Map<String, Object> sale = new HashMap<String, Object>();
sale.put("userids", int[].class);
sale.put("salesPersons", SalesPerson[].class);
sale.put("items", "OrderItem[]");	 // The property type is the name itself appended by []

epService.getEPAdministrator().getConfiguration().
    addEventType("SaleEvent", sale);

The three properties that the above example declares are:

The next EPL statement is a sample query asking for property values held by arrays:

select userids[0], salesPersons[1].name, 
    items[1], items[1].price.amount from SaleEvent

An event can also be represented by an array of objects. Event properties of Object[] events are the array element values.

Similar to the Map event type, the object-array event type takes part in the comprehensive type system that can eliminate the need to use Java classes as event types, thereby making it easier to change types at runtime or generate type information from another source.

A given Object-array event type can have only a single supertype that must also be an Object-array event type. All properties available on the Object-array supertype is also available on the type itself. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes and their subtypes match that expression.

Your application can add properties to an existing Object-array event type during runtime using the configuration operation updateObjectArrayEventType. Properties may not be updated or deleted - properties can only be added, and nested properties can be added as well. The runtime configuration also allows removing Object-array event types and adding them back with new type information.

After your application configures an Object-array event type by providing a type name, the type name can be used when defining further Object-array or Map event types by specifying the type name as a property type or an array property type.

One-to-Many relationships in Object-array event types are represented via arrays. A property in an Object-array event type may be an array of primitive, an array of Java object, an array of Map or an array of Object-array.

The engine can process Object[] events via the sendEvent(Object[] array, String eventTypeName) method on the EPRuntime interface. Entries in the Object array represent event properties.

The engine does not validate Object array length or value types. Your application must ensure that Object array values match the declaration of the event type: The type and position of property values must match property names and types in the same exact order and object array length must match the number of properties declared via create schema or the static or runtime configuration.

Object-array event properties can be of any type. Object-array event properties that are Java application objects or that are of type java.util.Map (or arrays thereof) or that are of type Object-array (or arrays thereof) offer additional power:

In order to use Object[] (object-array) events, the event type name and property names and types, in a well-defined order that must match object-array event properties, must be made known to the engine via configuration or create schema EPL syntax. Please see examples in Section 5.15, “Declaring an Event Type: Create Schema” and Section 16.4.3, “Events represented by Object[] (Object-array)”.

The code snippet below defines an Object-array event type, creates an Object-array event and sends the event into the engine. The sample defines the CarLocUpdateEvent event type via the runtime configuration interface (create schema or static configuration could have been used instead).

// Define CarLocUpdateEvent event type (example for runtime-configuration interface)
String[] propertyNames = {"carId", "direction"};   // order is important
Object[] propertyTypes = {String.class, int.class};  // type order matches name order

epService.getEPAdministrator().getConfiguration().
  addEventType("CarLocUpdateEvent", propertyNames, propertyTypes);

The CarLocUpdateEvent can now be used in a statement:

select carId from CarLocUpdateEvent.win:time(1 min) where direction = 1
// Send an event
Object[] event = {carId, direction};
epRuntime.sendEvent(event, "CarLocUpdateEvent");

The engine can also query Java objects as values in an Object[] event via the nested property syntax. Thus Object[] events can be used to aggregate multiple data structures into a single event and query the composite information in a convenient way. The example below demonstrates a Object[] event with a transaction and an account object.

epRuntime.sendEvent(new Object[] {txn, account}, "TxnEvent");

An example statement could look as follows:

select account.id, account.rate * txn.amount 
from TxnEvent.win:time(60 sec) 
group by account.id

Your Object[] (object-array) event type may declare one supertype when configuring the type at engine initialization time or at runtime through the administrative interface.

The supertype of a Object[] event type must also be an object-array event type. All property names and types of a supertype are also available on a subtype and override such same-name properties of the subtype. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes also matches that expression (similar to the concept of interface or superclass).

The properties provided by the top-most supertype must occur first in the object array. Subtypes each append to the object array. The number of values appended must match the number of properties declared by the subtype.

For example, assume your application declares the following two types:

create objectarray schema SuperType (p0 string)
create objectarray schema SubType (p1 string) inherits SuperType

The object array event objects that your application can send into the engine are shown by the next code snippet:

epRuntime.sendEvent(new Object[] {"p0_value", "p1_value"}, "SubType");
epRuntime.sendEvent(new Object[] {"p0_value"}, "SuperType");

Strongly-typed nested Object[]-within-Object[] events can be used to build rich, type-safe event types on the fly. Use the addEventType method on Configuration or ConfigurationOperations for initialization-time and runtime-time type definition, or the create schema EPL syntax.

Noteworthy points are:

For demonstration, in this example our top-level event type is an AccountUpdate event, which has an UpdatedFieldType structure as a property. Inside the UpdatedFieldType structure the example defines various fields, as well as a property by name 'history' that holds a JavaBean class UpdateHistory to represent the update history for the account. The code snippet to define the event type is thus:

String[] propertyNamesUpdField = {"name", "addressLine1", "history"};
Object[] propertyTypesUpdField = {String.class, String.class, UpdateHistory.class};
epService.getEPAdministrator().getConfiguration().
    addEventType("UpdatedFieldType", propertyNamesUpdField, propertyTypesUpdField);

String[] propertyNamesAccountUpdate = {"accountId", "fields"};
Object[] propertyTypesAccountUpdate = {long.class, "UpdatedFieldType"};
epService.getEPAdministrator().getConfiguration().
    addEventType("AccountUpdate", propertyNamesAccountUpdate, propertyTypesAccountUpdate);

The next code snippet populates a sample event and sends the event into the engine:

Object[] updatedField = {"Joe Doe", "40 Popular Street", new UpdateHistory()};
Object[] accountUpdate = {10009901, updatedField};

epService.getEPRuntime().sendEvent(accountUpdate, "AccountUpdate");

Last, a sample query to interrogate AccountUpdate events is as follows:

select accountId, fields.name, fields.addressLine1, fields.history.lastUpdate
from AccountUpdate

To model repeated properties within an Object-array, you may use arrays as properties in an Object-array. You may use an array of primitive types or an array of JavaBean objects or an array of a previously declared Object-array or Map event type.

When using a previously declared Object-array event type as an array property, the literal [] must be appended after the event type name.

This following example defines an Object-array event type by name Sale to hold array properties of the various types. It assumes a SalesPerson Java class exists and an Object-array event type by name OrderItem was declared:

String[] propertyNames = {"userids", "salesPersons", "items"};
Object[] propertyTypes = {int[].class, SalesPerson[].class, "OrderItem[]");

epService.getEPAdministrator().getConfiguration().
    addEventType("SaleEvent", propertyNames, propertyTypes);

The three properties that the above example declares are:

The next EPL statement is a sample query asking for property values held by arrays:

select userids[0], salesPersons[1].name, 
    items[1], items[1].price.amount from SaleEvent

Events can be represented as org.w3c.dom.Node instances and send into the engine via the sendEvent method on EPRuntime or via EventSender. Please note that configuration is required so the event type name and root element name is known. See Chapter 16, Configuration.

If a XML schema document (XSD file) can be made available as part of the configuration, then Esper can read the schema and appropriately present event type metadata and validate statements that use the event type and its properties. See Section 2.8.1, “Schema-Provided XML Events”.

When no XML schema document is provided, XML events can still be queried, however the return type and return values of property expressions are string-only and no event type metadata is available other than for explicitly configured properties. See Section 2.8.2, “No-Schema-Provided XML Events”.

In all cases Esper allows you to configure explicit XPath expressions as event properties. You can specify arbitrary XPath functions or expressions and provide a property name and type by which result values will be available for use in EPL statements. See Section 2.8.3, “Explicitly-Configured Properties”.

Nested, mapped and indexed event properties are also supported in expressions against org.w3c.dom.Node events. Thus XML trees can conveniently be interrogated via the property expression syntax.

Only one event type per root element name may be configured. The engine recognizes each event by its root element name or you may use EventSender to send events.

This section uses the following XML document as an example:

<?xml version="1.0" encoding="UTF-8"?>
<Sensor xmlns="SensorSchema">
  <ID>urn:epc:1:4.16.36</ID>
  <Observation Command="READ_PALLET_TAGS_ONLY">
    <ID>00000001</ID>
    <Tag>
      <ID>urn:epc:1:2.24.400</ID>
    </Tag>
    <Tag>
      <ID>urn:epc:1:2.24.401</ID>
    </Tag>
  </Observation>
</Sensor>

The schema for the example is:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="Sensor">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ID" type="xs:string"/>
        <xs:element ref="Observation" />
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name="Observation">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ID" type="xs:string"/>
        <xs:element ref="Tag" maxOccurs="unbounded" />
      </xs:sequence>
      <xs:attribute name="Command" type="xs:string" use="required" />
    </xs:complexType>
  </xs:element>

  <xs:element name="Tag">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="ID" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

If you have a XSD schema document available for your XML events, Esper can interrogate the schema. The benefits are:

The engine reads a XSD schema file from an URL you provide. Make sure files imported by the XSD schema file can also be resolved.

The configuration accepts a schema URL. This is a sample code snippet to determine a schema URL from a file in classpath:

URL schemaURL = this.getClass().getClassLoader().getResource("sensor.xsd");

Here is a sample use of the runtime configuration API, please see Chapter 16, Configuration for further examples.

epService = EPServiceProviderManager.getDefaultProvider();
ConfigurationEventTypeXMLDOM sensorcfg = new ConfigurationEventTypeXMLDOM();
sensorcfg.setRootElementName("Sensor");
sensorcfg.setSchemaResource(schemaURL.toString());
epService.getEPAdministrator().getConfiguration()
    .addEventType("SensorEvent", sensorcfg);

You must provide a root element name. This name is used to look up the event type for the sendEvent(org.w3c.Node node) method. An EventSender is a useful alternative method for sending events if the type lookup based on the root or document element name is not desired.

After adding the event type, you may create statements and send events. Next is a sample statement:

select ID, Observation.Command, Observation.ID, 
  Observation.Tag[0].ID, Observation.Tag[1].ID
from SensorEvent

As you can see from the example above, property expressions can query property values held in the XML document's elements and attributes.

There are multiple ways to obtain a XML DOM document instance from a XML string. The next code snippet shows how to obtain a XML DOM org.w3c.Document instance:

InputSource source = new InputSource(new StringReader(xml));
DocumentBuilderFactory builderFactory = DocumentBuilderFactory.newInstance();
builderFactory.setNamespaceAware(true);
Document doc = builderFactory.newDocumentBuilder().parse(source);

Send the org.w3c.Node or Document object into the engine for processing:

epService.getEPRuntime().sendEvent(doc);

By default, property expressions such as Observation.Tag[0].ID are evaluated by a fast DOM-walker implementation provided by Esper. This DOM-walker implementation is not namespace-aware.

Should you require namespace-aware traversal of the DOM document, you must set the xpath-property-expr configuration option to true (default is false). This flag causes Esper to generate namespace-aware XPath expressions from each property expression instead of the DOM-walker, as described next. Setting the xpath-property-expr option to true requires that you also configure namespace prefixes as described below.

When matching up the property names with the XSD schema information, the engine determines whether the attribute or element provides values. The algorithm checks attribute names first followed by element names. It takes the first match to the specified property name.

By setting the xpath-property-expr option the engine rewrites each property expression as an XPath expression, effectively handing the evaluation over to the underlying XPath implementation available from classpath. Most JVM have a built-in XPath implementation and there are also optimized, fast implementations such as Jaxen that can be used as well.

Set the xpath-property-expr option if you need namespace-aware document traversal, such as when your schema mixes several namespaces and element names are overlapping.

The below table samples several property expressions and the XPath expression generated for each, without namespace prefixes to keep the example simple:



For mapped properties that are specified via the syntax name('key'), the algorithm looks for an attribute by name id and generates a XPath expression as mapped[@id='key'].

Finally, here is an example that includes all different types of properties and their XPath expression equivalent in one property expression:

select nested.mapped('key').indexed[1].attribute from MyEvent

The equivalent XPath expression follows, this time including n0 as a sample namespace prefix:

/n0:rootelement/n0:nested/n0:mapped[@id='key']/n0:indexed[position() = 2]/@attribute

When providing a XSD document, the default configuration allows to transpose property values that are themselves complex elements, as defined in the XSD schema, into a new stream. This behavior can be controlled via the flag auto-fragment.

For example, consider the next query:

insert into ObservationStream
select ID, Observation from SensorEvent

The Observation as a property of the SensorEvent gets itself inserted into a new stream by name ObservationStream. The ObservationStream thus consists of a string-typed ID property and a complex-typed property named Observation, as described in the schema.

A further statement can use this stream to query:

select Observation.Command, Observation.Tag[0].ID from ObservationStream

Before continuing the discussion, here is an alternative syntax using the wildcard-select, that is also useful:

insert into TagListStream
select ID as sensorId, Observation.* from SensorEvent

The new TagListStream has a string-typed ID and Command property as well as an array of Tag properties that are complex types themselves as defined in the schema.

Next is a sample statement to query the new stream:

select sensorId, Command, Tag[0].ID from TagListStream

Please note the following limitations:

Esper automatically registers a new event type for transposed properties. It generates the type name of the new XML event type from the XML event type name and the property names used in the expression. The synposis is type_name.property_name[.property_name...]. The type name can be looked up, for example for use with EventSender or can be created in advance.

Regardless of whether or not you provide a XSD schema for the XML event type, you can always fall back to configuring explicit properties that are backed by XPath expressions.

For further documentation on XPath, please consult the XPath standard or other online material. Consider using Jaxen or Apache Axiom, for example, to provide faster XPath evaluation then your Java VM built-in XPath provider may offer.

Shown below is an example configuration that adds an explicit property backed by a XPath expression and that defines namespace prefixes:

epService = EPServiceProviderManager.getDefaultProvider();
ConfigurationEventTypeXMLDOM sensorcfg = new ConfigurationEventTypeXMLDOM();
sensorcfg.addXPathProperty("countTags", "count(/ss:Sensor/ss:Observation/ss:Tag)", 
    XPathConstants.NUMBER);
sensorcfg.addNamespacePrefix("ss", "SensorSchema");
sensorcfg.setRootElementName("Sensor");
epService.getEPAdministrator().getConfiguration()
    .addEventType("SensorEvent", sensorcfg);

The countTags property is now available for querying:

select countTags from SensorEvent

The XPath expression count(...) is a XPath built-in function that counts the number of nodes, for the example document the result is 2.

Esper can parse or cast the result of your XPath expression to the desired type. Your property configuration provides the type to cast to, like this:

sensorcfg.addXPathProperty("countTags", "count(/ss:Sensor/ss:Observation/ss:Tag)", 
    XPathConstants.NUMBER, "int");

The type supplied to the property configuration must be one of the built-in types. Arrays of built-in type are also possible, requiring the XPathConstants.NODESET type returned by your XPath expression, as follows:

sensorcfg.addXPathProperty("idarray", "//ss:Tag/ss:ID", 
    XPathConstants.NODESET, "String[]");

The XPath expression //ss:Tag/ss:ID returns all ID nodes under a Tag node, regardless of where in the node tree the element is located. For the example document the result is 2 array elements urn:epc:1:2.24.400 and urn:epc:1:2.24.40.

An explicit property may return XPathConstants.NODE or XPathConstants.NODESET and can provide the event type name of a pre-configured event type for the property. The method name to add such properties is addXPathPropertyFragment.

This code snippet adds two explicit properties and assigns an event type name for each property:

sensorcfg.addXPathPropertyFragment("tagOne", "//ss:Tag[position() = 1]", 
    XPathConstants.NODE, "TagEvent");
sensorcfg.addXPathPropertyFragment("tagArray", "//ss:Tag", 
    XPathConstants.NODESET, "TagEvent");

The configuration above references the TagEvent event type. This type must also be configured. Prefix the root element name with "//" to cause the lookup to search the nested schema elements for the definition of the type:

ConfigurationEventTypeXMLDOM tagcfg = new ConfigurationEventTypeXMLDOM();
tagcfg.setRootElementName("//Tag");
tagcfg.setSchemaResource(schemaURL);
epAdministrator.getConfiguration()
    .addEventType("TagEvent", tagcfg);

The tagOne and tagArray properties are now ready for selection and transposing to further streams:

insert into TagOneStream select tagOne.* from SensorEvent

Select from the new stream:

select ID from TagOneStream

An example with indexed properties is shown next:

insert into TagArrayStream select tagArray as mytags from SensorEvent

Select from the new stream:

select mytags[0].ID from TagArrayStream

Part of the extension and plug-in features of Esper is an event representation API. This set of classes allow an application to create new event types and event instances based on information available elsewhere, statically or dynamically at runtime when EPL statements are created. Please see Section 18.8, “Event Type And Event Object” for details.

Creating a plug-in event representation can be useful when your application has existing Java classes that carry event metadata and event property values and your application does not want to (or cannot) extract or transform such event metadata and event data into one of the built-in event representations (POJO Java objects, Map, Object-array or XML DOM).

Further use of a plug-in event representation is to provide a faster or short-cut access path to event data. For example, access to event data stored in a XML format through the Streaming API for XML (StAX) is known to be very efficient. A plug-in event representation can also provide network lookup and dynamic resolution of event type and dynamic sourcing of event instances.

Currently, EsperIO provides the following additional event representations:

  • Apache Axiom: Streaming API for XML (StAX) implementation

Please see the EsperIO documentation for details on the above.

The chapter on Section 18.8, “Event Type And Event Object” explains how to create your own custom event representation.

To summarize, an event is an immutable record of a past occurrence of an action or state change, and event properties contain useful information about an event.

The length of time an event is of interest to the event processing engine (retention time) depends on your EPL statements, and especially the data window, pattern and output rate limiting clauses of your statements.

During the retention time of an event more information about the event may become available, such as additional properties or changes to existing properties. Esper provides three concepts for handling updates to events.

The first means to handle updating events is the update istream clause as further described in Section 5.20, “Updating an Insert Stream: the Update IStream Clause”. It is useful when you need to update events as they enter a stream, before events are evaluated by any particular consuming statement to that stream.

The second means to update events is the on-merge and on-update clauses, for use with tables and named windows only, as further described in Section 6.8, “Triggered Upsert using the On-Merge Clause” and Section 6.6, “Updating Data: the On Update clause”. On-merge is similar to the SQL merge clause and provides what is known as an "Upsert" operation: Update existing events or if no existing event(s) are found then insert a new event, all in one atomic operation provided by a single EPL statement. On-update can be used to update individual properties of rows held in a table or named window.

The third means to handle updating events is the revision event types, for use with named windows only, as further described in Section 6.11, “Versioning and Revision Event Type Use with Named Windows”. With revision event types one can declare, via configuration only, multiple different event types and then have the engine present a merged event type that contains a superset of properties of all merged types, and have the engine merge events as they arrive without additional EPL statements.

Note that patterns do not reflect changes to past events. For the temporal nature of patterns, any changes to events that were observed in the past do not reflect upon current pattern state.

The insert into clause can populate instantiate new instances of Java object events, java.util.Map events and Object[] (object array) events directly from the results of select clause expressions and populate such instances. Simply use the event type name as the stream name in the insert into clause as described in Section 5.10, “Merging Streams and Continuous Insertion: the Insert Into Clause”.

If instead you have an existing instance of a Java object returned by an expression, such as a single-row function or static method invocation for example, you can transpose that expression result object to a stream. This is described further in Section 5.10.7, “Transposing an Expression Result” and Section 10.4, “Select-Clause transpose Function”.

The column names specified in the select and insert into clause must match available writable properties in the event object to be populated (the target event type). The expression result types of any expressions in the select clause must also be compatible with the property types of the target event type.

If populating a POJO-based event type and the class provides a matching constructor, the expression result types of expressions in the select clause must be compatible with the constructor parameters in the order listed by the constructor. The insert into clause column names are not relevant in this case.

Consider the following example statement:

insert into com.mycompany.NewEmployeeEvent 
select fname as firstName, lname as lastName from HRSystemEvent

The above example specifies the fully-qualified class name of NewEmployeeEvent. The engine instantianes NewEmployeeEvent for each result row and populates the firstName and lastName properties of each instance from the result of select clause expressions. The HRSystemEvent in the example is assumed to have lname and fname properties, and either setter-methods and a default constructor, or a matching constructor.

Note how the example uses the as-keyword to assign column names that match the property names of the NewEmployeeEvent target event. If the property names of the source and target events are the same, the as-keyword is not required.

The next example is an alternate form and specifies property names within the insert into clause instead. The example also assumes that NewEmployeeEvent has been defined or imported via configuration since it does not specify the event class package name:

insert into NewEmployeeEvent(firstName, lastName) 
select fname, lname from HRSystemEvent

Finally, this example populates HRSystemEvent events. The example populates the value of a type property where the event has the value 'NEW' and populates a new event object with the value 'HIRED', copying the fname and lname property values to the new event object:

insert into HRSystemEvent 
select fname, lname, 'HIRED' as type from HRSystemEvent(type='NEW')

The matching of the select or insert into-clause column names to target event type's property names is case-sensitive. It is allowed to only populate a subset of all available columns in the target event type. Wildcard (*) is also allowed and copies all fields of the events or multiple events in a join.

For Java object events, your event class must provide setter-methods according to JavaBean conventions or, alternatively, a matching constructor. If the event class provides setter methods the class should also provide a default constructor taking no parameters. If the event class provides a matching constructor there is no need for setter-methods. If your event class does not have a default constructor and setter methods, or a matching constructor, your application may configure a factory method via ConfigurationEventTypeLegacy. If your event class does not have a default constructor and there is no factory method provided, the engine uses in connection with the Oracle JVM the sun.reflect.ReflectionFactory, noting that in this case member variables do not get initialized to assigned defaults.

The engine follows Java standards in terms of widening, performing widening automatically in cases where widening type conversion is allowed without loss of precision, for both boxed and primitive types and including BigInteger and BigDecimal.

When inserting array-typed properties into a Java, Map-type or Object-array underlying event the event definition should declare the target property as an array.

Please note the following limitations:

  • Event types that utilize XML org.w3c.dom.Node underlying event objects cannot be target of an insert into clause.

Each of the event representations of Java object, Map and XML document has advantages and disadvantages that are summarized in the table below: