Application Development Guide

Creating Custom Adapters and Event Beans

This section contains information on the following subjects:

Overview of Adapters and Event Beans

The role of an adapter is to convert data coming from some stream, such as a market data feed, into Oracle Complex Event Processing (or Oracle CEP for short) events. These events are then passed to other components in the application, such as processors. An adapter is usually the entry point to an Oracle CEP application.

The FX example description shows three adapters that read in data from currency data feeds and then pass the data, in the form of a specific event type, to the processors, which are the next components in the network.

You can create adapters of different types, depending on the format of incoming data and the technology you use in the adapter code to do the conversion. The most typical types of adapters are those that:

Adapters are Java classes that implement specific Oracle CEP interfaces. You must also program adapter factories that create instances of the adapters. Finally, you must register both the adapter classes, and the adapter factories, in the EPN assembly file that describes your entire application.

You can optionally change the default configuration of the adapter, or even extend the configuration and add new configuration elements and attributes. There are two ways to pass configuration data to the adapter; the method you chose depends on whether you want to dynamically change the configuration after deployment. If you are not going to change the configuration data after the adapter is deployed, then you can configure the adapter in the EPN assembly file. If, however, you do want to be able to dynamically change the configuration elements, then you should put this configuration in the adapter-specific configuration files. Both methods are discussed below.

Creating Adapters or Event Beans: Typical Steps

The following procedure describes the typical steps for creating an adapter:

In the preceding procedure, it is assumed that the adapter is bundled in the same application JAR file that contains the other components of the event network, such as the processor, streams, and business logic POJO. If you want to bundle the adapter in its own JAR file so that it can be shared among many applications, see Creating an Adapter in Its Own Bundle.

Programming the Adapter Class: Guidelines

The adapter class reads the stream of incoming data, such as from a market data feed, converts it into an Oracle CEP event type that is understood by the rest of the application, and sends the event to the next component in the network.

The following example shows the adapter class of the HelloWorld sample; see the explanation after the example for coding guidelines that correspond to the Java code in bold.

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

import java.text.DateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import com.bea.wlevs.configuration.Activate;
import com.bea.wlevs.configuration.Prepare;
import com.bea.wlevs.configuration.Rollback;
import com.bea.wlevs.ede.api.Adapter;
import com.bea.wlevs.ede.api.EventSender;
import com.bea.wlevs.ede.api.EventSource;
import com.bea.wlevs.ede.api.SuspendableBean;
import com.bea.wlevs.event.example.helloworld.HelloWorldEvent;
import com.bea.wlevs.adapter.example.helloworld.HelloWorldAdapterConfig;

public class HelloWorldAdapter implements Runnable, Adapter, EventSource, SuspendableBean {

    private static final int SLEEP_MILLIS = 300;

    private DateFormat dateFormat;

    private String message;
    private EventSender eventSender;
    private boolean stopped;

    public HelloWorldAdapter() {
        super();
        dateFormat = DateFormat.getTimeInstance();
    }

    public void run() {
        stopped = false;
        while (!isStopped()) { // Generate messages forever...
            generateHelloMessage();
            try {
                synchronized (this) {
                    wait(SLEEP_MILLIS);
                }
            } catch (InterruptedException e) {
                e.printStackTrace();
            }
        }
    }

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

    private void generateHelloMessage() {
        List eventCollection = new ArrayList();
        String message = this.message + dateFormat.format(new Date());
        HelloWorldEvent event = new HelloWorldEvent();
        event.setMessage(message);
        eventCollection.add(event);
        eventSender.sendEvent(eventCollection, null);
    }

    @Prepare
    public void checkConfiguration(HelloWorldAdapterConfig adapterConfig) {
        if (adapterConfig.getMessage() == null
                || adapterConfig.getMessage().length() == 0) {
            throw new RuntimeException("invalid message: " + message);
        }
    }

    @Activate
    public void activateAdapter(HelloWorldAdapterConfig adapterConfig) {
        this.message = adapterConfig.getMessage();
    }

    @Rollback
    public void rejectConfigurationChange(HelloWorldAdapterConfig adapterConfig) {
    }

    public void setEventSender(EventSender sender) {
        eventSender = sender;
    }

    public synchronized void suspend() throws Exception {
        stopped = true;
    }

    private synchronized boolean isStopped() {
        return stopped;
    }
}

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

