|
|
This section contains information on the following subjects:
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 stream has been configured to playback events; as indicated, the playback happens at the point where events flow into the stream.
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, 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 Creating a Custom Event Store Provider.
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.
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 (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.
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 EPL for the RDBMS provider included in Oracle CEP. You can also use these APIs to delete old events from the event store.
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:
java.util.Map, or nested objects.
The sample code in this section is taken from the recplay example, located in the ORACLE_CEP_HOME\ocep_10.3\samples\source\applications\recplay directory, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory, such as d:\oracle_cep.
See Event Record and Playback Example for details about running and building the example.
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 Overview of Creating Oracle Complex Event Processing Applications for details. |
See Configuring an Event Store for Oracle CEP Server.
See Configuring a Component to Store Events.
See Configuring a Component to Playback Events.
wlevs.Admin to start recording. You must always use these administration tools to start and end the playback of events.See Starting and Stopping the Record and Playback of Events.
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 Description of the Database Tables Created by the RDMBS Provider for information about how Oracle CEP creates these tables.
To configure Oracle CEP for an event store, including the default Apache Derby, follow these steps:
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. <data-source> element to the config.xml file. For details, see
Configuring Access to a Relational Database.
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.
<transaction-manager> element to the config.xml file:<data-source>
...
</data-source>
<transaction-manager>
<name>myTransactionManager</name>
</transaction-manager><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.
You can configure any processor, adapter, stream, 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 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 XSD Schema Reference for Component Configuration Files 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></adapter>
...
</record-parameters>
...
...
</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></adapter>
<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>
The following table 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.
You can configure any processor, adapter, stream, 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 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 stream to playback events from a node upstream in the EPN that has recorded events, and that you have already created the stream’s configuration file.
See XSD Schema Reference for Component Configuration Files 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 stream 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">
<stream>
<name>eventStream</name><playback-parameters></stream>
...
</playback-parameters>
...
</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:
<stream>
<name>eventStream</name><playback-parameters></stream>
<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>
The following table 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.
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 Visualizer or wlevs.Admin. You also use these tools to dynamically start and stop the recording of events. For details, see:
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.
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.
<dataset-name> element. recordTime that stores the time the event was recorded.recordTime column.The following table lists the supported Java types that can be fields of the event type.
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.
|