8 Configuring HTTP Publish-Subscribe for Oracle CEP

This section contains information on the following subjects:

8.1 Overview of HTTP Publish-Subscribe

An HTTP Publish-Subscribe Server (HTTP pub-sub server) is a mechanism whereby Web clients subscribe to channels and then publish messages to these channels using asynchronous messages over HTTP.

The simple request/response nature of a standard Web application requires that all communication be initiated by the client; this means that the server can only push updated data to its clients if it receives an explicit request. This mechanism is adequate for traditional applications in which data from the server is required only when a client requests it, but inadequate for dynamic real-time applications in which the server must send data even if a client has not explicitly requested it. The client can use the traditional HTTP pull approach to check and retrieve the latest data at regular intervals, but this approach is lacking in scalability and leads to high network traffic because of redundant checks. The HTTP Publish-Subscribe Server solves this problem by allowing clients to subscribe to a channel (similar to a topic in JMS) and receive messages as they become available.

The HTTP pub-sub server is based on the Bayeux protocol proposed by the cometd project. The Bayeux protocol defines a contract between the client and the server for communicating with asynchronous messages over HTTP. It allows clients to register and subscribe to channels, which are named destinations or sources of events. Registered clients, or the HTTP pub-sub server itself, then publishes messages to these channels which in turn any subscribed clients receive.

The HTTP pub-sub server can communicate with any client that can understand the Bayeux protocol. The HTTP pub-sub server is responsible for identifying clients, negotiating trust, exchanging Bayeux messages, and, most importantly, pushing event messages to subscribed clients.

Figure 8-1 describes the basic architecture of the HTTP pub-sub server included in Oracle CEP.

Figure 8-1 HTTP Publish-Subscribe Server in Oracle CEP

Description of Figure 8-1 follows
Description of "Figure 8-1 HTTP Publish-Subscribe Server in Oracle CEP"

8.1.1 How the HTTP Pub-Sub Server Works

There is a one-to-one relationship between a servlet and an HTTP pub-sub server; in other words, each servlet has access to one unique HTTP pub-sub server. Each HTTP pub-sub server has its own list of channels. The servlet uses a context object to get a handle to its associated HTTP pub-sub server.

In Oracle CEP, HTTP pub-sub server instances are configured in the config.xml file of the server instance. System administrator uses the config.xml to configure the name of the HTTP pub-sub server, specify the transport and other parameters. You then use Oracle CEP Visualizer to add new channels and configure security for the channels.

Oracle CEP application developers can optionally use the built-in HTTP pub-sub adapters to publish and subscribe to channels within their applications. If, however, developers need the HTTP pub-sub server to perform additional steps, such as monitoring, collecting, or interpreting incoming messages from clients, then they must use the server-side HTTP pub-sub server APIs to program this functionality.

For Web 2.0 Ajax clients (such as Dojo) or rich internet applications (such as Adobe Flex) to communicate with the HTTP pub-sub server, the clients need a library that supports the Bayeux protocol. The Dojo JavaScript library provides four different transports, of which two are supported by the HTTP pub-sub server: long-polling and callback-polling.

8.1.2 HTTP Pub-Sub Server Support in Oracle CEP

Every Oracle CEP server includes a default HTTP pub-sub server. This server is used internally by Oracle CEP Visualizer and by the Record and Playback example. You can either use the default HTTP pub-sub server for your own Web 2.0 application or create a new one.

The default HTTP pub-sub server has the following properties:

  • HTTP pub-sub server URL— http://host:port/pubsub, where host and port refer to the computer on which Oracle CEP is running and the port number to which it listens, respectively.

  • Transport: Uses long-polling transport.

  • Allows clients to publish messages to a channel without having explicitly connected to the HTTP pub-sub server.

  • Includes the following three channels used internally by Oracle CEP Visualizer; do not delete these channels:

    • /evsmonitor

    • /evsalert/

    • /evsdomainchange

For details about configuring the default HTTP pub-sub server, or creating a new one, see:

Oracle CEP also includes two built-in adapters that easily harness HTTP pub-sub server functionality in your applications. By adding these adapters to your application you can both publish messages or subscribe to a server to receive messages, using either the local HTTP pub-sub server or a remote one.

For more information, see "Using and Creating HTTP Publish-Subscribe Adapters" in the Oracle CEP IDE Developer's Guide for Eclipse.

