7 Configuring HTTP Publish-Subscribe Server Adapters

7.1.1 Overview of the Built-In Pub-Sub Adapter for Publishing

You can use the built-in pub-sub adapter for publishing events to a channel. The built-in pub-sub adapter supports the following publishing modes:

• Section 7.1.1.1, "Local Publishing"

• Section 7.1.1.2, "Remote Publishing"

For more information, see Section 7.1, "Overview of HTTP Publish-Subscribe Server Adapter Configuration".

7.1.1.1 Local Publishing

Figure 7-1 shows how the built-in pub-sub adapter for local publishing fits into a simple event processing network. The arbitrary adapter and processor are not required, they are just an example of possible components in your application in addition to the pub-sub adapter.

Figure 7-1 Built-In Pub-Sub Adapter For Local Publishing

Description of "Figure 7-1 Built-In Pub-Sub Adapter For Local Publishing"

Note the following in Figure 7-1:

• Events flow from some source into an adapter of an application running in Oracle CEP. This adapter is not required, it is shown only as an example.

• The events flow from the adapter to an arbitrary processor; again, this processor is not required.

• The processor sends the events to the built-in pub-sub adapter for local publishing. The adapter in turn sends the events to the local HTTP pub-sub server configured for the Oracle CEP instance on which the application is deployed. The pub-sub adapter sends the messages to the channel for which it has been configured.

• The local HTTP pub-sub server configured for Oracle CEP then sends the event as a message to all subscribers of the local channel.

7.1.1.2 Remote Publishing

Figure 7-2 shows how the built-in pub-sub adapter for remote publishing fits into a simple event processing network.

Figure 7-2 Built-In Pub-Sub Adapter For Remote Publishing

Description of "Figure 7-2 Built-In Pub-Sub Adapter For Remote Publishing"

Note the following in Figure 7-2:

• Events flow from some source into an adapter of an application running in Oracle CEP. The arbitrary adapter is not required, it is shown only as an example.

• The events flow from the adapter to an arbitrary processor; again, this processor is not required.

• The processor sends the events to the built-in pub-sub adapter for remote publishing. The adapter in turn sends the events as messages to the remote HTTP pub-sub server for which the adapter is configured; this HTTP pub-sub server could be on another Oracle CEP instance, a WebLogic Server instance, or any other third-party implementation. The pub-sub adapter sends the messages to the channel for which it has been configured.

• The remote HTTP pub-sub server then sends the message to all subscribers of the channel.

7.1.2 Overview of the Built-In Pub-Sub Adapter for Subscribing

Figure 7-3 shows how the built-in pub-sub adapter for subscribing fits into a simple event processing network. The arbitrary processor and business POJO are not required, they are just an example of possible components in your application in addition to the pub-sub adapter.

Figure 7-3 Built-In Pub-Sub Adapter For Subscribing

Description of "Figure 7-3 Built-In Pub-Sub Adapter For Subscribing"

Note the following in Figure 7-3:

• Messages are published to a remote HTTP pub-sub server, which could be another instance of Oracle CEP, WebLogic Server, or a third-party implementation. The messages are typically published by Web based clients (shown in graphic), by the HTTP pub-sub server itself, or another server application.

• The built-in pub-sub adapter running in an Oracle CEP application subscribes to the HTTP pub-sub server and receives messages from the specified channel. The adapter converts the messages into the event type configured for the adapter.

• The pub-sub adapter sends the events to a processor. This processor is not required, it is shown only as an example of a typical Oracle CEP application.

• The processor sends the events to a business POJO. Again, this business POJO is not required.

For more information, see Section 7.1, "Overview of HTTP Publish-Subscribe Server Adapter Configuration".

7.1.3 Converting Between JSON Messages and Event Types

Oracle CEP can automatically convert incoming JavaScript Object Notation (JSON) messages to event types, and vice versa in the outbound case. However, if you want to customize the way a JSON message (either inbound via a HTTP pub-sub adapter for subscribing or outbound via an HTTP pub-sub adapter for publishing) is converted to an event type, or vice versa, you must create your own converter bean. See Section 7.2.1, "Creating a Custom Converter Between the HTTP Pub-Sub Messages and Event Types" for details.

If you do not provide your own converter class, and instead let Oracle CEP take care of the conversion between messages and event types, the following is true:

• You must specify an event type that Oracle CEP uses in its conversion. See Section 7.2.2, "Configuring an HTTP Pub-Sub Adapter" for details.

• The default converter used in the HTTP adapter for subscribing creates a new event of the specified type for each incoming message. For each property of the specified event type, it looks for a corresponding property name in the JSON object that constitutes the message, and if found, sets the corresponding value.

