Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Complex Event Processing
11g Release 1 (11.1.1.6.3) for Eclipse

Part Number E14301-10
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

15 Configuring Custom Event Beans

This chapter describes how to implement and configure Oracle Complex Event Processing (Oracle CEP) custom event beans, including how to implement the beans as event sinks and event sources.

15.1 Overview of Custom Event Beans

An event bean is a Plain Old Java Object (POJO) managed by the Oracle CEP management framework. You register event beans in the EPN assembly file using the Oracle CEP wlevs:event-bean stage rather than the standard bean element.

An event bean is a type of Stage, it can be monitored by the Oracle CEP monitoring framework, make use of the configuration metadata annotations, and it can be set to record, and play-back events that pass through it. An event bean can also participate in the Oracle CEP server bean lifecycle by specifying methods in its XML declaration, rather than by implementing Oracle CEP server API interfaces.

To add a Plain Old Java Object (POJO) to your Oracle CEP application:

15.1.1 Custom Event Bean Event Sources and Event Sinks

Event beans can be event sources, event sinks, or both. Event sources generate events, event sinks receive events.

15.1.1.1 Custom Event Beans as Event Sources

You specify that an event bean component in your EPN is an event source by implementing the com.bea.wlevs.ede.api.StreamSource or RelationSource API.

The implementation class of an event bean that is an event source may be specified as private to the application or as an advertised OSGI service re-usable by other applications.

For the framework to be able to fully manage the custom event bean as an EPN component, it must be specified as an event bean rather than a standard Spring bean. Management tasks include monitoring and record/playback.

You register event beans in the EPN assembly file using the wlevs:event-bean element. For example:

<wlevs:event-bean id="myEventBeanSource" class="com.acme.MySourceEventBean">
</wlevs:event-bean>

In this example, the Java class MySourceEventBean.java implements the com.bea.wlevs.ede.api.StreamSource or RelationSource API.

For more information, see Section 15.2.1, "Implementing a Custom Event Bean as an Event Source".

15.1.1.2 Custom Event Beans as Event Sinks

The functionality of custom event beans as event sinks is very similar to that of event sources except that custom event bean sinks must implement the com.bea.wlevs.ede.api.StreamSink or RelationSink API.

Event sinks are not active which means that if they implement the Runnable interface, Oracle CEP does not run them in a separate thread.

You reference event sinks in the EPN assembly file using the wlevs:listener element:

<wlevs:event-bean id="myEventBeanSink" class="com.acme.MySinkEventBean">
</wlevs:event-bean>
...
<wlevs:channel id="myStream" >
    <wlevs:listener ref="myEventBeanSink" />
</wlevs:channel>

In this example, the Java class MySinkEventBean.java implements the com.bea.wlevs.ede.api.StreamSink or RelationSink API.

For more information, see Section 15.2.2, "Implementing a Custom Event Bean as an Event Sink"

15.1.2 Custom Event Bean Factories

If your event bean is going to be used only by a single Oracle CEP application, then you do not need to create a factory. However, if multiple applications are going to use the same event bean, then you should also program a factory. In this case, every application gets its own instance of the adapter.

Event bean factories must implement the com.bea.wlevs.ede.api.Factory interface. This interface has a single method, create, that you implement to create an adapter or event bean instance.

You register factories in the EPN assembly file using the wlevs:factory element:

<wlevs:factory provider-name="myprovider" class="my.Implementation"/>

Note that if you need to specify service properties, then you must use the <osgi:service> to register the factory.

15.2 Implementing a Custom Event Bean

The following procedure describes the typical steps for creating a custom event bean.

To implement a custom event bean:

Note:

The following procedure assumes that the custom event bean is bundled in the same application JAR file that contains the other components of the EPN, such as the processor, streams, and business logic POJO. If you want to bundle the custom event bean in its own JAR file so that it can be shared among multiple applications, see Section 24.2.4.2, "How to Assemble a Custom Event Bean in its Own Bundle."

  1. Program the custom event bean Java class.

    If your custom event bean is an event source, see Section 15.2.1, "Implementing a Custom Event Bean as an Event Source."

    If your custom event bean is an event sink, see Section 15.2.2, "Implementing a Custom Event Bean as an Event Sink."

    If your custom event bean is both an event source and event sink, then see both sections.

  2. Optionally program the factory class.

    You only need to do this if many applications are going to use the custom event bean.

    See Section 15.2.3, "Implementing a Custom Event Bean Factory."

  3. Optionally extend the configuration of the custom event bean if its basic one is not adequate.

    See Chapter 19, "Extending Component Configuration."

  4. Configure the custom event bean.

    For more information, see:

15.2.1 Implementing a Custom Event Bean as an Event Source

The following example shows a custom event bean class as an event source ; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

package com.acme;

import com.bea.wlevs.ede.api.StreamSender;
import com.bea.wlevs.ede.api.StreamSource;
import com.bea.wlevs.ede.api.RunnableBean;
 
public class EventBeanSource implements RunnableBean, StreamSource {

    public void setEventSender (StreamSender streamSender) {
    ...
    }

    public void run() {
    ...
    }