8.2 Creating a New HTTP Publish-Subscribe Server

The following procedure describes how to create a new HTTP pub-sub server. See Section 8.4, "Example HTTP Publish-Subscribe Server Configuration" for a full example from the config.xml of a configured HTTP pub-sub server.

To create a new HTTP publish-subscribe server:

  1. If the Oracle CEP server is running, stop it.

    See Section 1.5.4, "Starting and Stopping Oracle CEP Servers".

  2. Using your favorite XML editor, open the Oracle CEP server's config.xml file.

    This file is located in the DOMAIN_DIR/servername/config directory, where DOMAIN_DIR refers to the domain directory and servername refers to the name of the server, such as /oracle_cep/user_projects/myDomain/defaultserver/config.

  3. Add an http-pubsub child element of the root config element of config.xml, with name, path and pub-sub-bean child elements, as shown in bold:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ns2:config xmlns:ns2="http://www.bea.com/ns/wlevs/config/server">
        <domain>
            <name>myDomain</name>
        </domain>
        ....
        <http-pubsub>
          <name>myPubSubServer</name>
          <path>/myPath</path>
          <pub-sub-bean>
             ...
          </pub-sub-bean>
        </http-pubsub>
        ...
    </ns2:config>
    

    Set the name element to the internal name of the HTTP pub-sub server.

    Set the path element to the string that you want to appear in the URL for connecting to the HTTP pub-sub server.

    The next step describes the pub-sub-bean element.

  4. Add server-config and channels child elements of the pub-sub-bean element:

        <http-pubsub>
          <name>myPubSubServer</name>
          <path>/myPath</path>
          <pub-sub-bean>
            <server-config>
               ...
            </server-config>
            <channels>
               ...
            </channels>
          </pub-sub-bean>
        </http-pubsub>
    
  5. Update the server-config child element of the pub-sub-bean element with HTTP pub-sub server configuration as required.

    For the full list of possible elements, see "Server Configuration XSD Schema: wlevs_server_config.xsd" in the Oracle CEP IDE Developer's Guide for Eclipse.

    The following are the most common configuration options:

    • Add a supported-transport element to specify the transport.

      The format of this element is as follows:

      <server-config>
          <supported-transport>
              <types>
                  <element>long-polling</element>
              </types>
          </supported-transport>
      ... 
      </server-config>
      

      Oracle CEP server supports the following transports:

      • long-polling: Using this transport, the client requests information from Oracle CEP server and if Oracle CEP server does not have information available, it does not reply until it has. When the Oracle CEP server replies, the client typically sends another request immediately.

      • callback-polling: Use this transport for HTTP publish-subscribe applications using a cross domain configuration in which the browser downloads the page from one Web server (including the Javascript code) and connects to another server as an HTTP publish-subscribe client. This is required by the Bayeaux protocol. For more information on the Bayeaux protocol, see http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html.

    • Add a publish-without-connect-allowed element to specify whether clients can publish messages without having explicitly connected to the HTTP pub-sub server; valid values are true or false:

      <server-config>
      ... 
          <publish-without-connect-allowed>true</publish-without-connect-allowed>
      </server-config> 
      
    • Add a work-manager element to specify the name of the work manager that delivers messages to clients. The value of this element corresponds to the value of the <name> child element of the work-manager you want to assign. See Section 5.2.3, "work-manager Configuration Object" for details.

      <server-config>
      ... 
          <work-manager>myWorkManager</work-manager>
      </server-config> 
      
    • Add a client-timeout-secs element to specify the number of seconds after which the HTTP pub-sub server disconnects a client if the client does has not sent back a connect/reconnect message.

      <server-config>
      ... 
          <client-timeout-secs>600</client-timeout-secs>
      </server-config> 
      
  6. Update the channels child element with at least one channel pattern.

    Channel patterns always begin with a forward slash (/). Clients subscribe to these channels to either publish or receive messages. Add a channel pattern as shown:

    <channels>
        <element>
            <channel-pattern>/mychannel</channel-pattern>
        </element>
    </channels>
    
  7. Save the config.xml file.

  8. Start the Oracle CEP server.

    See Section 1.5.4, "Starting and Stopping Oracle CEP Servers".

  9. Use Oracle CEP Visualizer to configure or add channels. See:

  10. Use Oracle CEP Visualizer to configure security for the channels. See:

8.3 Configuring an Existing HTTP Publish-Subscribe Server