Programming the Adapter Factory Class

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

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

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

import com.bea.wlevs.ede.api.Adapter;
import com.bea.wlevs.ede.api.AdapterFactory;

public class HelloWorldAdapterFactory implements AdapterFactory {

    public HelloWorldAdapterFactory() {
    }

    public synchronized Adapter create() throws IllegalArgumentException {
        return new HelloWorldAdapter();
    }
}

For full details of these APIs, see the Javadoc

Updating the EPN Assembly File

The adapters and adapter factory must be registered in the EPN assembly file, as discussed in the following sections. If you are using JMS, additional configuration is also required.

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

Registering the Adapter Factory as an OSGI Service

The adapter factory must be registered 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.AdapterFactory 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> tag to register the your specific adapter class in the Spring application context

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

<osgi:service interface="com.bea.wlevs.ede.api.AdapterFactory">
        <osgi:service-properties>
            <prop key="type">hellomsgs</prop>
        </osgi:service-properties>
        <bean  class="com.bea.adapter.wlevs.example.helloworld.HelloWorldAdapterFactory" />
</osgi:service>

Declaring the Adapter Components in your Application

In the EPN assembly file, you use the wlevs:adapter tag to declare an adapter as a component in the event processor network. You can declare one or more adapters in your network. Use the provider attribute to point to the name you specified as the type in your osgi:service entry; for example:

    <wlevs:adapter id="helloworldAdapter" provider="hellomsgs"/>

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

You can also use a <wlevs:instance-property> child tag 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:adapter id="myAdapter" provider="myProvider">
       <wlevs:instance-property name="port" value="9001" />
    </wlevs:adapter>

Configuring the Adapter

Each adapter in your application has a default configuration. In particular:

The default adapter configuration is typically adequate for most applications. However, if you want to change this configuration, you must create an XML file that is deployed as part of the Oracle CEP application bundle. You can later update this configuration at runtime using the wlevs.Admin utility or manipulating the appropriate JMX Mbeans directly.

If your application has more than one adapter, you can create separate XML files for each adapter, or create a single XML file that contains the configuration for all adapters, 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 adapter 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

See XSD Schema Reference for Component Configuration Files for the complete XSD Schema that describes the adapter configuration file.

Example of an Adapter Configuration File

The following sample XML file shows how to configure two adapters, firstAdapter and secondAdapter.

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

<sample:config
  xmlns:sample="http://www.bea.com/xml/ns/wlevs/example/sample">

  <adapter>
    <name>firstAdapter</name>
  </adapter>

  <adapter monitoring="true">
    <name>secondAdapter</name>
  </adapter>

</sample:config>

Creating an Adapter in Its Own Bundle

In the procedure described in Creating Adapters or Event Beans: Typical Steps, it is assumed that the adapter and adapter factory are bundled in the same application JAR file that contains the other components of the event network, such as the processor, streams, and business logic POJO.

However, you might sometimes want to bundle the adapter in its own JAR file and then reference the adapter in other application bundles. This is useful if, for example, two different applications read data coming from the same data feed provider and both applications use the same event types. In this case, it makes sense to share a single adapter and event type implementations rather than duplicate the implementation in two different applications.

There is no real difference in how you configure an adapter and an application that uses it in separate bundles; the difference lies in where you put the configuration, as described in the following guidelines:

Extending the Configuration of an Adapter

Adapters have default configuration data, as described in Configuring the Adapter and XSD Schema Reference for Component Configuration Files. This default configuration is typically adequate for simple and basic applications.

However, you can also extend this configuration by using XSD Schema to specifying a new XML format of an adapter configuration file that extends the built-in XML type provided by Oracle CEP. By extending the XSD Schema, you can add as many new elements to the adapter configuration as you want, with few restrictions other than each new element must have a name attribute. This feature is based on standard technologies, such as XSD Schema and Java Architecture for XML Binding (JAXB).

The following procedure describes how to extend the adapter configuration:

Creating the XSD Schema File

The new XSD schema file extends the wlevs_application_config.xsd XSD schema and then adds new custom information, such as new configuration elements for an adapter. Use standard XSD schema syntax for your custom information.

Oracle recommends that you use the XSD schema from the HelloWorld example as a basic template, and modify the content to suit your needs. In addition to adding new configuration elements, other modifications include changing the package name of the generated Java code and the element name for the custom adapter. You can control whether the schema allows just your custom adapter or other components like processors.

