Application Development Guide

Using the Java Message Service (JMS) Adapters

This section contains information on the following subjects:

Overview of Using the JMS Adapters

Oracle CEP provides two JMS adapters that you can use in your event applications to send and receive messages to and from a JMS queue, respectively, without writing any Java code. In particular:

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:

Oracle CEP supports the following two JMS providers: Oracle WebLogic JMS and TIBCO EMS JMS.

Oracle CEP includes a WebLogic JMS client. When connecting to Oracle WebLogic server, Oracle CEP uses the T3 client by default. You can use the IIOP WebLogic client by starting Oracle WebLogic Server with the -useIIOP command-line argument. This is a server-wide setting that is independent of the JMS code being used (whether it is one of the provided adapters or custom JMS code). It is not possible to mix T3 and IIOP usage within a running Oracle CEP server.

If you are using a JMS provider other than WebLogic JMS, such as TIBCO, you must include the appropriate client jar as a library within your application jar.

For general information about JMS, see Java Message Service on the Sun Developer Network.

Using JMS Adapters: Typical Steps

The following procedure describes the typical steps to use the JMS adapters provided by Oracle CEP.

Creating a Custom Converter Between JMS Messages and Event Types

If you want to customize the way a JMS message is converted to an event type, or vice versa, you must create your own converter bean.

The custom converter bean for an inbound JMS must implement the com.bea.wlevs.adapters.jms.api.InboundMessageConverter interface. This interface has a single method:

public List convert(Message message) throws MessageConverterException, JMSException;

The message parameter corresponds to the incoming JMS 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 custom converter bean for an outbound JMS must implement the com.bea.wlevs.adapters.jms.api.OutboundMessageConverter interface. This interface has a single method:

public List<Message> convert(Session session, Object event) throws MessageConverterException, JMSException;

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

See the Javadoc 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 JMS adapters:

package com.customer;

import com.bea.wlevs.adapters.jms.api.InboundMessageConverter;
import com.bea.wlevs.adapters.jms.api.MessageConverterException;
import com.bea.wlevs.adapters.jms.api.OutboundMessageConverter;

import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.Session;
import javax.jms.TextMessage;
import java.util.ArrayList;
import java.util.List;

public class MessageConverter implements InboundMessageConverter, OutboundMessageConverter {

    public List convert(Message message) throws MessageConverterException, JMSException {
        TestEvent event = new TestEvent();
        TextMessage textMessage = (TextMessage) message;
        event.setString_1(textMessage.getText());
        List events = new ArrayList(1);
        events.add(event);
        return events;
    }

    public List<Message> convert(Session session, Object inputEvent) throws MessageConverterException, JMSException {
        TestEvent event = (TestEvent) inputEvent;
        TextMessage message = session.createTextMessage("Text message: " + event.getString_1());
        List<Message> messages = new ArrayList<Message>();
        messages.add(message);
        return messages;
    }
}

Updating the EPN Assembly File With JMS Adapters

For each JMS adapter in your event processing network, you must add a corresponding <wlevs:adapter> tag to the EPN assembly file of your application; use the provider attribute to specify whether the JMS adapter is inbound or outbound. Follow these guidelines:

As with any other stage in the EPN, add listeners to the <wlevs:adapter> tag to integrate the JMS adapter into the event processing network. Typically, an inbound JMS adapter is the first stage in an EPN (because it receives messages) and an outbound JMS adapter 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 JMS adapters fit in.

The following sample EPN assembly file shows how to configure an outbound JMS adapter. The network is simple: a custom adapter called getData receives data from some feed, converts it into an event type and passes it to myProcessor, which in turn sends the events to the jmsOutbound JMS adapter via the streamOne stream. Oracle CEP automatically converts these events to JMS messages and sends the messages to the JMS queue configured in the component configuration file associated with the jmsOutbound adapter.

<?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="JMSEvent">
            <wlevs:class>com.customer.JMSEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>

    <!-- Custom adapter that gets data from somewhere and sends it to myProcessor -->
    <wlevs:adapter id="getData" 
                   class="com.customer.GetData">
        <wlevs:listener ref="myProcessor"/>
    </wlevs:adapter>

    <wlevs:processor id="myProcessor" />

    <wlevs:adapter id="jmsOutbound" provider="jms-outbound"/>

     <!-- Stream for events flowing from myProcessor to outbound JMS adapter -->

    <wlevs:stream id="streamOne">
       <wlevs:listener ref="jmsOutbound"/>
       <wlevs:source ref="myProcessor"/>
    </wlevs:stream>

</beans>

The following sample EPN assembly file shows how to configure an inbound JMS adapter. The network is simple: the inbound JMS adapter called jmsInbound receives messages from the JMS queue configured in its component configuration file. The Spring bean myConverter converts the incoming JMS messages into event types, and then these events flow to the mySink event bean.

<?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="JMSEvent">
            <wlevs:class>com.customer.JMSEvent</wlevs:class>
        </wlevs:event-type>
    </wlevs:event-type-repository>

    <!-- Event bean that is an event sink -->
    <wlevs:event-bean id="mySink" 
                         class="com.customer.MySink"/>

    <!-- Inbound JMS adapter with custom converter class; adapter sends events to mySink event bean-->
   <bean id="myConverter" class="com.customer.MessageConverter"/>
   <wlevs:adapter id="jmsInbound" provider="jms-inbound">
       <wlevs:instance-property name="converterBean" ref="myConverter"/>
       <wlevs:listener ref="mySink"/>
    </wlevs:adapter>

</beans>

Configuring the JMS Adapters

You configure the JMS 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 Component Configuration Files.

The root element for configuring a JMS adapter is <jms-adapter>. The <name> child element for a particular adapter must match the id attribute of the corresponding <wlevs:adapter> tag in the EPN assembly file that declares this adapter.

The following table describes the additional child elements of <jms-adapter> you can configure for both inbound and outbound JMS adapters.

The following table lists the optional child elements of <jms-adapter> you can configure for inbound JMS adapters only.

The following table lists the optional child elements of <jms-adapter> you can configure for outbound JMS adapters only.

For the full schema for the configuration of JMS adapters, see the XSD Schema.

The following configuration file shows a complete example of configuring both an inbound and outbound JMS adapter.

<?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">

    <jms-adapter>
        <name>jmsInbound</name>
        <jndi-provider-url>t3://localhost:7001</jndi-provider-url>
        <destination-jndi-name>Queue1</destination-jndi-name>
        <user>weblogic</user>
        <password>weblogic</password>
        <work-manager>JettyWorkManager</work-manager>
        <concurrent-consumers>1</concurrent-consumers>
        <session-transacted>false</session-transacted>
    </jms-adapter>

    <jms-adapter>
        <name>jmsOutbound</name>
        <event-type>JMSEvent</event-type>
        <jndi-provider-url>t3://localhost:7001</jndi-provider-url>
        <destination-jndi-name>Topic1</destination-jndi-name>
        <delivery-mode>nonpersistent</delivery-mode>
    </jms-adapter>

</n1:config>

The following snippet shows how to configure an inbound JMS adapter connecting to TIBCO EMS JMS:

<jms-adapter>
  <name>myJmsAdapter</name>
  <jndi-provider-url>t3://localhost:7222</jndi-provider-url>
  <jndi-factory>com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi-factory>
  <connection-jndi-name>TibcoQueueConnectionFactory</connection-jndi-name>
  <destination-jndi-name>MyQueue</destination-jndi-name>
</jms-adapter>

Encrypting Passwords in the JMS Adapter Configuration File

Use the following procedure if you want to encrypt the password in the JMS adapter configuration file.