Application Development Guide

Overview of Creating Oracle Complex Event Processing Applications

This section contains information on the following subjects:

Overview of the Oracle Complex Event Processing Programming Model

Because Oracle Complex Event Processing (or Oracle CEP for short) applications are low latency high-performance driven applications, they run on a lightweight container and are developed using a POJO-based programming model. In POJO (Plain Old Java Object) programming, business logic is implemented in the form of POJOs, and then injected with the services they need. This is popularly called dependency injection. The injected services can range from those provided by Oracle CEP services, such as configuration management, to those provided by another Oracle product such as Oracle Kodo, to those provided by a third party.

Oracle CEP defines a set of core services or components used together to assemble event-driven applications; the typical services are adapters, streams, and processors. You can also create your own business logic POJOs and Spring beans that are part of the application, as well as specialized event beans that are just like Spring beans but with full access to the Oracle CEP framework, such as monitoring and record/playback of events. In addition to these, Oracle CEP includes other infrastructure services, such as caching, clustering, configuration, monitoring, logging, and so on.

All services are deployed on the underlying Oracle microServices Architecture (mSA) technology. Oracle mSA is based upon the OSGi Service Platform defined by the OSGi Alliance.

The following sections provide additional information about the Oracle CEP programming model and creating applications:

Components of the Oracle CEP Event Processing Network

Oracle CEP applications and their event processing networks (EPNs) are made up of the following basic components:

Event Sources and Event Sinks

All components in an EPN are either event sources (emit events) or event sinks (receive events.) Some components can be both, such as an event bean in the middle of an EPN that receives events from an adapter, for example, and then sends events to a processor.

Components that emit events must implement the com.bea.wlevs.ede.api.EventSource interface. This interface has one method, setEventSender(); at runtime the event source component is injected with an com.bea.wlevs.ede.api.EventSender instance. This EventSender instance, in turn, has a sentEvent() method that the component invokes to actually send events to the next component in the EPN.

Components that receive events from event sources must implement the com.bea.wlevs.ede.api.EventSink interface. This interface has a single callback method, onEvent(), that event sinks implement to receive a list of events from the previous component in the EPN.

Component Configuration Files

Each component in your event processing network (adapter, processor, stream, or event bean) can have an associated configuration file, although only processors are required to have a configuration file. The caching system also uses a configuration file, regardless of whether it is a stage in the event processing network. Component configuration files in Oracle CEP are XML documents whose structure is defined using standard XML Schema. You create a single file that contains configuration for all components in your application, or you can create separate files for each component; the choice depends on which is easier for you to manage.

The following two schema documents define the default structure of application configuration files:

The structure of application configuration files is as follows. There is a top-level root element named <config> that contains a sequence of sub-elements. Each individual sub element contains the configuration data for an Oracle CEP component (processor, stream, or adapter). For example:

<?xml version="1.0" encoding="UTF-8"?>

<helloworld:config
  xmlns:helloworld="http://www.bea.com/ns/wlevs/example/helloworld">
  <processor>
    <name>helloworldProcessor</name>
    <rules>
      <rule id="helloworldRule"><![CDATA[ select * from HelloWorldEvent retain 1 event ]]></rule>
    </rules>
  </processor>

  <adapter>
    <name>helloworldAdapter</name>
    <message>HelloWorld - the current time is:</message>
  </adapter>

  <stream monitoring="true" >
      <name>helloworldOutstream</name>
      <max-size>10000</max-size>
      <max-threads>2</max-threads>
  </stream>

</helloworld:config>

How Components Fit Together

Oracle CEP applications are made of services that are assembled together to form an Event Processing Network (EPN).

The server uses the Spring framework as its assembly mechanism due to Spring’s popularity and simplicity. Oracle CEP has extended the Spring framework to further simplify the process of assembling applications. This approach allows Oracle CEP applications to be easily integrated with existing Spring-beans, and other light-weight programming frameworks that are based upon a dependency injection mechanism.

A common approach for dependency injection is the usage of XML configuration files to declaratively specify the dependencies and assembly of an application. You assemble an Oracle CEP application an EPN assembly file before deploying it to the server; this EPN assembly file is an extension of the Spring framework XML configuration file.

After an application is assembled, it must be package so that it can be deployed into Oracle CEP. This is a simple process. The deployment unit of an application is a plain JAR file, which must contain, at a minimum, the following artifacts:

After you assemble the artifacts into a JAR file, you deploy this bundle to Oracle CEP so it can immediately start receiving incoming data.

Application Lifecycle

This section describes the lifecycle of an application deployed to Oracle CEP and the sequence of com.bea.wlevs.ede.api API callbacks. The lifecycle description is broken down into actions that a user performs, such as install an application, suspend it, resume it, and so on.