Follow these steps when creating the XSD Schema file that describes your extended adapter configuration; see Complete Example of an Extended XSD Schema File for the HelloWorld example:

Complete Example of an Extended XSD Schema File

The following extended XSD file is used in the HelloWorld sample application:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.bea.com/xml/ns/wlevs/example/helloworld"
        xmlns="http://www.bea.com/xml/ns/wlevs/example/helloworld"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
        xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
        xmlns:wlevs="http://www.bea.com/xml/ns/wlevs/config/application"
        jxb:extensionBindingPrefixes="xjc" jxb:version="1.0"
        elementFormDefault="unqualified" attributeFormDefault="unqualified">

        <xs:annotation>
                <xs:appinfo>
                        <jxb:schemaBindings>
                                <jxb:package name="com.bea.adapter.wlevs.example.helloworld"/>
                        </jxb:schemaBindings>
                </xs:appinfo>
        </xs:annotation>

        <xs:import namespace="http://www.bea.com/xml/ns/wlevs/config/application"
                schemaLocation="wlevs_application_config.xsd"/>

        <xs:element name="config">
                <xs:complexType>
                        <xs:choice maxOccurs="unbounded">
                                <xs:element name="adapter" type="HelloWorldAdapterConfig"/>
                                <xs:element name="processor" type="wlevs:DefaultProcessorConfig"/>
                                <xs:element name="stream" type="wlevs:DefaultStreamConfig"/>
                         </xs:choice>
                </xs:complexType>
        </xs:element>

        <xs:complexType name="HelloWorldAdapterConfig">
                <xs:complexContent>
                        <xs:extension base="wlevs:AdapterConfig">
                                <xs:sequence>
                                        <xs:element name="message" type="xs:string"/>
                                </xs:sequence>
                        </xs:extension>
                </xs:complexContent>
        </xs:complexType>
</xs:schema>

Programming Access to the Configuration of an Adapter

When you deploy your application, Oracle CEP maps the configuration of each component (specified in the component configuration XML files) into Java objects using the Java Architecture for XML Binding (JAXB) standard. Because there is a single XML element that contains the configuration data for each component, JAXB in turn also produces a single Java class that represents this configuration data. Oracle CEP passes an instance of this Java class to the component (processor, stream, or adapter) at runtime when the component is initialized, and also whenever there is a dynamic change to the component’s configuration.

In your adapter implementation, you can use metadata annotations to specify the Java methods that are invoked by Oracle CEP at runtime. Oracle CEP passes an instance of the configuration Java class to the specified methods; you can then program these methods to get specific runtime configuration information about the adapter. The following example shows how to annotate the activateAdapter() method with the @Activate annotation to specify the method invoked when the adapter configuration is first activated:

@Activate
public void activateAdapter(HelloWorldAdapterConfig adapterConfig) {
   this.message = adapterConfig.getMessage();
}

By default, the date type of the adapter configuration Java class is com.bea.wlevs.configuration.application.DefaultAdapterConfig. If, however, you have extended the configuration of your adapter by creating your own XSD file that describes the configuration XMLfile, then you specify the type in the XSD file. In the preceding example, because the HelloWorld sample extends the configuration of its adapter, the data type of the Java configuration object is com.bea.wlevs.example.helloworld.HelloWorldAdapterConfig.

The metadata annotations provided are as follows:

Passing Login Credentials from an Adapter to the Data Feed Provider

If your adapter accesses an external data feed, the adapter might need to pass login credentials (username and password) to the data feed for user authentication.

The simplest, and least secure, way to do this is to hard-code the non-encrypted login credentials in your adapter Java code. However, this method does not allow you to encrypt the password or later change the login credentials without recompiling the adapter Java code.

The following procedure describes a different method that takes these two issues into account. In the procedure, it is assumed that the username to access the data feed is juliet and the password is superSecret.

Updating the Adapter Code to Access the Login Credential Properties

This section describes how update your adapter Java code to dynamically get the user and password values from the extended adapter configuration, and then use the com.bea.core.encryption.EncryptionService API to decrypt the encrypted password. The code snippets below build on the HelloWorld adapter Java code, shown in Programming the Adapter Class: Guidelines.