13 HTTP Publish-Subscribe Server

An HTTP Publish-Subscribe (HTTP pub-sub) server enables web clients to subscribe to channels and publish messages to the channels using asynchronous messaging over HTTP. You can configure an HTTP pub-sub server to subscribe to channels, use a specific type of transport, set a time out, indicate a specific work manager to deliver messages to clients, and so on.

This chapter includes the following sections:

13.1 Default HTTP Pub-Sub Server

Every Oracle Stream Analytics server has a default HTTP pub-sub server. Oracle Stream Analytics Visualizer and the Record and Playback sample application use the default HTTP pub-sub server internally. An installation can use the default HTTP pub-sub server, or have a software developer create a custom HTTP pub-sub server.

In Oracle Stream Analytics, 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. An administrator then uses Oracle Stream Analytics Visualizer to add new channels and configure security for the channels. See Using Visualizer for Oracle Stream Analytics.

The <http-pubsub> element in the config.xml file contains the HTTP pub-sub server configuration. By default, the HTTP pub-sub server has the following configuration. See Schema Reference for Oracle Stream Analytics for information about the supported configuration settings.

<http-pubsub>
  <name>pubsub</name>
  <path>/pubsub</path>
  <pub-sub-bean>
    <server-config>
      <name>/pubsub</name>
      <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>

<path>/pubsub</path>: The URL to the HTTP pub-sub server. In a browser, you can locate the HTTP pub-sub server by typing http://host:port/pubsub, where host and port refer to the computer on which Oracle Stream Analytics is running and the port number to which it listens, respectively. For example, http://myhost.com:9102/pubsub.
<supported-transport>: The transport mode. The default is long-polling transport.
<publish-without-connect-allowed>true</publish-without-connect-allowed>: Allows clients to publish messages to a channel without having to explicitly connect to the HTTP pub-sub server.
Includes the following three channels that are used internally by Oracle Stream Analytics Visualizer. Do not delete these channels:
- /evsmonitor
- /evsalert
- /evsdomainchange

13.2 HTTP Publish-Subscribe Adapters

Oracle Stream Analytics provides two built-in adapters that provide HTTP pub-sub server functionality in applications. A software developer adds these adapters to an application to publish messages or subscribe to a server to receive messages.

In an application, a software developer uses the HTTP pub-sub adapters as follows:

Uses the HTTP Publisher adapter to send JavaScript Object Notation (JSON) event data out of the EPN to a web-based user interface.
Uses the HTTP Subscriber adapter to accept JavaScript Object Notation (JSON) event data entering the EPN. JSON event data comes from an HTTP server where user actions generate events.

If a software developer needs the HTTP pub-sub server to perform additional steps such as monitoring, collecting, or interpreting incoming messages from clients, then he or she must use the server-side HTTP pub-sub server APIs to program this functionality. See the following packages:

com.bea.wlevs.adapters.httppubsub.api
com.bea.wlevs.adapters.httppubsub.support

See Java API Reference for Oracle Stream Analytics.

13.3 Server Architecture

The HTTP Publish-Subscribe server enables clients to subscribe to a channel (similar to a topic in JMS) and receive messages as they become available. In contrast, traditional web applications require that all communication be initiated by the client.

The server can only push updated data to its clients if it receives an explicit request. However, dynamic real-time applications require that the server send data regardless of whether the client explicitly requested it.

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 that 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 pushing event messages to subscribed clients. 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.

There is a one-to-one relationship between a servlet and an HTTP pub-sub server. 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 obtain a handle to its associated HTTP pub-sub server.

Figure 13-1 shows the basic Oracle Stream Analytics HTTP pub-sub server architecture.

Figure 13-1 HTTP Publish-Subscribe Server in Oracle Stream Analytics

Description of "Figure 13-1 HTTP Publish-Subscribe Server in Oracle Stream Analytics"

13.4 Create a New HTTP Publish-Subscribe Server

This procedure describes how to create a new HTTP pub-sub server.

See Default HTTP Pub-Sub Server for a full example from the config.xml of a configured HTTP pub-sub server.

Create a New HTTP Publish-Subscribe Server

If the Oracle Stream Analytics server is running, stop it.

See Start and Stop Servers.
In an XML editor, open the Oracle Stream Analytics server config.xml file.

By default this file is in Oracle/Middleware/my_oep/user_projects/domains/<domainname>/<servername>/config.

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.

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>

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 Schema Reference for Oracle Stream Analytics.

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 Stream Analytics server supports the following transports:
  - long-polling: Using this transport, the client requests information from Oracle Stream Analytics server and if Oracle Stream Analytics server does not have information available, it does not reply until it has. When the Oracle Stream Analytics 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 Bayeux protocol.
- 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.
```
<server-config>
...
   <work-manager>myWorkManager</work-manager>
</server-config>
```
  See Schema Reference for Oracle Stream Analytics.
- 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 has not sent back a connect/reconnect message.
```
<server-config>
...
   <client-timeout-secs>600</client-timeout-secs>
</server-config>
```
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>
```
Save the config.xml file.
Start the Oracle Stream Analytics server.

See Start and Stop Servers.
Use Oracle Stream Analytics Visualizer to configure or add channels. See:
- See Using Visualizer for Oracle Stream Analytics
Use Oracle Stream Analytics Visualizer to configure security for the channels. See:
- See Using Visualizer for Oracle Stream Analytics
- Configure HTTP Publish-Subscribe Server Channel Security.

13.5 Configure an Existing HTTP Publish-Subscribe Server

This procedure describes how to configure an existing HTTP pub-sub server.

See Default HTTP Pub-Sub Server for a full example from the config.xml of a configured HTTP pub-sub server.

Configure an Existing HTTP Publish-Subscribe Server

If the Oracle Stream Analytics server is running, stop it.

See Start and Stop Servers.
In an XML editor, open the Oracle Stream Analytics server config.xml file.

By default this file is in Oracle/Middleware/my_oep/user_projects/domains/<domainname>/<servername>/config.
Search for the http-pubsub element that corresponds to the HTTP pub-sub server you want to configure.
For example, to configure the default HTTP pub-sub server, locate the following entry:
```
<http-pubsub>
    <name>pubsub</name>
    <path>/pubsub</path>
    <pub-sub-bean>
        <server-config>
        ...
</http-pubsub>
```
Update the server-config child element of the pub-sub-bean element, which is a child element of http-pubsub, with HTTP pub-sub server configuration as required.
For the full list of possible elements, see Schema Reference for Oracle Stream Analytics.

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 Stream Analytics server supports the following transports:
  - long-polling: Using this transport, the client requests information from Oracle Stream Analytics server and if Oracle Stream Analytics server does not have information available, it does not reply until it has. When the Oracle Stream Analytics 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. The Bayeux protocol requires this. For more about the Bayeux protocol, see http://svn.cometd.org/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.
```
<server-config>
... 
    <work-manager>myWorkManager</work-manager>
</server-config> 
```
  See Using Visualizer for Oracle Stream Analytics.
- 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> 
```
Save the config.xml file.
Start the Oracle Stream Analytics server.

See Start and Stop Servers.
Use Oracle Stream Analytics Visualizer to configure or add channels. See:
- See Using Visualizer for Oracle Stream Analytics.
Use Oracle Stream Analytics Visualizer to configure security for the channels. See:
- See Using Visualizer for Oracle Stream Analytics.
- Configure HTTP Publish-Subscribe Server Channel Security.