Getting Started Guide

Oracle CEP Examples

This section contains information on the following subjects:

Overview of the Samples Provided in the Distribution Kit

Oracle Complex Event Processing, or Oracle CEP for short, includes four complete examples: HelloWorld, which is a basic skeleton of a a typical Oracle CEP application, a Foreign Exchange (FX) example that includes a multiple components, a Signal Generation example that simulates market trading and trend detection, and a record/playback example that shows how to configure event record and playback using a persistent event store.

These examples are provided in two forms, as follows:

The samples use Ant as their development tool; for details about Ant and installing it on your computer, see the Apache Ant Project.

Installing the Examples

When initially installing Oracle CEP, you must chose the Custom option to also install the examples. The Typical option does not include the examples.

If you previously installed Oracle CEP using the Typical option, and you now want to also install the examples, re-run the Oracle CEP installation process and specify the same Oracle CEP home directory; a later step in the installation process allows you to then install just the examples.

Using Visualizer With the Examples

Oracle CEP Visualizer, or Visualizer for short, is a Web 2.0 application that consumes data from Oracle CEP, displays it in a useful and intuitive way to system administrators and operators, and, for specificied tasks, accepts data that is then passed back to Oracle CEP so as to change it configuration.

Visualizer is itself an Oracle CEP application and is automatically deployed in each server instance. To use it with the examples, be sure you have started the server (instructions provided for each examples below) and then invoke the following URL in your browser:

   http://host:9002

where host refers to the name of the computer hosting Oracle CEP; if it is the same as the computer on which the browser is running you can use localhost.

Security is disabled for the HelloWorld application, so you can click Logon at the login screen without entering a username and password. For the FX and signal generation examples, however, security is enabled, so use the following to logon:

User Id: wlevs
Password: wlevs

For more information about Visualizer, see Overview of Visualizer.

Increasing the Performance of the Examples

To increase the throughput and latency when running the examples, and Oracle CEP applications in general, Oracle recommends the following:

Setting Your Development Environment

You must set your development environment before you can start Oracle CEP instances and run the examples. In particular, you must set the PATH and JAVA_HOME environment variables so that you are using the correct version of the JRockit JDK.

There are two ways in which JRockit might have been installed on your computer:

Although not required, Oracle recommends that you run Oracle CEP using the JRockit JDK version included in Oracle JRockit Real Time 3.0 for best results; however, the following procedures describe how to set your environment for either case.

Windows

To make it easier to reset your development environment after logging out of a session, you can create a command file, such as setEnv.cmd, that contains these set commands.

You can also set these environment variables permanently on your Windows computer by invoking the Control Panel > System window, clicking the Advanced tab, and then clicking the Environment Variables button. You can set the environment variables for the current user or for the entire system.

UNIX

To make it easier to reset your environment after logging out of a session, you can create a command file, such as setEnv.sh, that contains these commands.

HelloWorld Example

The first example that shows how to create an Oracle CEP application is the ubiquitous HelloWorld. The following diagram shows the components that make up the application and how they fit together, which together make up the HelloWorld event processing network:

The example includes the following components:

Running the HelloWorld Example from the helloworld Domain

To run the HelloWorld application that is pre-deployed to the helloworld domain, you simply start an instance of Oracle CEP, as described in the following steps:

After server status messages scroll by, you should see the following message printed to the output about every second:

    Message: HelloWorld - the current time is: 3:56:57 PM

This message indicates that the HelloWorld example is running correctly.

Building and Deploying the HelloWorld Example from the Source Directory

The HelloWorld sample source directory contains the Java source, along with other required resources such as configuration XML files, that make up the HelloWorld application. The build.xml Ant file contains targets to build and deploy the application to the helloworld domain; see Description of the Ant Targets to Build Hello World for details.

To build and deploy the HelloWorld application, follow these steps:

You should see the following message printed to the output about every second:

    Message: HelloWorld - the current time is: 3:56:57 PM

This message indicates that the HelloWorld example has been redeployed and is running correctly.

Description of the Ant Targets to Build Hello World

The build.xml file, located in the top level of the HelloWorld source directory, contains the following targets to build and deploy the application:

Implementation of the HelloWorld Example

The implementation of the HelloWorld example generally follows the main steps for creating an Oracle CEP application; refer to that section for a task-oriented procedure that describes the typical development process.

The HelloWorld example, because it is relatively simple, does not use all the components and configuration files described in the general procedure for creating an Oracle CEP application. All the files of the example are located relative to the ORACLE_CEP_HOME\ocep_10.3\samples\source\applications\helloworld directory, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory such as c:\oracle_cep. Oracle recommends that you use this example directory setup in your own environment, although it is obviously not required.