• The default converter used in the HTTP adapter for publishing creates a JSON message for each event. For each property of the specified event type, a corresponding element is created in the output JSON message.

For more information, see http://www.json.org/.

7.2.1 Creating a Custom Converter Between the HTTP Pub-Sub Messages and Event Types

If you want to customize the way a message (either inbound via a HTTP pub-sub adapter for subscribing or outbound via an HTTP pub-sub adapter for publishing) is converted to an event type, or vice versa, you must create your own converter bean.

The custom converter bean for an inbound HTTP pub-sub message must implement the com.bea.wlevs.adapters.httppubsub.api.InboundMessageConverter interface. This interface has a single method:

public List convert(JSONObject message) throws Exception;

The message parameter corresponds to the incoming HTTP pub-sub message and the return value is a List of events that will be passed on to the next stage of the event processing network. The incoming message is assumed to be the JSON format.

The custom converter bean for an outbound HTTP pub-sub message must implement the com.bea.wlevs.adapters.httppubsub.api.OutboundMessageConverter interface. This interface has a single method:

public List<JSONObject> convert(Object event) throws Exception;

The parameters correspond to an event received by the outbound HTTP pub-sub adapter from the source node in the EPN and the return value is a List of JSON messages.

See the Oracle CEP Java API Reference for a full description of these APIs.

The following example shows the Java source of a custom converter bean that implements both InboundMessageConverter and OutboundMessageConvert; this bean can be used for both inbound and outbound HTTP pub-sub adapters:

package com.sample.httppubsub;
import com.bea.wlevs.adapters.httppubsub.api.InboundMessageConverter;
import com.bea.wlevs.adapters.httppubsub.api.OutboundMessageConverter;
import com.bea.httppubsub.json.JSONObject;
import java.util.List;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;
public class TestConverter implements InboundMessageConverter, OutboundMessageConverter {
    public List convert(JSONObject message) throws Exception {
        List eventCollection = new ArrayList();
        PubsubTestEvent event = new PubsubTestEvent();
        event.setMessage("From TestConverter: " + message);
        eventCollection.add(event);
        return eventCollection;
    }
    public List<JSONObject> convert(Object event) throws Exception {
        List<JSONObject> list = new ArrayList<JSONObject>(1);
        Map map = new HashMap();
        map.put("message", ((PubsubTestEvent) event).getMessage());
        list.add(new JSONObject(map));
        return list;
    }
}

You can use the GSON Java library to help you convert Java objects to JSON format.

For more information, see:

• http://www.json.org/

• http://code.google.com/p/google-gson

7.2.2 Configuring an HTTP Pub-Sub Adapter

You configure the built-in pub-sub adapters in their respective configuration files, similar to how you configure other components in the event processing network, such as processors or streams. For general information about these configuration files, see Section 1.1.5, "Component Configuration Files."

The following configuration file shows a complete example of configuring each of the three built-in pub-sub adapters; the procedure following the example uses the example to show how to create your own file:

<?xml version="1.0" encoding="UTF-8"?>
<n1:config 
  xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/application wlevs_application_config.xsd"
  xmlns:n1="http://www.bea.com/ns/wlevs/config/application" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <http-pub-sub-adapter>
        <name>remotePublisher</name>
        <server-url>http://myhost.com:9102/pubsub</server-url>
        <channel>/channel1</channel>
        <event-type>com.mycompany.httppubsub.PubsubEvent</event-type>
        <user>wlevs</user>
        <password>wlevs</password>
    </http-pub-sub-adapter>
    <http-pub-sub-adapter>
        <name>localPublisher</name>
        <server-context-path>/pubsub</server-context-path>
        <channel>/channel2</channel>
    </http-pub-sub-adapter>
    <http-pub-sub-adapter>
        <name>remoteSubscriber</name>
        <server-url>http://myhost.com:9102/pubsub</server-url>
        <channel>/channel3</channel>
        <event-type>com.mycompany.httppubsub.PubsubEvent</event-type>
    </http-pub-sub-adapter>
</n1:config>

The following procedure describes the main steps to configure the built-in pub-sub adapters for your application. For simplicity, it is assumed in the procedure that you are going to configure all components of an application in a single configuration XML file and that you have already created this file for your application.

See Section B.2, "Component Configuration Schema wlevs_application_config.xsd" for the complete XSD Schema that describes the configuration of the built-in pub-sub adapters.

To configure an HTTP pub-sub adapter:

1. Open the configuration XML file using your favorite XML editor.