The following procedure describes how to configure an existing HTTP pub-sub server. See Section 8.4, "Example HTTP Publish-Subscribe Server Configuration" for a full example from the config.xml of a configured HTTP pub-sub server.

To configure an existing HTTP publish-subscribe server:

  1. If the Oracle CEP server is running, stop it.

    See Section 1.5.4, "Starting and Stopping Oracle CEP Servers".

  2. Using your favorite XML editor, open the Oracle CEP server's config.xml file.

    This file is located in the DOMAIN_DIR/servername/config directory, where DOMAIN_DIR refers to the domain directory and servername refers to the name of the server, such as /oracle_cep/user_projects/myDomain/defaultserver/config.

  3. Search for the http-pubsub element that corresponds to the HTTP pub-sub server you want to configure. For example, the default HTTP pub-sub server is as follows:

    <http-pubsub>
        <name>pubsub</name>
        <path>/pubsub</path>
        <pub-sub-bean>
            <server-config>
            ...
    </http-pubsub>
    
  4. Update the server-config child element of the pub-sub-bean element (which in turn is a child element of http-pubsub) with HTTP pub-sub server configuration as required.

    For the full list of possible elements, see "Server Configuration XSD Schema: wlevs_server_config.xsd" in the Oracle CEP IDE Developer's Guide for Eclipse.

    The following are the most common configuration options:

    • Add a supported-transport element to specify the transport.

      The format of this element is as follows:

      <server-config>
          <supported-transport>
              <types>
                  <element>long-polling</element>
              </types>
          </supported-transport>
      ... 
      </server-config>
      

      Oracle CEP server supports the following transports:

      • long-polling: Using this transport, the client requests information from Oracle CEP server and if Oracle CEP server does not have information available, it does not reply until it has. When the Oracle CEP server replies, the client typically sends another request immediately.

      • callback-polling: Use this transport for HTTP publish-subscribe applications using a cross domain configuration in which the browser downloads the page from one Web server (including the Javascript code) and connects to another server as an HTTP publish-subscribe client. This is required by the Bayeaux protocol. For more information on the Bayeaux protocol, see http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html.

    • Add a publish-without-connect-allowed element to specify whether clients can publish messages without having explicitly connected to the HTTP pub-sub server; valid values are true or false:

      <server-config>
      ... 
          <publish-without-connect-allowed>true</publish-without-connect-allowed>
      </server-config> 
      
    • Add a work-manager element to specify the name of the work manager that delivers messages to clients. The value of this element corresponds to the value of the name child element of the work-manager you want to assign. See Section 5.2.3, "work-manager Configuration Object" for details.

      <server-config>
      ... 
          <work-manager>myWorkManager</work-manager>
      </server-config> 
      
    • Add a client-timeout-secs element to specify the number of seconds after which the HTTP pub-sub server disconnects a client if the client does has not sent back a connect/reconnect message.

      <server-config>
      ... 
          <client-timeout-secs>600</client-timeout-secs>
      </server-config> 
      
  5. Save the config.xml file.

  6. Start the Oracle CEP server.

    See Section 1.5.4, "Starting and Stopping Oracle CEP Servers".

  7. Use Oracle CEP Visualizer to configure or add channels. See:

  8. Use Oracle CEP Visualizer to configure security for the channels. See:

8.4 Example HTTP Publish-Subscribe Server Configuration

The following snippet of the config.xml file shows the configuration of the default HTTP pub-sub server present in every Oracle CEP server:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:config xmlns:ns2="http://www.bea.com/ns/wlevs/config/server">
    <domain>
        <name>myDomain</name>
    </domain>
    ....
    <http-pubsub>
        <name>pubsub</name>
        <path>/pubsub</path>
        <pub-sub-bean>
            <server-config>
                <supported-transport>
                    <types>
                    <element>long-polling</element>
                    </types>
                </supported-transport>
                <publish-without-connect-allowed>true</publish-without-connect-allowed>
            </server-config>
            <channels>
                <element>
                    <channel-pattern>/evsmonitor</channel-pattern>
                </element>
                <element>
                    <channel-pattern>/evsalert</channel-pattern>
               </element>
                <element>
                    <channel-pattern>/evsdomainchange</channel-pattern>
                </element>
            </channels>
        </pub-sub-bean>
    </http-pubsub>
...
</ns2:config>