The files used by the HelloWorld example include:

The HelloWorld example uses a build.xml Ant file to compile, assemble, and deploy the OSGi bundle; see Building and Deploying the HelloWorld Example from the Source Directory for a description of this build.xml file if you also use Ant in your development environment.

The HelloWorld EPN Assembly File

One of the main purposes of the EPN assembly file is to define the event processing network by declaring the components of the application and how they are all connected, or in other word, which components listen to which other components. Oracle CEP provides a set of custom Spring tags used to declare the network. You also use the EPN assembly file to register the event types used by your application and its EPL rules.

You use the EPN assembly file in the typical way to define the application component beans in the Spring application context; the application components beans are those implemented with Java classes, such as adapters and the POJO that contains the business logic.

For full reference information about the custom Spring tags, see Oracle CEP Custom Spring Tags Reference or the XSD Schema file that defines the tags.

The following example shows the EPN assembly file used in the HelloWorld sample application; see the explanation after the example for details about the entries in bold.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
       xsi:schemaLocation="
  http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/osgi
  http://www.springframework.org/schema/osgi/spring-osgi.xsd
  http://www.bea.com/ns/wlevs/spring
  http://www.bea.com/ns/wlevs/spring/spring-wlevs.xsd">

    <wlevs:event-type-repository>
        <wlevs:event-type type-name="HelloWorldEvent">
            <wlevs:class>com.bea.wlevs.event.example.helloworld.HelloWorldEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>

    <wlevs:adapter id="helloworldAdapter" class="com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapter" >
        <wlevs:instance-property name="message" value="HelloWorld - the currenttime is:"/>
    </wlevs:adapter>

    <wlevs:processor id="helloworldProcessor" />

    <wlevs:stream id="helloworldInstream" >
        <wlevs:listener ref="helloworldProcessor"/>
        <wlevs:source ref="helloworldAdapter"/>
    </wlevs:stream>

    <wlevs:stream id="helloworldOutstream" manageable="true">
        <wlevs:listener>
            <bean class="com.bea.wlevs.example.helloworld.HelloWorldBean"/>
        </wlevs:listener>
        <wlevs:source ref="helloworldProcessor"/>
    </wlevs:stream>

</beans>

In the preceding example:

The HelloWorld Component Configuration File

The HelloWorld application configures the processor and one of the streams in a component configuration file as follows:

<?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">

  <processor>
    <name>helloworldProcessor</name>
    <rules>
      <rule id="helloworldRule"><![CDATA[ select * from HelloWorldEvent retain 1 event ]]></rule>
    </rules>
  </processor>

  <stream>
      <name>helloworldOutstream</name>
      <max-size>10000</max-size>
      <max-threads>2</max-threads>
  </stream>

</n1:config>

If your application contains multiple processors, adapters or streams, you can either declare them all in a single configuration file, or create separate configuration files for each component; the method you chose depends on which you find easier to manage.

For each component you configure, you must add the <name> child element to explicitly declare the specific component to which you are referring. The value of the <name> element must correspond to the component’s unique identifier of its declaration in the EPN assembly file.

For example, assume a processor is declared in the EPN assembly file as follows:

 <wlevs:processor id="helloworldProcessor" ...>

Then its corresponding XML configuration would be as follows:

 <processor>
  <name>helloworldProcessor</name>
  ...
 </processor>

The HelloWorld example uses a single configuration file for one processor with the name helloworldProcessor and one stream with the name helloworldOutstream. These names correspond with the declaration of the components in the EPN assembly file.

The <processor> element configures the processor component. The most important part of the processor configuration is the declaration of the set of Event Processing Language (EPL) rules that this processor executes; these rules select the set of events that are eventually passed to the application business object. Each rule is declared with a <rule> element using an XML ![CDATA[...]] section; all rules are grouped together with a single <rules> element. You can define as many rules as you want for a particular processor.

The HelloWorld application has just a single very simple rule:

  select * from HelloWorldEvent retain 1 event

This rule selects all events of type HelloWorldEvent, but retains only one event at a time in its window. For additional information and examples about using EPL, see the EPL Reference Guide.

The <stream> element configures the helloworldOutstream component. The <max-size> and <max-threads> elements specify the maximum size of the stream and the maximum number of threads assigned to the stream, respectively.

Foreign Exchange (FX) Example

The foreign exchange example, called FX for simplicity, is a more complex example than the HelloWorld one because it includes multiple processors that handle information from multiple data feeds. In the example, the data feeds are simulated using the Oracle CEP load generator utility. The following diagram describes the FX event processing network:

In the scenario, three data feeds, simulated using the load generator, send a constant pair of values from different parts of the world; the value pairs consist of a currency pair, such as USDEUR for US dollar - European euro, and an exchange rate between the two currencies. The fxMarketXXX adapters receive the data from the feeds, convert them into events, and pass them to the preprocessorXXX processors. Each processor performs an initial stale check to ensure that no event is more than ten seconds old and then a boundary check to ensure that the exchange rate between the two currencies is within a current boundary. The server also only selects a specific currency pair from a particular stream; for example, the server selects USDEUR from the simulated American data feed, but rejects all other pairs, such as USDAUD (Australian dollar).

After the data from each data feed provider passes this initial preparation phase, a different processor, called spreader, joins all events across all providers, calculates the mid-point between the maximum and minimum rate, and then applies a trader-specified spread. Finally, the processor forwards the rate to the POJO that contains the business code; in this example, the POJO simply publishes the rate to clients.

The Oracle CEP monitor is configured to watch if the event latency in the last step exceeds some threshold, such as no updated rates in a 30 second time-span, and if there is too much variance between two consecutive rates for the same currency pair. Finally, the last rate of each currency pair is forwarded to the dashboard.

Running the Foreign Exchange Example

For optimal demonstration purposes, Oracle recommends that you run this example on a powerful computer, such as one with multiple CPUs or a 3 GHz dual-core Intel, with a minimum of 2 GB of RAM.

To run the Foreign Exchange (FX) application that is pre-deployed to the fx_domain domain, you simply start an instance of Oracle CEP, as described in the following steps:

After the server status messages scroll by in the command window from which you started the server, and the three load generators start, you should see messages similar to the following being printed to the server command window:

{crossRate=USDJPY, internalPrice=119.09934499999781}, {crossRate=USDGBP, internalPrice=0.5031949999999915}, {crossRate=USDJPY, internalPrice=117.73945624999783}

These messages indicate that the Foreign Exchange example is running correctly. The output shows the cross rates of US dollars to Japanese yen and US dollars to UK pounds sterling.

Building and Deploying the Foreign Exchange Example from the Source Directory

The Foreign Exchange (FX) sample source directory contains the Java source, along with other required resources such as configuration XML files, that make up the FX application. The build.xml Ant file contains targets to build and deploy the application to the fx_domain domain, as described in Description of the Ant Targets to Build FX.

To build and deploy the FX application, follow these steps:

After server status messages scroll by, you should see the following message printed to the output:

    {crossRate=USDJPY, internalPrice=119.09934499999781}, {crossRate=USDGBP, internalPrice=0.5031949999999915}, {crossRate=USDJPY, internalPrice=117.73945624999783}

This message indicates that the FX example has been redeployed and is running correctly.

Description of the Ant Targets to Build FX

The build.xml file, located in the top-level directory of the FX source, contains the following targets to build and deploy the application:

Implementation of the FX Example

The implementation of the foreign exchange (FX) example generally follows the main steps for creating an Oracle CEP application; refer to that section for a procedure that describes the typical development process.

All the files of the FX example are located relative to the ORACLE_CEP_HOME\ocep_10.3\samples\source\applications\fx directory, where ORACLE_CEP_HOME refers to the main Oracle CEP installation directory such as c:\oracle_cep. Oracle recommends that you use this example directory setup in your own environment, although it is obviously not required.

The files used by the FX example include:

The FX example uses a build.xml Ant file to compile, assemble, and deploy the OSGi bundle; see Building and Deploying the Foreign Exchange Example from the Source Directory for a description of this build.xml file if you also use Ant in your development environment.

The FX EPN Assembly File