2. For each built-in pub-sub adapter you want to configure, add a http-pub-sub-adapter child element of the config root element; use the <name> child element to uniquely identify it. This name value will be used later as the id attribute of the wlevs:adapter element in the EPN assembly file that defines the event processing network of your application. This is how Oracle CEP knows to which particular adapter in the EPN assembly file this adapter configuration applies.

   For example, assume your configuration file already contains a processor (contents removed for simplicity) and you want to configure instances of each of the three built-in pub-sub adapters; then the updated file might look like the following; details of the adapter configuration will be added in later steps:

   <?xml version="1.0" encoding="UTF-8"?>
   <n1:config
    xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/application wlevs_application_config.xsd" 
    xmlns:n1="http://www.bea.com/ns/wlevs/config/application" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <processor>
         ...
       </processor>
       <http-pub-sub-adapter>
           <name>remotePublisher</name>
           ...
       </http-pub-sub-adapter>
       <http-pub-sub-adapter>
           <name>remoteSubscriber</name>
           ...
       </http-pub-sub-adapter>
       <http-pub-sub-adapter>
           <name>localPublisher</name>
           ...
       </http-pub-sub-adapter>
   </n1:config>
   

3. For each remote pub-sub adapter (for both publishing and subscribing), add a server-url child element of http-pub-sub-adapter to specify the URL of the remote HTTP pub-sub server to which the Oracle CEP application will publish or subscribe, respectively. The remote pub-sub server could be another instance of Oracle CEP, or a WebLogic Server instance, or it could be any third-party HTTP pub-sub server. For example:

   <http-pub-sub-adapter>
       <name>remotePublisher</name>
           <server-url>http://myhost.com:9102/pubsub</server-url>
           ...
   </http-pub-sub-adapter>
   

   In the example, the URL of the remote HTTP pub-sub server to which the remotePublisher adapter will publish events is http://myhost.com:9102/pubsub.

4. For each local pub-sub adapter for publishing, add a server-context-path element to specify the path of the local HTTP pub-sub server associated with the Oracle CEP instance hosting the current Oracle CEP application.

   By default, each Oracle CEP server is configured with an HTTP pub-sub server with path /pubsub; if, however, you have created a new local HTTP pub-sub server, or changed the default configuration, then specify the value of the path child element of the http-pubsub element in the server's config.xml file. For example:

   <http-pub-sub-adapter>
           <name>localPublisher</name>
           <server-context-path>/pubsub</server-context-path>
           ...
       </http-pub-sub-adapter>
   

5. For all the pub-sub adapters, whether they are local or remote or for publishing or subscribing, add a channel child element to specify the channel that the pub-sub adapter publishes or subscribes to, whichever is appropriate. For example:

   <http-pub-sub-adapter>
       <name>localPublisher</name>
       <server-context-path>/pubsub</server-context-path>
       <channel>/channel2</channel>
   </http-pub-sub-adapter>
   

   In the example, the localPublisher pub-sub adapter publishes to a local channel with pattern /channel2.

6. For all pub-sub adapters for subscribing, add an event-type element that specifies the JavaBean to which incoming messages are mapped. You are required to specify this for all subscribing adapters. At runtime, Oracle CEP uses the incoming key-value pairs in the message to map the message data to the specified event type.

   You can also optionally use the event-type element in a pub-sub adapter for publishing if you want to limit the types of events that are published to just those specified by the event-type elements. Otherwise, all events sent to the pub-sub adapter are published. For example:

   <http-pub-sub-adapter>
       <name>remoteSubscriber</name>
       <server-url>http://myhost.com:9102/pubsub</server-url>
       <channel>/channel3</channel>
       <event-type>com.mycompany.httppubsub.PubsubEvent</event-type>
   </http-pub-sub-adapter>
   

   Be sure this event type has been registered in the EPN assembly file by specifying it as a child element of the wlevs:event-type-repository element.

7. Finally, if the HTTP pub-sub server to which the Oracle CEP application is publishing requires user authentication, add user and password (or encrypted-password) elements to specify the username and password or encrypted password. For example:

   <http-pub-sub-adapter>
       <name>remotePublisher</name>
       <server-url>http://myhost.com:9102/pubsub</server-url>
       <channel>/channel1</channel>
       <event-type>com.mycompany.httppubsub.PubsubEvent</event-type>
       <user>wlevs</user>
       <password>wlevs</password>
   </http-pub-sub-adapter>
   

7.2.3 Updating the EPN Assembly File

For each pub-sub adapter in your event processing network, you must add a corresponding wlevs:adapter tag to the EPN assembly file that describes the network; use the provider attribute to specify whether the adapter is for publishing or subscribing. Follow these guidelines:

• If you are using a built-in pub-sub adapter for publishing (either locally or remotely), set the provider attribute to httppub, as shown:

  <wlevs:adapter id="remotePublisher" provider="httppub"/>
  

  The value of the id attribute, in this case remotePublisher, must match the name specified for this built-in pub-sub adapter in its configuration file. Note that the declaration of the built-in adapter for publishing in the EPN assembly file does not specify whether this adapter is local or remote; you specify this in the adapter configuration file.