The point of this section is to show you how Oracle CEP manages an application’s lifecycle so that you can better use the lifecycle APIs in your application. See Oracle CEP APIs for a brief description of these lifecycle APIs, such as RunnableBean and SuspendableBean, as well as the Javadocs.

The application states referenced in this section are returned by the getState() method on the ApplicationMBean. These states are specific to Oracle CEP; they are not OSGI bundle states. The possible states are: UNINSTALLED, INITIALIZING, RUNNING, and SUSPENDED.

User action: Install an application or start the server with application already deployed

User action: Suspend application.

User action: Resume application.

User action: Uninstall application.

User action: Update application.

This is equivalent to first unistalling an application and then installing it again.

Oracle CEP APIs

Oracle CEP provides a variety of Java APIs that you use in your adapter or event bean implementation.

This section describes the APIs that you will most typically use in your adapters and event beans; see the Javadoc for the full reference documentation for all classes and interfaces. See Creating Custom Adapters and Event Beans as well as the HelloWorld and FX examples in the installed product, for sample Java code that uses these APIs.

Oracle CEP Development Environment for Eclipse

Oracle provides an IDE targeted specifically to programmers that want to develop Oracle CEP applications. Oracle CEP Development Environment for Eclipse (Oracle CEP IDE for short) is a set of plugins for the Eclipse IDE designed to help develop, deploy, and debug applications for Oracle CEP.

The key features of the Oracle CEP IDE are as follows:

Although it is not required or assumed that you are using the Oracle CEP IDE, Oracle recommends that you give it a try.

See the online help, integrated in the Oracle CEP IDE product itself, for detailed instructions on using the IDE.

Downloading the Latest Oracle CEP IDE

New versions of the IDE are constantly being uploaded to the Oracle Technology Network Web site. Oracle highly recommends that you download the IDE from this site:

http://www.oracle.com/technology/products/event-driven-architecture/cep-ide/10

Installing the Oracle CEP IDE Distributed With the Product

A version of the Oracle CEP IDE is shipped with the Oracle CEP product, although this version might be older than the one on the Oracle Technology Network site. However, if you want to use the version shipped with the product, follow these steps:

Once Eclipse has restarted, you should find all of the Oracle CEP IDE tools available to you.

Creating Oracle CEP Applications: Typical Steps

The following procedure shows the suggested start-to-finish steps to create an Oracle CEP application. Although it is not required to program and configure the various components in the order shown, the procedure shows a typical and logical flow recommended by Oracle.

It is assumed in the procedure that you are using an IDE, although it is not required and the one you use is your choice. For one targeted to Oracle CEP developers, see Oracle CEP Development Environment for Eclipse.

Oracle CEP provides a load generator testing tool that you can use to test your application, in particular the EPL rules. This testing tool can temporarily replace the adapter component in your application, for testing purposes only of course. For details, see Using the Load Generator to Test Your Application.

See Next Steps for the list of steps you should follow after you have completed programming your application, such as packaging and deploying.

Creating the EPN Assembly File

You use the EPN assembly file to declare the components that make up your Oracle CEP application and how they are connected to each other. You also use the file to register event types of your application, as well as the Java classes that implement the adapter and POJO components of your application.

For an example of an EPN assembly file, see the foreign exchange (FX) example. For additional information about Spring and OSGi, see Additional Information about Spring and OSGi.

As is often true with Spring, there are different ways to use the tags to define your event network. This section shows one way. See Oracle CEP Spring Tag Reference or the XSD Schema for the full reference information on the other tags and attributes you can use.

For a typical way to create the EPN assembly file for your application, follow these steps:

Creating the Event Types

Event types define the properties of the events that are handled by Oracle CEP applications. Adapters receiving incoming events from different event sources, such as JMS, or financial market data feeds. You must define these events by an event type before a processor is able to handle them. An event type can be created either programmatically using the EventTypeRepository class or declaratively in the EPN assembly file.

You then use these event types in the adapter and POJO Java code, as well as in the EPL rules associated with the processors.

Events are JavaBean instances in which each property represents a data item from the feed. Oracle recommends that you create your own JavaBean class that represents the event type and register the class in the EPN assembly file. By creating your own JavaBean, you can reuse it and you have complete control over what the event looks like. Alternatively, you can specify the properties of the event type in the EPN assembly file using <wlevs:metadata> tags, in which case Oracle CEP will use a map; this method is best used for quick prototyping.

The following simple example shows the JavaBean that implements the HelloWorldEvent:

package com.bea.wlevs.event.example.helloworld;

public class HelloWorldEvent {
        private String message;

        public String getMessage() {
                return message;
        }

        public void setMessage (String message) {
                this.message = message;
        }
}

The preceding Java class follows standard JavaBeans programming guidelines. See the JavaBeans Tutorial for additional details.

In addition, Oracle recommends that, if possible, you make your JavaBeans immutable for performance reasons because immutable beans help the garbage collection work much better. Immutable beans are read only (only getters) and have public constructors with arguments that satisfy immutability.

