Oracle® CEP IDE Developer's Guide for Eclipse Release 11gR1 (11.1.1) E14301-01 |
|
![]() Previous |
![]() Next |
This section contains information on the following subjects:
Section 7.1, "Overview of HTTP Publish-Subscribe Server Adapter Configuration"
Section 7.2, "Using the Built-In HTTP Pub-Sub Adapters in an Application"
An HTTP Publish-Subscribe server (pub-sub server) is a mechanism whereby Web clients, such as browser-based clients, subscribe to channels, receive messages as they become available, and publish messages to these channels, all using asynchronous messages over HTTP. A channel is similar to a JMS topic.
Every instance of Oracle CEP includes a pub-sub server that programmers can use to implement HTTP publish-subscribe functionality in their applications. The pub-sub server is configured in the config.xml
file along with other server services such as Jetty and JDBC datasources. The pub-sub server is based on the Bayeux protocol (see http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html
) proposed by the cometd project (see http://cometd.com/
). The Bayeux protocol defines a contract between the client and the server for communicating with asynchronous messages over HTTP.
In Oracle CEP, programmers access HTTP publish-subscribe functionality by using the following built-in HTTP publish-subscribe adapters (pub-sub adapters):
Publishing to a channel: see Section 7.1.1, "Overview of the Built-In Pub-Sub Adapter for Publishing"
Local publishing to a channel: see Section 7.1.1.1, "Local Publishing".
Remote publishing to a channel: see Section 7.1.1.2, "Remote Publishing".
Subscribing to a channel: see Section 7.1.2, "Overview of the Built-In Pub-Sub Adapter for Subscribing".
Oracle CEP also provides a pub-sub API for programmers to create their own custom pub-sub adapters for publishing and subscribing to a channel, if the built-in pub-sub adapters are not adequate. For example, programmers might want to filter incoming messages from a subscribed channel, dynamically create or destroy local channels, and so on. The built-in pub-sub adapters do not provide this functionality, which is why programmers must implement their own custom pub-sub adapters in this case. For details, see Chapter 8, "Configuring Custom Adapters, Event Beans, and Spring Beans."
By default, Oracle CEP performs automatic conversion to and from Oracle CEP event types. Alternatively, you can create a custom converter. See Section 7.2.1, "Creating a Custom Converter Between the HTTP Pub-Sub Messages and Event Types".
Oracle CEP can also automatically convert between JSON messages and Oracle CEP event types. See Section 7.1.3, "Converting Between JSON Messages and Event Types".
The built-in pub-sub adapters work like any other adapter: they are stages in the event processing network, they are defined in the EPN assembly file, and they are configured with the standard component configuration files. Typical configuration options include specifying channels, specifying the local or remote pub-sub server, and user authentication.
The pub-sub server can communicate with any client that can understand the Bayeux protocol. Programmers developer their Web clients using one of the following frameworks:
Dojo JavaScript library (see http://dojotoolkit.org/
) that supports the Bayeux protocol. Oracle CEP does not provide this library.
WebLogic Workshop Flex plug-in that enables development of a Flex client that uses the Bayeux protocol to communicate with a pub-sub server.
For information on securing an HTTP pub-sub server channel, see "Configuring HTTP Publish-Subscribe Server Channel Security" in the Oracle CEP Administrator's Guide.
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:
For more information, see Section 7.1, "Overview of HTTP Publish-Subscribe Server Adapter Configuration".
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
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.
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
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.
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
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".
Oracle CEP can automatically convert incoming 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.
The following procedure describes typical steps for using the built-in pub-sub adapters in your Oracle CEP application. See Chapter 8, "Configuring Custom Adapters, Event Beans, and Spring Beans," for details about creating a custom pub-sub adapter.
Note: This section assumes that you have already created an Oracle CEP application, along with its EPN assembly file and component configuration files, and that you want to update the application to use the built-in pub-sub adapters. If this is not true, refer to Chapter 1, "Overview of Creating Oracle CEP Applications" for general information about creating an Oracle CEP application. |
To use the built-in HTTP pub-sub adapters in an application:
Optionally create a converter Java class if you want to customize the way the inbound or outbound messages are converted into event types. This step is optional because you can let Oracle CEP make the conversion based on mapping property names between the messages and a specified event type.
See Section 7.2.1, "Creating a Custom Converter Between the HTTP Pub-Sub Messages and Event Types."
If you are going to use the local HTTP pub-sub server associated with the Oracle CEP instance for local publishing, use Visualizer, the Oracle CEP Administration Tool, to add new channels with the channel pattern required by your application.
For details, see "How to Configure Security for an HTTP Publish-Subscribe Channel" in the Oracle CEP Visualizer User's Guide.
Configure the built-in pub-sub adapters you are going to add to you application by updating the component configuration files.
Update the EPN assembly file, adding declarations for each built-in pub-sub adapter you are adding to your application.
Update the MANIFEST.MF
file of your application, adding the package com.bea.core.encryption
to the Import-Package
header. For example:
Import-Package:
com.bea.core.encryption
com.bea.wlevs.adapter.defaultprovider;version="2.0.0.0",
...
See Section 14.2.2.1, "Creating the MANIFEST.MF File" for additional information on the manifest file.
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 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.1, "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:
Open the configuration XML file using your favorite XML editor.
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>
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
.
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>
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
.
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.
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>
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.