• If you are using a built-in pub-sub adapter for subscribing, set the provider attribute to httpsub, as shown:

  <wlevs:adapter id="remoteSubscriber" provider="httpsub"/>
  

  The value of the id attribute, in this case remoteSubscriber, must match the name specified for this built-in pub-sub adapter in its configuration file.

As with any other stage in the EPN, add listeners to the wlevs:adapter element to integrate the pub-sub adapter into the event processing network. Typically, a pub-sub adapter for subscribing is the first stage in an EPN (because it receives messages) and a pub-sub adapter for publishing would be in a later stage (because it sends messages). However, the requirements of your own Oracle CEP application define where in the network the pub-sub adapters fit in.

Also be sure that the event types used by the pub-sub adapters have been registered in the event type repository using the wlevs:event-type-repository element.

The following sample EPN file shows an event processing network with two built-in pub-sub adapters for publishing both local and remote publishing); see the text after the example for an explanation:

<?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="com.mycompany.httppubsub.PubsubEvent">
            <wlevs:class>com.mycompany.httppubsub.PubsubEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>
    <wlevs:adapter id="receiveFromFeed"
                   class="com.mycompany.httppubsub.ReceiveFromFeed">
    </wlevs:adapter>
    <wlevs:processor id="pubsubProcessor" />
    <wlevs:adapter id="remotePublisher" provider="httppub"/>
    <wlevs:adapter id="localPublisher" provider="httppub"/>
    <wlevs:channel id="feed2processor">
        <wlevs:source ref="receiveFromFeed"/>
        <wlevs:listener ref="pubsubProcessor"/>
    </wlevs:channel>
    <wlevs:channel id="pubsubStream">
        <wlevs:listener ref="remotePublisher"/>
        <wlevs:listener ref="localPublisher"/>
        <wlevs:source ref="pubsubProcessor"/>
    </wlevs:channel>
</beans>

In the preceding example:

• The receiveFromFeed adapter is a custom adapter that receives data from some data feed; the details of this adapter are not pertinent to this topic. The receiveFromFeed adapter then sends its events to the pubsubProcessor via the feed2processor channel.

• The pubsubProcessor processes the events from the receiveFromFeed adapter and then sends them to the pubsubStream channel, which in turn sends them to the two built-in pub-sub adapters: remotePublisher and localPublisher.

• Based on the configuration of these two pub-sub adapters (see examples in Section 7.2.2, "Configuring an HTTP Pub-Sub Adapter"), remotePublisher publishes events only of type com.mycompany.httppubsub.PubsubEvent and publishes them to the a channel called /channel1 on the HTTP pub-sub server hosted remotely at http://myhost.com:9102/pubsub.

  The localPublisher pub-sub adapter publishes all events it receives to the local HTTP pub-sub server, in other words, the one associated with the Oracle CEP server on which the application is running. The local pub-sub server's path is /pubsub and the channel to which the adapter publishes is called /channel2.

The following sample EPN file shows an event processing network with one built-in pub-sub adapter for subscribing; see the text after the example for an explanation:

<?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="com.mycompany.httppubsub.PubsubEvent">
            <wlevs:class>com.mycompany.httppubsub.PubsubEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>
    <wlevs:adapter id="remoteSubscriber" provider="httpsub">
        <wlevs:listener ref="myEventBean"/>
    </wlevs:adapter>
    <bean id="myEventBean"
          class="com.mycompany.httppubsub.MyEventBean">
    </bean>
    <wlevs:channel id="pubsubStream" advertise="true">
        <wlevs:listener>
            <bean id="mySink"
                  class="com.mycompany.httppubsub.MySink"/>
        </wlevs:listener>
        <wlevs:source ref="myEventBean"/>
    </wlevs:channel>
</beans>

In the preceding example:

• The remoteSubscriber adapter is a built-in pub-sub adapter for subscribing.

  Based on the configuration of this adapter (see examples in Section 7.2.2, "Configuring an HTTP Pub-Sub Adapter"), remoteSubscriber subscribes to a channel called /channel3 configured for the remote HTTP pub-sub server hosted at http://myhost.com:9102/pubsub. Oracle CEP converts each messages it receives from this channel to an instance of com.mycompany.httppubsub.PubsubEvent and then sends it a Spring bean called myEventBean.

• The myEventBean processes the event as described by the com.mycompany.httppubsub.MyEventBean class, and then passes it the mySink event source via the pubsubStream channel. This section does not discuss the details of these components because they are not pertinent to the HTTP pub-sub adapter topic.