The following example shows the EPN assembly file used in the FX sample application; see the explanation after the example for details about the entries in bold.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:osgi="http://www.springframework.org/schema/osgi"
       xmlns:wlevs="http://www.bea.com/ns/wlevs/spring"
       xsi:schemaLocation="
  http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd
  http://www.springframework.org/schema/osgi
  http://www.springframework.org/schema/osgi/spring-osgi.xsd
  http://www.bea.com/ns/wlevs/spring
  http://www.bea.com/ns/wlevs/spring/spring-wlevs.xsd">

    <wlevs:event-type-repository>
        <wlevs:event-type type-name="ForeignExchangeEvent">
            <wlevs:class>com.bea.wlevs.example.fx.OutputBean$ForeignExchangeEvent</wlevs:class>
            <wlevs:property name="builderFactory">
                <bean id="builderFactory" class="com.bea.wlevs.example.fx.ForeignExchangeBuilderFactory"/>
            </wlevs:property>
        </wlevs:event-type>
    </wlevs:event-type-repository>

    <!-- Assemble EPN (event processing network) -->

    <wlevs:adapter id="fxMarketAmer" provider="loadgen">
        <wlevs:instance-property name="port" value="9011"/>
    </wlevs:adapter>

    <wlevs:adapter id="fxMarketAsia" provider="loadgen">
        <wlevs:instance-property name="port" value="9012"/>
    </wlevs:adapter>

    <wlevs:adapter id="fxMarketEuro" provider="loadgen">
        <wlevs:instance-property name="port" value="9013"/>
    </wlevs:adapter>

    <wlevs:processor id="preprocessorAmer" listeners="spreaderIn"/>
    <wlevs:processor id="preprocessorAsia" listeners="spreaderIn"/>
    <wlevs:processor id="preprocessorEuro" listeners="spreaderIn"/>

    <wlevs:stream id="fxMarketAmerOut">
        <wlevs:listener ref="preprocessorAmer"/>
        <wlevs:source ref="fxMarketAmer"/>
    </wlevs:stream>

    <wlevs:stream id="fxMarketAsiaOut">
        <wlevs:listener ref="preprocessorAsia"/>
        <wlevs:source ref="fxMarketAsia"/>
    </wlevs:stream>

    <wlevs:stream id="fxMarketEuroOut">
        <wlevs:listener ref="preprocessorEuro"/>
        <wlevs:source ref="fxMarketEuro"/>
    </wlevs:stream>

    <wlevs:stream id="spreaderOut" manageable="true">
        <wlevs:listener>
            <!-- Create business object -->
            <bean id="outputBean" 
                  class="com.bea.wlevs.example.fx.OutputBean"
                  autowire="byName"/>
        </wlevs:listener>
    </wlevs:stream>

    <!-- The processor id needs to be well known so that it can import the rules config -->

    <wlevs:processor id="spreader">
        <wlevs:listener ref="spreaderOut"/>
    </wlevs:processor>

    <wlevs:stream id="spreaderIn">
        <wlevs:listener ref="spreader"/>
    </wlevs:stream>

</beans>

In the preceding example:

The FX Processor Configuration Files

The FX application uses four processors: three to handle the three data feeds and one that joins the resulting events. The first three processors are configured in a single XML file, called preprocessor.xml, as shown:

<?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">

<processor>
    <name>preprocessorAmer</name>
    <rules>
      <rule id="UsdToEurRule"><![CDATA[

      insert into ForeignExchangeEvent
      select avg(lastPrice) as price, 'USD' as fromRate, 'EUR' as toRate
      from (select * from StockTick where symbol='USDEUR') retain 1 sec
      where lastPrice < 3.0 and lastPrice > 0.25

      ]]></rule>
    </rules>
  </processor>

  <processor>
    <name>preprocessorAsia</name>
    <rules>
      <rule id="EurToJpyRule"><![CDATA[

      insert into ForeignExchangeEvent
      select avg(lastPrice) as price, 'EUR' as fromRate, 'JPY' as toRate
      from (select * from StockTick where symbol='EURJPY') retain 1 sec
      where lastPrice < 200.0 and lastPrice > 100.0

      ]]></rule>
    </rules>
  </processor>

  <processor>
    <name>preprocessorEuro</name>
    <rules>
      <rule id="EurToGbpRule"><![CDATA[

      insert into ForeignExchangeEvent
      select avg(lastPrice) as price, 'EUR' as fromRate, 'GBP' as toRate
      from (select * from StockTick where symbol='EURGBP') retain 1 sec
      where lastPrice < 1.5 and lastPrice > 0.5

      ]]></rule>
    </rules>
  </processor>

</n1:config>

The three processors in this file are all essentially the same; the differences lie only in the values used in the EPL queries for querying different items from the data feeds and applying different boundary conditions. For this reason, this section will discuss just a single one of the processors: preprocessorAmer.

The EPL rule fired for the american data feed is:

      insert into ForeignExchangeEvent
      select avg(lastPrice) as price, 'USD' as fromRate, 'EUR' as toRate
      from (select * from StockTick where symbol='USDEUR') retain 1 sec
      where lastPrice < 3.0 and lastPrice > 0.25

To understand the query, one must look at the various clauses, as follows:

The spreader processor is configured with the spreader.xml file, as shown:

<?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">

<processor>
    <name>spreader</name>
    <rules>
      <rule id="spreaderRule"><![CDATA[

      select ((a.price * b.price) + 0.05) as internalPrice, a.fromRate || b.toRate as crossRate
      from ForeignExchangeEvent a, ForeignExchangeEvent b
      retain 10 sec with unique a.toRate partition by a.fromRate
      where a.toRate = b.fromRate and a.fromRate != b.toRate

      ]]></rule>
    </rules>
  </processor>

</n1:config>

In the spreader EPL rule:

The result of this query is then sent to the business object POJO.

For additional information and examples about using EPL, see the EPL Reference Guide.

Signal Generation Example

The signal generation sample application receives simulated market data and verifies if the price of a security has fluctuated more than two percent. The application also detects if there is a trend occurring by keeping track of successive stock prices for a particular symbol; if more than three successive prices fluctuate more than two percent, this is considered a trend.

The application simulates a market data feed using the Oracle CEP load generator utility; in this example, the load generator generates up to 10,000 messages per second. The example includes an HTML dashboard which displays the matched events along with the latencies; events consist of a stock symbol, a timestamp, and the price.

The example demonstrates very low latencies, with minimum latency jitter under high throughputs. Once the application starts running, the processor matches an average of 800 messages per second. If the application is run on the minimum configured system, the example shows very low average latencies (30-300 microsecond, on average) with minimal latency spikes (low milliseconds).

The example computes and displays latency values based on the difference between a timestamp generated on the load generator and timestamp on Oracle CEP. Computing valid latencies requires very tight clock synchronization, such as 1 millisecond, between the computer running the load generator and the computer running Oracle CEP. For this reason, Oracle recommends running both the load generator and Oracle CEP on a single multi-CPU computer where they will share a common clock.

The example also shows how to use the Oracle CEP event caching feature. In particular the single processor in the EPN sends events to both an event bean and a cache.

The example also demonstrates how to use parameterized EPL queries in which the rules configured in the processor configuration file use the ? character as a placeholder, and then the queries are passed specific parameter values at runtime.

Running the Signal Generation Example

For optimal demonstration purposes, Oracle recommends that you run this example on a powerful computer, such as one with multiple CPUs or a 3 GHz dual-core Intel, with a minimum of 2 GB of RAM.

The signalgeneration_domain domain contains a single application: the signal generation sample application. To run the signal generation application, you simply start an instance of Oracle CEP in the domain, as described in the following steps:

Building and Deploying the Signal Generation Example from the Source Directory

The signal generation sample source directory contains the Java source, along with other required resources, such as configuration XML files, EPN assembly file, and DOJO client Javascript libraries, that make up the signal generation application. The build.xml Ant file contains targets to build and deploy the application to the signalgeneration_domain domain, as described in Description of the Ant Targets to Build Signal Generation.

To build and deploy the signal generation application, follow these steps:

Description of the Ant Targets to Build Signal Generation

The build.xml file, located in the top-level directory of the FX source, contains the following targets to build and deploy the application:

Event Record and Playback Example

The record and playback example shows how to configure a component to record events to an event store and then configure another component in the network to playback events from the store. The example uses the Oracle CEP-provided database server, Apache Derby, to store the events. The example also shows how to configure a publishing HTTP pub-sub adapter as a node in the event processing network.

The following graphic describes the event processing network of the example.

The application contains four components in its event processing network:

Running the Event Record/Playback Example

The recplay_domain domain contains a single application: the record and playback sample application. To run this application, you first start an instance of Oracle CEP in the domain, as described in the following procedure.

The procedure then shows how you use Visualizer to start the recording and playback of events at the simpleEventSource and eventStream components, respectively. Finally, the procedure shows how you can use Visualizer to view the stream of events being published to a channel by the playbackHttpPublisher adapter.

Building and Deploying the Event Record/Playback Example from the Source Directory

The record and playback sample source directory contains the Java source, along with other required resources, such as configuration XML file and EPN assembly file that make up the application. The build.xml Ant file contains targets to build and deploy the application to the signalgeneration_domain domain, as described in Description of the Ant Targets to Build Record and Playback.

To build and deploy the record and playback application, follow these steps:

Description of the Ant Targets to Build Record and Playback

The build.xml file, located in the top-level directory of the record/playback source, contains the following targets to build and deploy the application:

Implementation of the Record and Playback Example

The implementation of the record and playback example generally follows the main steps for creating an Oracle CEP application; refer to that section for a task-oriented procedure that describes the typical development process.

All the files of the example are located relative to 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 c:\oracle_cep. Oracle recommends that you use this example directory setup in your own environment, although it is obviously not required.

The files used by the record and playback example include:

The record/playback example uses a build.xml Ant file to compile, assemble, and deploy the OSGi bundle; see Building and Deploying the Event Record/Playback Example from the Source Directory for a description of this build.xml file if you also use Ant in your development environment.