    public synchronized void suspend() throws Exception {
    ...
    }
}

Follow these guidelines when programming the custom event bean Java class; code snippets of the guidelines are shown in bold in the preceding example:

  • Import the interfaces and classes of the Oracle CEP API:

    import com.bea.wlevs.ede.api.StreamSender;
    import com.bea.wlevs.ede.api.StreamSource;
    import com.bea.wlevs.ede.api.RunnableBean;
    

    Because the custom event bean is an event source it must implement the StreamSource interface. If you want the custom event bean to run in a thread, also implement RunnableBean. The StreamSender interface sends event types to the next component in your application network. For full details of these APIs, see Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.

  • The custom event bean class must implement the StreamSource and RunnableBean interfaces because it is an event source and will run in its own thread:

    public class HelloWorldAdapter implements RunnableBean, StreamSource {
    

    The StreamSource interface provides the StreamSender that you use to send events.

  • Because the custom event bean implements the RunnableBean interface, your adapter must then implement the run method:

    public void run() {...
    

    This is where you should put the code that reads the incoming data, such as from a market feed, and convert it into an Oracle CEP event type, and then send the event to the next component in the network. Refer to the documentation of your data feed provider for details on how to read the incoming data. See Section 24.2.2.2, "Accessing Third-Party JAR Files" for information about ensuring you can access the vendor APIs if they are packaged in a third-party JAR file.

  • Because the custom event bean implements StreamSource, you must implement the setEventSender method, which passes in the StreamSender that you use to send events:

    public void setEventSender(StreamSender sender) { ...
    
  • If, as is typically the case, your custom event bean implements SuspendableBean, you must implement the suspend method that stops the custom event bean when, for example, the application is undeployed:

    public synchronized void suspend() throws Exception { ... 
    

15.2.2 Implementing a Custom Event Bean as an Event Sink

The following sample code shows a Spring bean from HelloWorld application that acts as an event sink; see the explanation after the example for the code shown in bold:

package com.bea.wlevs.example.helloworld;
 
import com.bea.wlevs.ede.api.StreamSink;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;
 
public class HelloWorldBean implements StreamSink {
 
    public void onInsertEvent(Object event) {
        if (event instanceof HelloWorldEvent) {
            HelloWorldEvent helloWorldEvent = (HelloWorldEvent) event;
            System.out.println("Message: " + helloWorldEvent.getMessage());
        }   
        // Throw com.bea.wlevs.ede.api.EventRejectedException to have exceptions propagated
        // up to senders. Other errors will be logged and dropped.
    }
 
}

The programming guidelines shown in the preceding example are as follows:

  • Your bean must import the event type of the application, which in the HelloWorld case is HelloWorldEvent:

    import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;
    
  • Your bean must implement the com.bea.wlevs.ede.api.StreamSink interface:

    public class HelloWorldBean implements StreamSink {...
    
  • The StreamSink interface has a single method that you must implement, onInsertEvent(java.lang.Object), which is a callback method for receiving events. The parameter of the method is an Object that represents the actual event that the bean received from the component that sent it the event:

    public void onInsertEvent(Object event)
    

    Your implementation should throw com.bea.wlevs.ede.api.EventRejectedException to have exceptions propagated up to senders. Other errors will be logged and dropped.

  • The data type of the events is determined by the event type you registered in the EPN assembly file of the application. In the example, the event type is HelloWorldEvent; the code first ensures that the received event is truly a HelloWorldEvent:

    if (event instanceof HelloWorldEvent) {
        HelloWorldEvent helloWorldEvent = (HelloWorldEvent) event;
    

    This event type is a JavaBean that was configured in the EPN assembly file as shown:

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

    See Section 4.3, "Creating EPN Assembly Files" for procedural information about creating the EPN assembly file, and Appendix C, "Schema Reference: EPN Assembly spring-wlevs-v11_1_1_6.xsd" for reference information.

  • Events are instances of the appropriate JavaBean, so you access the individual properties using the standard getXXX methods. In the example, the HelloWorldEvent has a property called message. You access this property using method getMessage:

    System.out.println("Message: " + helloWorldEvent.getMessage());
    

For complete API reference information about the Oracle CEP APIs described in this section, see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.

15.2.3 Implementing a Custom Event Bean Factory

Your adapter factory class must implement the com.bea.wlevs.ede.api.EventBeanFactory interface, which has a single method, create, in which you code the creation of your specific adapter class. Event beans implement Factory.

The following is a possible adapter factory class for the HelloWorld example:

package com.acem;

import com.bea.wlevs.ede.api.EventBean;
import com.bea.wlevs.ede.api.EventBeanFactory;

public class MyEventBeanFactory implements Factory {
    public MyEventBeanFactory() {
    }
    public synchronized EventBean create() throws IllegalArgumentException {
        return new MyEventBeanFactory();
    }
}

For full details of these APIs, see the Oracle Fusion Middleware Java API Reference for Oracle Complex Event Processing.

15.3 Configuring the Custom Event Bean EPN Assembly File

The custom event bean and custom event bean factory (if used) must be registered in the EPN assembly file, as discussed in the following sections:

For a complete description of the configuration file, including registration of other components of your application, see Section 4.3, "Creating EPN Assembly Files."

15.3.1 Registering the Custom Event Bean Factory

You register factories in the EPN assembly file using the wlevs:factory element:

<wlevs:factory provider-name="myprovider" class="my.Implementation"/>

If you need to specify service properties, then you must use the osgi:service element to register the factory as an OSGI service in the EPN assembly file. The scope of the OSGI service registry is the entire Oracle CEP. This means that if more than one application deployed to a given server is going to use the same adapter factory, be sure to register the adapter factory only once as an OSGI service.

Add an entry to register the service as an implementation of the com.bea.wlevs.ede.api.EventBeanFactory interface. Provide a property, with the key attribute equal to type, and the name by which this adapter provider will be referenced. Finally, add a nested standard Spring bean element to register your specific adapter class in the Spring application context

For example, the following segment of the EPN assembly file registers the MyEventBeanFactory as the provider for type hellomsgs:

<osgi:service interface="com.bea.wlevs.ede.api.EventBeanFactory">
    <osgi:service-properties>
        <entry key="type" value="myprovider"</entry>
    </osgi:service-properties>
    <bean  class="com.acme.MyEventBeanFactory" />
</osgi:service>

For more information on how to reference a factory by its type, see Section 15.3.2, "Declaring the Custom Event Bean Components in your Application".

15.3.2 Declaring the Custom Event Bean Components in your Application

In the EPN assembly file, you use the wlevs:event-bean element to declare a custom event bean as a component in the event processor network. For example:

<wlevs:event-bean id="recplayEventSink"
                  class="com.bea.wlevs.example.recplayRecplayEventSink">
    <wlevs:listener ref="playbackHttpPublisher"/>
</wlevs:event-bean>

If you registered an optional factory as an OSGI service, then use the provider attribute to point to the name you specified as the type in your osgi:service entry; for example:

<wlevs:event-bean id="myEventBean" provider="myprovider"/>

This means that an adapter will be instantiated by the factory registered for the type myprovider.

You can also use a wlevs:instance-property child element of wlevs:adapter to set any static properties in the adapter bean. Static properties are those that you will not dynamically change after the adapter is deployed.

For example, if your adapter class has a setPort method, you can pass it the port number as shown:

<wlevs:event-bean id="myEventBean" provider="myProvider">
    <wlevs:instance-property name="port" value="9001" />
</wlevs:event-bean>

15.4 Configuring the Custom Event Bean Component Configuration File

Each custom event bean in your application has a default configuration, and, optionally, an extended component configuration.

If your application has more than one custom event bean, you can create separate XML files for each, or create a single XML file that contains the configuration for all custom event beans, or even all components of your application (adapters, processors, and streams). Choose the method that best suits your development environment.

The following procedure describes the main steps to create the custom event bean configuration file. For simplicity, it is assumed in the procedure that you are going to configure all components of an application in a single XML file

For more information, see:

15.4.1 How to Configure a Custom Event Bean Manually

The following procedure describes how to configure a custom event bean manually.

To configure the custom event bean component configuration file:

  1. Create an XML file using your favorite XML editor.

    You can name this XML file anything you want, provided it ends with the .xml extension.

    The root element of the configuration file is config, with namespace definitions shown in the next step.

  2. For each event bean in your application, add an event-bean child element of config.

    Uniquely identify each custom event bean with the name child element. This name must be the same as the value of the id attribute in the wlevs:event-bean element of the EPN assembly file that defines the event processing network of your application. This is how Oracle CEP knows to which particular custom event bean component in the EPN assembly file this adapter configuration applies. See Section 4.3, "Creating EPN Assembly Files" for details.

    For example, if your application has two custom event beans, the configuration file might initially look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <helloworld:config
      xmlns:helloworld="http://www.bea.com/xml/ns/wlevs/example/helloworld">
      <processor>
       ...
      </processor>
      <event-bean>
        <name>firstEventBean</name>
        ...
      </event-bean>
      <event-bean>
        <name>firstEventBean</name>
        ...
      </event-bean>
    </helloworld:config>
    

    In the example, the configuration file includes two custom event beans called firstEventBean and secondEventBean. This means that the EPN assembly file must include at least two custom event bean registrations with the same identifiers:

    <wlevs:event-bean id="firstEventBean" ...>
      ...
    </wlevs:event-bean>
    <wlevs:event-bean id="secondEventBean" ...>
      ...
    </wlevs:event-bean>
    

    Caution:

    Identifiers and names in XML files are case sensitive, so be sure you specify the same case when referencing the component's identifier in the EPN assembly file.

15.4.1.1 Example of a Custom Event Bean Configuration File

The following sample XML file shows how to configure two custom event beans, firstEventBean and secondEventBean.

<?xml version="1.0" encoding="UTF-8"?>
<sample:config
  xmlns:sample="http://www.bea.com/xml/ns/wlevs/example/sample">
  <event-bean>
    <name>firstEventBean</name>
    ...
  </event-bean>
  <event-bean>
    <name>firstEventBean</name>
    ...
  </event-bean>
</sample:config>