Once you have programmed and compiled the JavaBean that represents your event type, you register it in the EPN assembly file using the <wlevs:event-type> child tag of <wlevs:event-type-repository>. Use the <wlevs:class> tag to point to your JavaBean class, and then optionally use the <wlevs:property name="builderFactory"> tag to specify a custom event builder factory for the event type, which can be used to create event instances that do not follow the JavaBean specification. If want Oracle CEP to generate the bean instance for you, use the <wlevs:metadata> tag to group standard Spring <entry> tags for each property. The following example shows both ways:

<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 type-name="AnotherEvent">
          <wlevs:metadata>
             <entry key="name" value="java.lang.String"/>
             <entry key="age" value="java.lang.Integer"/>
             <entry key="address" value="java.lang.String"/>
          </wlevs:metadata>
    </wlevs:event-type>

</wlevs:event-type-repository>

In the example, ForeignExchangeEvent is implemented by the ForeignExchangeEvent inner class of com.bea.wlevs.example.fx.OutputBean. Instances of AnotherEvent will be generated by Oracle CEP. The AnotherEvent has three properties: name, age, and address.

See Using an Event Type Builder Factory for additional information about using an event type builder factory.

You can now reference the event types as standard JavaBeans in the Java code of the adapters and business logic POJO in your application. The following snippet from the business logic POJO HelloWorldBean.java of the HelloWorld application shows an example:

public void onEvent(List newEvents)
        throws RejectEventException {
    for (Object event : newEvents) {
            HelloWorldEvent helloWorldEvent = (HelloWorldEvent) event;
        System.out.println("Message: " + helloWorldEvent.getMessage());
    }
}

The following EPL rule shows how you can reference the HelloWorldEvent in a SELECT statement:

SELECT * FROM HelloWorldEvent RETAIN 1 event

Using an Event Type Builder Factory

When you register an event type in the repository using the <wlevs:event-type> tag, Oracle CEP creates instances of the event using the information in the event type class.

Sometimes, however, you might want or need to have more control over how the event type instances are created. This is required if the POJO that represents the event does not expose the necessary getter and setter methods for the event properties. For example, assume the event type has a firstname property, but the EPL rule that executes on the event type assumes the property is called fname. Further assume that you cannot change either the event type class (because you are using a shared event class from another bundle, for example) or the EPL rule to make them compatible with each other. In this case you can use an event type builder factory to change the way the event type instance is created so that the property is named fname rather than firstname.

When you program the event type builder factory, you must implement the EventBuilder.Factory inner interface of the com.bea.wlevs.ede.api.EventBuilder interface; see the Javadocs for details about the methods you must implement, such as createBuilder() and createEvent().

The following example of an event type builder factory class is taken from the FX sample:

package com.bea.wlevs.example.fx;

import java.util.HashMap;
import java.util.Map;

import com.bea.wlevs.ede.api.EventBuilder;
import com.bea.wlevs.example.fx.OutputBean.ForeignExchangeEvent;

public class ForeignExchangeBuilderFactory implements EventBuilder.Factory {

        public EventBuilder createBuilder() {
                return new ForeignExchangeBuilder();
        }

        static class ForeignExchangeBuilder implements EventBuilder {
                private Map<String,Object> values = new HashMap<String,Object>(10);

                public Object createEvent() {
                        return new ForeignExchangeEvent(
                                (String) values.get("symbol"),
                                (Double) values.get("price"),
                                (String) values.get("fromRate"),
                                (String) values.get("toRate"));
                }

                public void put(String property, Object value) throws IllegalStateException {
                        values.put(property, value);
                }
        }
}

When you register the event type in the EPN assembly file, use the <wlevs:property name="builderFactory"> child tag of the <wlevs:event-type> tag to specify the name of the factory class. The hard-coded builderFactory value of the name attribute alerts Oracle CEP that it should use the specified factory class, rather than its own default factory, when creating instances of this event. For example, in the FX example, the builder factory is registered as shown in bold:

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

Sharing Event Types Between Application Bundles

Each Oracle CEP application gets its own Java classloader and loads application classes using that classloader. This means that, by default, one application cannot access the classes in another application. However, because the event type repository is a singleton service, you can configure the repository in one bundle and then explicitly export the event type classes so that applications in separate bundles (deployed to the same Oracle CEP server) can use these shared event types.

The event type names in this case are scoped to the entire Oracle CEP server instance. This means that you will get an exception if you try to create an event type that has the same name as an event type that has been shared from another bundle, but the event type classes are different.

To share event type classes, add their package name to the Export-Package header of the MANIFEST.MF file of the bundle that contains the event type repository you want to share.

Be sure you deploy the bundle that contains the event type repository before all bundles that contain applications that use the shared event types, or you will get a deployment exception.

Next Steps

After you have programmed all components of your application and created their configuration XML files: