13 Configuring Event Record and Playback

This section contains information on the following subjects:

Section 13.1, "Overview of Configuring Event Record and Playback"
Section 13.2, "Configuring Event Record and Playback in Your Application"
Section 13.3, "Creating a Custom Event Store Provider"

13.1 Overview of Configuring Event Record and Playback

Oracle CEP event repository feature allows you to persist the events that flow out of a component of the event processing network (EPN) to a store, such as a database table, and then play them back at a later stage or explicitly query the events from a component such as an event bean.

A typical use case of this feature is the ability to debug a problem with a currently running application. If you have been recording the events at a node in the EPN when the problem occurred, you can later playback the same list of events to recreate the problem scenario for debugging purposes.

The following graphic shows the EPN of the Event Record and Playback example and demonstrates at what point events are recorded and where they are played back. The simpleEventSource adapter has been configured to record events; as indicated, the record happens as events flow out of the adapter. The eventStream channel has been configured to playback events; as indicated, the playback happens at the point where events flow into the channel.

Figure 13-1 Configuring Record and Playback in an EPN

Description of "Figure 13-1 Configuring Record and Playback in an EPN"

13.1.1 Storing Events in the Persistent Event Store

Oracle CEP provides an RDBMS-based implementation of the event store; this implementation stores data in a relational database. You can use either the database server included with Oracle CEP (Apache Derby) or another database server, such as Oracle DBMS.

Oracle CEP includes a default database server, Apache Derby (see http://db.apache.org/derby/index.html), that you can use to record events. Apache Derby is an open source relational database implemented entirely in Java. By default, Derby creates its database files and log file (derby.log) from the directory in which you started Oracle CEP, such as DOMAIN_DIR/servername. You can change this default location by setting the system property derby.system.home to a different directory.

You can also create a custom event store provider to store events in a non-RDBMS persistent store. For details, see Section 13.3, "Creating a Custom Event Store Provider."

13.1.2 Recording Events

You can configure recording for any component in the event processing network (EPN) that produces events: processors, adapters, streams, and event beans. Processors and streams always produce events; adapters and event beans must implement the EventSource interface. Additionally, you can configure that events from different components in the EPN be stored in different persistent stores, or that all events go to the same store. Note that only events that are outputted by the component are recorded.

You enable the recording of events for a component by updating its configuration file and adding the record-parameters element. Using the child elements of record-parameters, you specify the event store to which the events are recorded, an initial time period when recording should take place, the list of event types you want to store, and so on.

After you deploy the application and events start flowing through the network, recording begins either automatically because you configured it to start at a certain time or because you dynamically start it using administration tools. For each component you have configured for recording, Oracle CEP stores the events that flow out of it to the appropriate store along with a timestamp of the time it was recorded.

13.1.3 Playing Back Events

You can configure playback for any component in the event processing network (EPN): processors, adapters, streams, and event beans. Typically the playback component is a node later in the network than the node that recorded the events.

You enable the playback of events for a component by updating its configuration file and adding the playback-parameters element. Using the child elements of playback-parameters, you specify the event store from which the events are played back, the list event types you want to play back (by default all are played back), the time range of the recorded events you want to play back, and so on. By default, Oracle CEP plays back the events in a time accurate manner; however, you can also configure that the events get played back either faster or slower than they originally flowed out of the component from which they were recorded.

After you deploy the application and events start flowing through the network, you must start the playback by using the administration tools (Oracle CEP Visualizer or wlevs.Admin). Oracle CEP reads the events from the appropriate persistent store and inserts them into the appropriate place in the EPN.

It is important to note that when a component gets a playback event, it looks exactly like the original event. Additionally, a component later in the network has been configured to record events, then Oracle CEP records the playback events as well as the "real" events.

For more information, see:

"Recording and Playing Back Events Flowing Through an EPN" in the Oracle CEP Visualizer User's Guide
"Commands for Controlling Event Record and Playback" in the Oracle CEP Administrator's Guide

13.1.4 Querying Stored Events

You can use the event store API to query a store for past events given a record time range and the component from which the events were recorded. The actual query you use depends on the event repository provider; for example, you would use Oracle CQL or EPL for the RDBMS provider included in Oracle CEP. You can also use these APIs to delete old events from the event store.

13.1.5 Restrictions on the Event Types that Can Be Recorded

In this release, the following restrictions apply to the event types that can be recorded to the event store if you use the Oracle RDBMS-based provider:

The fields of the event type must be simple data types. In other words, the fields cannot be complex types such as arrays, java.util.Map, or nested objects.
The simple fields must be one of the supported Java types, as listed in Table 13-3.

13.1.6 Record and Playback Example

The sample code in this section is taken from the event record and playback example, located in the ORACLE_CEP_HOME\ocep_11.1\samples\source\applications\recplay directory, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as d:\oracle_cep.

For details about running and building the example, see "Event Record and Playback Example" in the Oracle CEP Getting Started.

13.2 Configuring Event Record and Playback in Your Application

Depending on how you are going to use the event repository, there are different tasks that you must perform, as described in the following procedure that in turn point to sections with additional details.

Note:

It is assumed in this section that you have already created an Oracle CEP application along with component configuration file(s) for the components and that you want to update the application so that components record or playback events. If you have not, refer to Chapter 1, "Overview of Creating Oracle CEP Applications," for details.

To configure record and playback of events in your application:

Configure an event store for your Oracle CEP server instance.

You must perform this configuration step even if you plan to use the event store provider provided by Oracle CEP, Apache Derby (see http://db.apache.org/derby/index.html).

See Section 13.2.1, "Configuring an Event Store for Oracle CEP Server."
Configure a component in your EPN to record events by updating the component's configuration file.

The component can be a processor, adapter, channel, or event bean. Only events flowing out of the component are recorded.

See Section 13.2.2, "Configuring a Component to Record Events."
Configure a component in your EPN to playback events by updating the component's configuration file.

The component can be a processor, adapter, channel, or event bean. Only components that are also event sinks can playback events; events are played to the input side of the component.

See Section 13.2.3, "Configuring a Component to Playback Events."
Redeploy your application for the changes to take effect.
If you have not specified an explicit start and end time for recording events, you must use Oracle CEP Visualizer or wlevs.Admin to start recording. You must always use these administration tools to start and end the playback of events.

See Section 13.2.4, "Starting and Stopping the Record and Playback of Events."

13.2.1 Configuring an Event Store for Oracle CEP Server

Oracle CEP stores recorded events in a database, which means that before you can start using the record and playback feature in your own application, you must specify where the database server is located along with the name of the database server that will contain the recorded events. You do this by updating the config.xml file of your Oracle CEP server instance, as described in later procedures.

You do not, however, create the actual tables that store the recorded events; Oracle CEP automatically does this for you after you deploy the application that uses the record and playback feature and recording starts to take place. See Section 13.2.5, "Description of the Database Tables Created by the RDMBS Provider" for information about how Oracle CEP creates these tables.

To configure an event store for Oracle CEP server:

Stop your Oracle CEP server instance, if it is running.
Using your favorite XML editor, open the server's config.xml file for edit.

The config.xml file is located in the DOMAIN_DIR/servername/config directory of your server, where DOMAIN_DIR refers to the domain directory, such as /oracle_cep/user_projects/domains/myDomain and servername refers to the name of your server, such as defaultserver.
Configure access to your relational database by adding a data-source element to the config.xml file.

For details, see "Configuring JDBC for Oracle CEP" in the Oracle CEP Administrator's Guide.

If you want to use the default Apache Derby database, add the following data-source element:
```
<?xml version="1.0" encoding="UTF-8"?>
<n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/server"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<domain> 
   <name>myDomain</name>
</domain>
...
<data-source>
  <name>derby1</name>
  <connection-pool-params>
    <initial-capacity>15</initial-capacity>
    <max-capacity>50</max-capacity>
  </connection-pool-params>
  <driver-params>
    <url>jdbc:derby:dbtest1;create=true</url>
    <driver-name>org.apache.derby.jdbc.EmbeddedDriver</driver-name>
  </driver-params>
</data-source>
</n1:config>
```
You can, of course, name the data source anything you want, as well as specify different connection pool parameters and database name (the sample above connects to the database dbtest1 and specifies that the database should be created if it does not already exist). The only element that must be the same as in the sample above is <driver-name>, whose value must be org.apache.derby.jdbc.EmbeddedDriver. You are required to add a <transaction-manager> element, although you can name it anything you want.

Add a transaction-manager element to the config.xml file:

<data-source>
 ...
</data-source>
<transaction-manager>
  <name>myTransactionManager</name>
</transaction-manager>

Add an rdbms-event-store-provider element to the config.xml file that in turn references the previously configured data source.

For example, to use the Apache Derby database configured in the previous step, add the following XML snippet:
```
<data-source>
  <name>derby1</name>
  ...
</data-source>
<rdbms-event-store-provider>
   <name>my-rdbms-provider</name>
   <data-source-name>derby1</data-source-name>
</rdbms-event-store-provider>
```
Later, when you configure the components that record and playback the events, you will specify the name of this event store.

Oracle CEP is now configured for an event store and you can configure specific components in your application to record or playback events.

13.2.2 Configuring a Component to Record Events

You can configure any processor, adapter, channel, or event bean in your application to record events. As with all other component configuration, you specify that a component records events by updating its configuration file. For general information about these configuration files, see Section 1.1.4, "Component Configuration Files."

This section describes the main steps to configure a component to record events. For simplicity, it is assumed in the procedure that you are configuring an adapter to record events and that you have already created its component configuration file.

See Section B.1, "Component Configuration Schema wlevs_application_config.xsd" for the complete XSD Schema that describes the event recording configuration file elements.

Using your favorite XML editor, open the component configuration XML file and add a record-parameters child element to the component you want to configure to record events. For example, to configure an adapter called simpleEventSource:

<?xml version="1.0" encoding="UTF-8"?>
  <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <adapter>
        <name>simpleEventSource</name>
        <record-parameters>
          ...
       </record-parameters>
        ...
    </adapter>
    ...
</n1:config>

Add child elements to record-parameters to specify the name of the event store provider, the events that are stored, the start and stop time for recording, and so on. For example:

<adapter>
      <name>simpleEventSource</name>
      <record-parameters>
        <dataset-name>recplay_sample</dataset-name>
        <event-type-list>
            <event-type>SimpleEvent</event-type>
        </event-type-list>
        <provider-name>my-rdbms-provider</provider-name>
        <batch-size>1</batch-size>
        <batch-time-out>10</batch-time-out>
      </record-parameters>
</adapter>

Table 13-1 lists the child elements of record-parameters that you can specify. Although only dataset-name is required, Oracle recommends that you also include provider-name to explicitly specify the name of the event store provider.

Table 13-1 Child Elements of record-parameters

Child Element	Description
`dataset-name`	Specifies the group of data that the user wants to group together. In the case of the Oracle RDBMS-based provider, it specifies the database area, or schema, in which the tables that store the recorded events are created. When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`provider-name`	Specifies the name of the event store provider. The value of this element corresponds to the value of the `name` child element of the `rdbms-event-store-provider` element in the `config.xml` file of the Oracle CEP server instance. See Section 13.2.1, "Configuring an Event Store for Oracle CEP Server." When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`event-type-list`	Specifies the event types that are recorded to the event store. If this element is not specified, then Oracle CEP records all event types that flow out of the component. Use the `event-type` child component to list all events, such as: <event-type-list> <event-type>EventOne</event-type> <event-type>EventTwo</event-type> </event-type-list> When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`time-range`	Specifies the time period during which recording should take place using a start and end time. The time period is configured by using a `start` child element to specify a start time and an `end` child element to specify the end time. The start and end time formats are both `MM-dd-yyyy:HH:mm:ss`, such as `10-20-2007:11:22:07`. For example, to specify that recording should start on April 7, 2009, at 6:00am and end on April 10, 2009, at 10:00 pm, enter the following <time-range-offset> <start>04-07-2009:06:00:00</start> <end>04-10-2009:22:00:00</end> </time-range-offset> If you do not specify a time period, then no events are recorded when the application is deployed and recording will only happen after you explicitly start it using Oracle CEP Visualizer or `wlevs.Admin`. You can specify `time-range` or `time-range-offset`, but not both.
`time-range-offset`	Specifies the time period during which recording should take place, using a start time and a duration. The time period is configured by using a `start` child element to specify a start time and `duration` child element to specify the amount of time after the start time that recording should stop. The start time format is `MM-dd-yyyy:HH:mm:ss`, such as `10-20-2007:11:22:07`. The duration format is `HH:mm:ss`, such as `01:00:00`. For example, to specify that recording should start on April 7, 2009, at 6:00am and continue for 3 hours, enter the following <time-range-offset> <start>04-07-2009:06:00:00</start> <duration>03:00:00</duration> </time-range-offset> If you do not specify a time period, then no events are recorded when the application is deployed and recording will only happen after you explicitly start it using Oracle CEP Visualizer or `wlevs.Admin`. You can specify `time-range` or `time-range-offset`, but not both.
`batch-size`	Specifies the number of events that Oracle CEP picks up in a single batch from the event buffer to write the event store. Default value is 1000.
`batch-time-out`	Specifies the number of seconds that Oracle CEP waits for the event buffer window to fill up with the `batch-size` number of events before writing to the event store. Default value is 60
`max-size`	If specified, Oracle CEP uses a stream when writing to the event store, and this element specifies the size of the stream, with non-zero values indicating asynchronous writes. Default value is 1024.
`max-threads`	If specified, Oracle CEP uses a stream when writing to the event store, and this element specifies the maximum number of threads that will be used to process events for this stream. Setting this value has no effect when `max-size` is 0. The default value is 1.
`store-policy-parameters`	Specifies policy parameters, specific to the event store provider. Use the `<name>` and `<value>` child elements to specify a particular parameter, such as: <store-policy-parameters> <name>supportsTransactions</name> <value>true</value> </store-policy-parameters>

13.2.3 Configuring a Component to Playback Events

You can configure any processor, adapter, channel, or event bean in your application to playback events, although the component must be a node downstream of the recording component so that the playback component will actually receive the events and play them back. As with all other component configuration, you specify that a component plays back events by updating its configuration file. For general information about these configuration files, see Section 1.1.4, "Component Configuration Files."

This section describes the main steps to configure a component to play back events. For simplicity, it is assumed in the procedure that you are configuring a channel to playback events from a node upstream in the EPN that has recorded events, and that you have already created the channel's configuration file.

See for the complete XSD Schema that describes the event playback configuration file elements.

Using your favorite XML editor, open the component configuration XML file and add a playback-parameters child element to the component you want to configure to playback events. For example, to configure a channel called eventStream:

<?xml version="1.0" encoding="UTF-8"?>
  <n1:config xmlns:n1="http://www.bea.com/ns/wlevs/config/application"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <channel>
      <name>eventStream</name>
      <playback-parameters>
        ...
      </playback-parameters>
    </channel>
    ...
</n1:config>

Add child elements to playback-parameters to specify the name of the event store provider, the events that are played back, and so on. For example:

    <channel>
      <name>eventStream</name>
      <playback-parameters>
          <dataset-name>recplay_sample</dataset-name>
          <event-type-list>
              <event-type>SimpleEvent</event-type>
          </event-type-list>
          <provider-name>test-rdbms-provider</provider-name>
      </playback-parameters>
    </channel>

Table 13-2 lists the child elements of playback-parameters that you can specify. Although only dataset-name is required, Oracle recommends that you also include provider-name to explicitly specify the name of the event store provider.

Table 13-2 Child Elements of playback-parameters

Child Element	Description
`dataset-name`	Specifies the group of data that the user wants to group together. In the case of the Oracle RDBMS-based provider, it specifies the database area, or schema, in which the tables that store the recorded events are queried for the playback events. When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`provider-name`	Specifies the name of the event store provider. The value of this element corresponds to the value of the `name` child element of the `rdbms-event-store-provider` element in the `config.xml` file of the Oracle CEP server instance. See Section 13.2.1, "Configuring an Event Store for Oracle CEP Server." When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`event-type-list`	Specifies the event types that are played back from the event store. If this element is not specified, then Oracle CEP plays back all event types. Use the `event-type` child component to list all events, such as: <event-type-list> <event-type>EventOne</event-type> <event-type>EventTwo</event-type> </event-type-list> When configuring the Oracle RDBMS-based provider, you are required to specify this element.
`time-range`	Specifies the time period of the recorded events that you want to play back. In other words, this element acts as a filter so that only the events recorded during the specified time period are played back. This element does not specify a time period when the playback itself occurs. The time period is configured by using a `start` child element to specify a start time and an `end` child element to specify the end time. The start and end time formats are both `MM-dd-yyyy:HH:mm:ss`, such as `10-20-2007:11:22:07`. For example, to specify that you want to playback events that were recorded starting on April 7, 2009, at 6:00am and ending on April 10, 2009, at 10:00 pm, enter the following <time-range-offset> <start>04-07-2009:06:00:00</start> <end>04-10-2009:22:00:00</end> </time-range-offset> If you do not specify a time period, then all events are played back. You can specify `time-range` or `time-range-offset`, but not both.
`time-range-offset`	Specifies the time period of the recorded events that you want to play back. In other words, this element acts as a filter so that only the events recorded during the specified time period are played back. This element does not specify a time period when the playback itself occurs. The time period is configured by using a `start` child element to specify a start time and `duration` child element to specify an amount of time after the start time. The start time format is `MM-dd-yyyy:HH:mm:ss`, such as `10-20-2007:11:22:07`. The duration format is `HH:mm:ss`, such as `01:00:00`. For example, to specify that you want to playback events that were recorded starting on April 7, 2009, at 6:00am and continued for three hours enter the following: <time-range-offset> <start>04-07-2009:06:00:00</start> <duration>03:00:00</duration> </time-range-offset> If you do not specify a time period, then all events are played back.
`playback-speed`	Specifies the playback speed as a positive float. The default value is 1, which corresponds to normal speed. A value of 2 means that events will be played back 2 times faster than the original record speed. Similarly, a value of 0.5 means that events will be played back at half the speed.
`repeat`	Specifies whether to playback events again after the playback of the specified time interval is over. Valid values are `true` and `false`. Default value is `false`. A value of `true` means that the repeat of playback continues an infinite number of times until it is deliberately stopped. `False` means that events will be played back only once.
`max-size`	If specified, Oracle CEP uses a stream when playing back events from the event store, and this element specifies the size of the stream, with non-zero values indicating asynchronous writes. Default value is 1024.
`max-threads`	If specified, Oracle CEP uses a stream when playing back events from the event store, and this element specifies the maximum number of threads that will be used to process events for this stream. Setting this value has no effect when `max-size` is 0. The default value is 1.
`store-policy-parameters`	Specifies policy parameters, specific to the event store provider. Use the `<name>` and `<value>` child elements to specify a particular parameter, such as: <store-policy-parameters> <name>supportsTransactions</name> <value>true</value> </store-policy-parameters>

13.2.4 Starting and Stopping the Record and Playback of Events

After you configure the record and playback functionality for the components of an application, and you deploy the application to Oracle CEP, the server starts to record events only if you specified an explicit start/stop time in the initial configuration.

For example, if you included the following element in a component configuration:

<time-range-offset>
    <start>04-07-2009:06:00:00</start>
    <end>04-10-2009:22:00:00</end>
</time-range-offset>

then recording will automatically start on April 7, 2009.

The only way to start the playback of events, however, is by using Oracle CEP Visualizer or wlevs.Admin. You also use these tools to dynamically start and stop the recording of events.

For more information, see:

"Recording and Playing Back Events Flowing Through an EPN" in the Oracle CEP Visualizer User's Guide
"Commands for Controlling Event Record and Playback" in the Oracle CEP Administrator's Guide

Visualizer and wlevs.Admin use managed beans (MBeans) to dynamically start and stop event recording and playback, as well as manage the event store configuration. A managed bean is a Java bean that provides a Java Management Extensions (JMX) interface. JMX is the Java EE solution for monitoring and managing resources on a network. You can create your own administration tool and use JMX to manage event store functionality by using the com.bea.wlevs.management.configuration.StageMBean.

For more information, see:

"Configuring JMX for Oracle CEP" in the Oracle CEP Administrator's Guide
Oracle CEP Java API Reference

13.2.5 Description of the Database Tables Created by the RDMBS Provider

When you enable event recording for a component, Oracle CEP automatically creates, if they do not already exist, the database tables that stores the actual data. The server connects to the database using the data source configured for the event store provider.

Oracle recommends that you allow Oracle CEP to create and manage these tables; however, if you want more control you can create your own tables.

The following guidelines describe how Oracle CEP creates the database tables, and thus the requirements if you decide to create your own tables. If the default name of a database object (schema, table, column) is a reserved word, Oracle CEP adds a suffix to come up with a non-reserved word.

Events are stored in a schema, whose name is specified by the value of the dataset-name element.
Every Java event type in the event store has a corresponding table in the schema. The name of the table is same as the name of the event type.
Every field in the Java event type has a corresponding column in the table. The name of the column is the same as the name of the field.

See Table 13-3 for the list of supported Java types for the fields of the event type.
The table contains an additional column recordTime that stores the time the event was recorded.
The table has an index on the recordTime column.

Table 13-3 Supported Java Types

Java Type	Corresponding Java SQL Type
`boolean, java.lang.Boolean`	`java.sql.Types.BIT`
`byte, java.lang.Byte`	`java.sql.Types.TINYINT`
`short, java.lang,Short`	`java.sql.Types.SMALLINT`
`int, java.lang.Integer`	`java.sql.Types.INTEGER`
`long, java.lang.Long`	`java.sql.Types.BIGINT`
`float, java.lang.Float`	`java.sql.Types.REAL`
`double, java.lang.Double`	`java.sql.Types.DOUBLE`
`java.lang.String`	`java.sql.Types.VARCHAR`
`java.math.BigDecimal`	`java.sql.Types.BIGINT`
`java.sql.Date, java.util.Date`	`java.sql.Types.TIMESTAMP`
`java.sql.Time`	`java.sql.Types.TIME`
`java.sql.Timestamp`	`java.sql.Types.TIMESTAMP`

13.3 Creating a Custom Event Store Provider

Oracle CEP provides an event store API that you can use to create a custom event store provider. Oracle provides an RDBMS-based implementation for storing events in a relational database, or one that supports JDBC connections. If you want to store events in a different kind of database, or for some reason the Oracle RDBMS provider is not adequate for your needs, then you can create your own event store provider using the event store API.

The event store API is in the com.bea.wlevs.eventstore package; the following list describes the most important interfaces:

EventStore—Object that represents a single event store. The methods of this interface allow you to persist events to the store and to query the contents of the store using a provider-specific query.
EventStoreManager—Manages event stores. Only one instance of the EventStoreManager ever exists on a given Oracle CEP server, and this instance registers itself in the OSGI registry so that event store providers can in turn register themselves with the event store manager. You use this interface to find existing event stores, create new ones, get the provider for a given event store, and register an event provider. The event store manager delegates the actual work to the event store provider.
EventStoreProvider—Underlying repository that provides event store services to clients.

For more information, see the Oracle CEP Java API Reference.