11 Integrating the Java Message Service

This chapter describes how to use JMS adapters to connect the Java Message Service with an Oracle Event Processing event processing network to receive and send JMS messages.

This chapter includes the following sections:

11.1 Overview of JMS Adapter Configuration

The Oracle Event Processing JMS adapters support any Java EE compliant JMS service provider that provides a Java client. For more information, see Section 11.1.1, "JMS Service Providers".

Oracle Event Processing provides the following Java Message Service (JMS) adapters that you can use in your event applications to send and receive messages to and from a JMS destination, respectively, without writing any Java code:

For general information about JMS, see Java Message Service on the Sun Developer Network at http://java.sun.com/products/jms/.

11.1.1 JMS Service Providers

The Oracle Event Processing JMS adapters support any Java EE compliant JMS service provider that provides a Java client.

This chapter describes how to configure the Oracle Event Processing JMS inbound and outbound adapters for use with the following JMS service providers:

If your JMS service provider is not in this list, you can still configure Oracle Event Processing JMS adapters for use with your JMS service provider. Review the procedure in Section 11.2.4, "How to Configure a JMS Adapter for Tibco EMS JMS Manually" as a configuration model, consult your JMS service provider documentation, and adapt this procedure to suit your JMS service provider.

For more information, see Section 11.2, "Configuring a JMS Adapter for a JMS Service Provider".

11.1.2 Inbound JMS Adapter

The inbound JMS adapter receives messages from a JMS destination and converts them into events.

You specify an inbound JMS adapter in the EPN assembly file as follows:

...
    <wlevs:adapter id="myJmsInbound" provider="jms-inbound">
        ...
    </wlevs:adapter>
...

You configure an inbound JMS adapter in its component configuration file as follows:

...
    <jms-adapter>
        <name>myJmsInbound</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>
...

This section describes:

For more information, see:

11.1.2.1 Conversion Between JMS Messages and Event Types

By default, the inbound JMS adapter automatically converts JMS messages into events by matching property names with a specified event type if the following is true:

  • You must specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

    The JMS adapter converts incoming JMS messages into the Oracle Event Processing event type this element specifies.

  • JMS messages must be of type MapMessage.

    For each incoming message, an event of the specified event type is created. For each map element in the incoming message, the adapter looks for a property on the event type and if found, sets the corresponding value.

Optionally, you may customize JMS message to event type conversion by writing your own Java class to specify exactly how you want the incoming JMS messages to be converted into one or more event types. In this case, you do not specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

For more information, see Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

11.1.2.2 Single and Multi-threaded Inbound JMS Adapters

By default, an inbound JMS adapter is single-threaded. That is, the inbound JMS adapter uses a single thread to read messages from the JMS destination.

When the inbound JMS adapter is single-threaded, event order is guaranteed.

To improve scalability, you can configure an inbound JMS adapter to use multiple threads to read messages from the JMS destination. The simplest way to do this is to configure the adapter with a work manager. You can specify a dedicated work manager used only by the adapter or you can share a work manager amongst several components such as other adapters and Jetty.

When the inbound JMS adapter is multi-threaded, event order is not guaranteed.

For more information, see:

11.1.2.3 Configuring a JMS Adapter for Durable Subscriptions

You can configure an inbound JMS adapter to be a client in a durable subscription to a JMS topic. A durable subscription ensures that the adapter receives published messages even if the adapter becomes inactive. When the inbound adapter connects to the JMS server it will register the durable subscription, and subsequent messages sent to the topic will be retained during periods when the subscriber is disconnected (unless they expire) and delivered when it reconnects.

A durable subscription assumes that the publisher that is publishing JMS messages to the topic is using the persistent delivery mode. Note that publisher might be the Oracle Event Processing outbound JMS adapter (in other words, its delivery-mode value must be persistent, the default value).

To create a durable subscription in the adapter you do the following:

  • Ensure that the JMS message publisher is delivering messages in persistent mode.

  • Specify a client ID for the connection factory. On Oracle WebLogic Server, the client ID can be set on the connection factory administratively using the console. Note that this implies that you should have a dedicated connection factory configured for each adapter instance that is using durable subscribers.

  • Set three jms-adapter properties:

    • destination-type must be set to TOPIC.

    • durable-subscription must be set to true.

    • durable-subscription-name is set to a unique identifier for the subscription.

For more information about these properties, see Section 11.6.1, "JMS Inbound Adapter Component Configuration".

11.1.3 Outbound JMS Adapter

The outbound JMS adapter sends events to a JMS destination, automatically converting the event into a JMS map message by matching property names with the event type.

Typically, you also customize this conversion by writing your own Java class to specify exactly how you want the event types to be converted into outgoing JMS messages.

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

  • You must specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

    The JMS adapter converts incoming JMS messages into the Oracle Event Processing event type this element specifies.

  • By default, the outbound JMS adapter default converter creates JMS messages of type MapMessage. For each property of the event, a corresponding element is created in the output MapMessage.

You specify an outbound JMS adapter in the EPN assembly file as follows:

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

You configure an outbound JMS adapter in its component configuration file as follows:

...
    <jms-adapter>
        <name>myJmsOutbound</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>
...

For more information, see:

11.2 Configuring a JMS Adapter for a JMS Service Provider

This section describes how to configure the Oracle Event Processing JMS inbound and outbound adapters:

This section provides examples specific to the following JMS service providers:

If your JMS service provider is not in this list, and your JMS service provider offers a Java client, then you can still configure Oracle Event Processing JMS adapters for use with your JMS service provider. Review the procedure in Section 11.2.4, "How to Configure a JMS Adapter for Tibco EMS JMS Manually" as a configuration model, consult your JMS service provider documentation, and adapt this procedure to suit your JMS service provider.

For more information, see Section 11.1.1, "JMS Service Providers".

11.2.1 How to Configure a JMS Adapter Using the Oracle Event Processing IDE for Eclipse

The simplest way to create and configure a JMS adapter is using the Oracle Event Processing IDE for Eclipse adapter wizard.

For more information, see Section 7.4.1.2, "How to Create an Adapter Node".

After using the adapter wizard to create and specify the basic JMS adapter configuration, review Section 11.2.2, "How to Configure a JMS Adapter Manually" to complete the configuration.

11.2.2 How to Configure a JMS Adapter Manually

This section describes how to create and configure a JMS adapter manually. It describes the detailed steps that you may require depending on your JMS adapter application and service provider.

The simplest way to create and configure a JMS adapter is using the Oracle Event Processing IDE for Eclipse adapter wizard as Section 11.2.1, "How to Configure a JMS Adapter Using the Oracle Event Processing IDE for Eclipse" describes. After using the adapter wizard to create and specify the basic JMS adapter configuration, review this procedure to complete the configuration.

To configure a JMS adapter manually:

  1. In the EPN assembly file of the application, add a wlevs:adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-1 shows the wlevs:adapter element for a JMS inbound adapter.

    Example 11-1 wlevs:adapter Element for Inbound Adapter

    <wlevs:adapter id="inboundJmsAdapter1" provider="jms-inbound">
...
</wlevs:adapter>

    See:

  2. In the component configuration file of the application, add a jms-adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-2 shows the jms-adapter element for the JMS inbound adapter in Example 11-1.

    Example 11-2 jms-adapter Element for Inbound Adapter

    <jms-adapter>
    <name>inboundJmsAdapter1</name>
...
</jms-adapter>

    For each jms-adapter element, the name child element must be set to the corresponding wlevs:adapter element id child element.

    See:

  3. Decide how you want to convert between JMS messages and Oracle Event Processing event types:

    1. If you want the JMS adapters to perform automatic conversion, specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

      See:

    2. If you want the JMS adapters to perform custom conversion, create a custom converter Java class and register it in the EPN assembly file.

      See Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

  4. Configure the jms-adapter elements for your JMS provider as Example 11-3 shows:

    Example 11-3 jms-adapter Element With Tibco EMS JMS Configuration

    <jms-adapter>
    <name>inboundJmsAdapter1</name>
    ...
    <jndi-provider-url> ... </jndi-provider-url>
    <jndi-factory> ... </jndi-factory>
    <connection-jndi-name> ... </connection-jndi-name>
    <destination-jndi-name> ... </destination-jndi-name>
    ...
</jms-adapter>

    For all options that the Oracle Event Processing JMS adapters support, see:

    For specific JMS provider examples, see:

    For more information, see your JMS service provider documentation.

  5. If you specify JMS provider client passwords in the component configuration file, consider encrypting them.

    See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File".

  6. Create a JMS client application library that contains the following:

    • The JMS client JAR files your JMS service provider documentation specifies.

    • If you are using Java Object messages, the Java classes used for messaging need to be packaged in a library bundle.

      You may include these Java classes in this JMS client JAR application library.

    Note:

    This JMS client JAR application library must:

    • Export all provider-specific packages.

    • Export the Java classes used for messaging, if applicable.

    • Import javax.jms and javax.naming.

    The application bundle does not need to export the provider-specific packages.

    The application bundle must import Java classes used for messaging, if applicable.

    For more information, see Section 23.1.3.3, "Creating Application Libraries".

    For a specific JMS provider example, see Section 11.2.4, "How to Configure a JMS Adapter for Tibco EMS JMS Manually".

  7. Copy the JMS client JAR application library to the appropriate Oracle Event Processing server application library directory:

    1. If your bundle is a driver, you must put it in the library extensions directory.

      See Section 23.1.3.2, "Library Extensions Directory".

    2. If your bundle is not a driver, you may put it in the library directory.

      See Section 23.1.3.1, "Library Directory"

    For more information, see Section 23.3.4, "How to Update an Application Library Using Oracle Event Processing IDE for Eclipse".

  8. If you created a custom converter class in step 3, update the MANIFEST.MF file of your application to add the following packages to the Import-Package header:

    Import-Package: javax.jms,javax.naming, ...
    ...

    See Section 5.7.5, "How to Import a Package".

11.2.3 How to Configure a JMS Adapter for Oracle WebLogic Server JMS Manually

Oracle Event Processing includes a WebLogic JMS client.

When connecting to Oracle WebLogic server, Oracle Event Processing 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 Event Processing server.

For more information, see Section 11.2, "Configuring a JMS Adapter for a JMS Service Provider".

You can manually configure the built-in JMS inbound and outbound adapter to use the Oracle WebLogic Server JMS provider.

The simplest way to create and configure a JMS adapter is using the Oracle Event Processing IDE for Eclipse adapter wizard as Section 11.2.1, "How to Configure a JMS Adapter Using the Oracle Event Processing IDE for Eclipse" describes. After using the adapter wizard to create and specify the basic JMS adapter configuration, review this procedure to complete the configuration.

To configure JMS adapters for Oracle WebLogic Server JMS manually:

  1. Update the EPN assembly file of the application by adding a wlevs:adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-4 shows the wlevs:adapter element for a JMS inbound adapter.

    Example 11-4 wlevs:adapter Element for Inbound Adapter

    <wlevs:adapter id="inboundJmsAdapter1" provider="jms-inbound">
...
</wlevs:adapter>

    See:

  2. Update the component configuration file of the application by adding a jms-adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-5 shows the jms-adapter element for the JMS inbound adapter in Example 11-4.

    Example 11-5 jms-adapter Element for Inbound Adapter

    <jms-adapter>
    <name>inboundJmsAdapter1</name>
...
</jms-adapter>

    For each jms-adapter element, the name child element must be set to the corresponding wlevs:adapter element id child element.

    See:

  3. Decide how you want to convert between JMS messages and Oracle Event Processing event types:

    1. If you want the JMS adapters to perform automatic conversion, specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

      See:

    2. If you want the JMS adapters to perform custom conversion, create a custom converter Java class and register it in the EPN assembly file.

      See Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

  4. Configure the jms-adapter elements for your Oracle WebLogic Server JMS provider.

    Example 11-6 shows the jms-adapter elements for a JMS inbound and JMS outbound adapter.

    Example 11-6 jms-adapter Elements for an Oracle WebLogic Server JMS Provider

    ...
    <jms-adapter>
        <name>JmsInbound</name>
        <event-type>SimpleMapEvent</event-type>
        <jndi-provider-url>t3://localhost:7001</jndi-provider-url>
        <destination-jndi-name>QueueIn</destination-jndi-name>
        <user>weblogic</user>
        <password>welcome1</password>
        <work-manager>JettyWorkManager</work-manager>
        <concurrent-consumers>1</concurrent-consumers>
        <session-transacted>false</session-transacted>
        <delivery-mode>nonpersistent</delivery-mode>
    </jms-adapter>

    <jms-adapter> 
        <name>JmsOutbound</name>
        <event-type>SimpleMapEvent</event-type>
        <jndi-provider-url>t3://localhost:7001</jndi-provider-url>
        <destination-jndi-name>QueueIn</destination-jndi-name>
        <user>weblogic</user>
        <password>welcome1</password>
        <message-selector></message-selector>
        <session-transacted>false</session-transacted>
        <delivery-mode>nonpersistent</delivery-mode>
    </jms-adapter>
...

    See:

  5. If you specify JMS provider client passwords in the component configuration file, consider encrypting them.

    See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File".

  6. If you are using Java Object messages, you must create a JMS client application library that contains the Java classes used for messaging need to be packaged in a library bundle.

    For more information, see Section 23.1.3.3, "Creating Application Libraries".

    Note:

    This JMS client JAR application library must:

    • Export the Java classes used for messaging.

    • Import javax.jms and javax.naming.

    The application bundle does not need to export provider-specific packages.

    The application bundle must import Java classes used for messaging, if applicable.

  7. If you are using Java Object messages, copy the Java classes for messaging application library to the appropriate Oracle Event Processing server application library directory:

    1. If your bundle is a driver, you must put it in the library extensions directory.

      See Section 23.1.3.2, "Library Extensions Directory".

    2. If your bundle is not a driver, you may put it in the library directory.

      See Section 23.1.3.1, "Library Directory"

    For more information, see Section 23.3.4, "How to Update an Application Library Using Oracle Event Processing IDE for Eclipse".

  8. If you created a custom converter class in step 3, update the MANIFEST.MF file of your application to add the following packages to the Import-Package header:

    Import-Package: javax.jms,javax.naming, ...
    ...

    See Section 5.7.5, "How to Import a Package".

11.2.4 How to Configure a JMS Adapter for Tibco EMS JMS Manually

Oracle Event Processing supports TIBCO Enterprise Message Service (EMS) version 4.2.0 or higher.

To use the Tibco EMS JMS provider, you must add the following Tibco EMS client JAR files to the Oracle Event Processing server library directory:

  • tibjms.jar

For more information, see:

You can manually configure the built-in JMS inbound and outbound adapter to use the Tibco EMS JMS provider.

The simplest way to create and configure a JMS adapter is using the Oracle Event Processing IDE for Eclipse adapter wizard as Section 11.2.1, "How to Configure a JMS Adapter Using the Oracle Event Processing IDE for Eclipse" describes. After using the adapter wizard to create and specify the basic JMS adapter configuration, review this procedure to complete the configuration.

To configure a JMS adapter for Tibco EMS JMS manually:

  1. In the EPN assembly file of the application, add a wlevs:adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-7 shows the wlevs:adapter element for a JMS inbound adapter.

    Example 11-7 wlevs:adapter Element for Inbound Adapter

    <wlevs:adapter id="inboundJmsAdapter1" provider="jms-inbound">
...
</wlevs:adapter>

    See:

  2. In the component configuration file of the application, add a jms-adapter element for each inbound and outbound JMS adapter you want to use in your application.

    Example 11-8 shows the jms-adapter element for the JMS inbound adapter in Example 11-7.

    Example 11-8 jms-adapter Element for Inbound Adapter

    <jms-adapter>
    <name>inboundJmsAdapter1</name>
...
</jms-adapter>

    For each jms-adapter element, the name child element must be set to the corresponding wlevs:adapter element id child element.

    See:

  3. Decide how you want to convert between JMS messages and Oracle Event Processing event types:

    1. If you want the JMS adapters to perform automatic conversion, specify an event type using the jms-adapter element event-type child element in the JMS adapter component configuration file.

      See:

    2. If you want the JMS adapters to perform custom conversion, create a custom converter Java class and register it in the EPN assembly file.

      See Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

  4. Configure the jms-adapter elements for your Tibco EMS JMS provider as Example 11-9 shows:

    Example 11-9 jms-adapter Element With Tibco EMS JMS Configuration

    <jms-adapter>
    <name>inboundJmsAdapter1</name>
    ...
    <jndi-provider-url>tcp://TIBCOHOST:PORT</jndi-provider-url>
    <jndi-factory>com.tibco.tibjms.naming.TibjmsInitialContextFactory</jndi-factory>
    <connection-jndi-name>CONNECTION_NAME</connection-jndi-name>
    <destination-jndi-name>DESTINATION_NAME</destination-jndi-name>
    ...
</jms-adapter>

    Where:

    • TIBCOHOST: the hostname of the Tibco EMS JMS provider host.

    • PORT: the Tibco EMS JMS provider port.

    • DESTINATION_NAME: the destination JNDI name of the Tibco EMS JMS destination, such as TibcoRequestQueue1.

    • CONNECTION_NAME: the connection JNDI name of the Tibco EMS JMS connection factory you defined in the Tibco EMS JMS server, such as TibcoQueueConnectionFactory.

    See:

  5. If you specify JMS provider client passwords in the component configuration file, consider encrypting them.

    See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File".

  6. Create a JMS client application library that contains the following:

    • tibjms.jar

    • If you are using Java Object messages, the Java classes used for messaging need to be packaged in a library bundle.

      You may include these Java classes in this JMS client application library.

    Note:

    The JMS client application library must:

    • Export all provider-specific packages.

    • Export the Java classes used for messaging, if applicable.

    • Import javax.jms and javax.naming.

    The application bundle does not need to export the provider-specific packages.

    The application bundle must import Java classes used for messaging, if applicable.

    For more information, see Section 23.1.3.3, "Creating Application Libraries".

    For a specific JMS provider example, see Section 11.2.4, "How to Configure a JMS Adapter for Tibco EMS JMS Manually".

  7. Copy the application library to the appropriate Oracle Event Processing server application library directory:

    1. If your bundle is a driver, you must put it in the library extensions directory.

      See Section 23.1.3.2, "Library Extensions Directory".

    2. If your bundle is not a driver, you may put it in the library directory.

      See Section 23.1.3.1, "Library Directory"

    For more information, see Section 23.3.4, "How to Update an Application Library Using Oracle Event Processing IDE for Eclipse".

  8. If you created a custom converter class in step 3, update the MANIFEST.MF file of your application to add the following packages to the Import-Package header:

    Import-Package: javax.jms,javax.naming, ...
    ...

    See Section 5.7.5, "How to Import a Package".

11.3 Creating a Custom Converter Between JMS Messages and Event Types

If you want to customize the conversion between JMS messages and event types you must create your own converter bean.

This section describes:

11.3.1 How to Create a Custom Converter for the Inbound JMS Adapter

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.

See the Oracle Fusion Middleware Java API Reference for Oracle Event Processing for a full description of these APIs.

To create a custom converter for the inbound JMS adapter:

  1. Using the Oracle Event Processing IDE for Eclipse (or your preferred IDE), add a Java class to your application project.

  2. Implement the com.bea.wlevs.adapters.jms.api.InboundMessageConverter interface.

    Example 11-10 shows a possible implementation.

    Example 11-10 Custom Converter for an Inbound JMS Adapter

    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;
    }
}

  3. Specify the converter in your application EPN assembly file as Example 11-11 shows:

    • Register the converter class using a bean element.

    • Associate the converter class with the JMS adapter by adding a wlevs:instance-property with name set to converterBean and ref set to the id of bean.

    Example 11-11 Specifying a Converter Class for an Inbound JMS Adapter in the EPN Assembly File

    ...
    <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>
...

  4. Package the Java class with your application.

    For more information, see Chapter 23, "Assembling and Deploying Oracle Event Processing Applications".

11.3.2 How to Create a Custom Converter for the Outbound JMS Adapter

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 Oracle Fusion Middleware Java API Reference for Oracle Event Processing for a full description of these APIs.

To create a custom converter for the outbound JMS adapter:

  1. Using the Oracle Event Processing IDE for Eclipse (or your preferred IDE), add a Java class to your application project.

  2. Implement the com.bea.wlevs.adapters.jms.api.OutboundMessageConverter interface.

    Example 11-10 shows a possible implementation.

    Example 11-12 Custom Converter for an Outbound JMS Adapter

    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;
    }
}

  3. Specify the converter in your application EPN assembly file as Example 11-11 shows:

    • Register the convert class using a bean element.

    • Associate the converter class with the JMS adapter by adding a wlevs:instance-property with name set to converterBean and ref set to the id of bean.

    Example 11-13 Specifying a Converter Class for an Outbound JMS Adapter in the EPN Assembly File

    ...
    <bean id="myConverter" class="com.customer.MessageConverter"/>
    <wlevs:adapter id="jmsOutbound" provider="jms-outbound">
        <wlevs:instance-property name="converterBean" ref="myConverter"/>
    </wlevs:adapter>
...

  4. Package the Java class with your application.

    For more information, see Chapter 23, "Assembling and Deploying Oracle Event Processing Applications".

11.4 Encrypting Passwords in the JMS Adapter Component Configuration File

You can encrypt the password in the JMS adapter configuration file.

Note:

The procedure assumes that you are currently using the password element in the configuration file, along with a cleartext password value, but want to start using the encrypted-password element to encrypt the password.

11.4.1 How to Encrypt Passwords in the JMS Adapter Component Configuration File

You can encrypt the password in the JMS adapter configuration file.

To encrypt passwords in the JMS adapter component configuration file:

  1. Open a command window and set your environment as described in Section 3.2, "Setting Your Development Environment."

  2. Change to the directory that contains the configuration file for your JMS adapter.

  3. Execute the following encryptMSAConfig command to encrypt the value of the <password> element in the configuration file:

    prompt> ORACLE_CEP_HOME/ocep_11.1/bin/encryptMSAConfig . config_file aesinternal.dat_file

    where ORACLE_CEP_HOME refers to the main BEA directory into which you installed Oracle Event Processing, such as d:\oracle_cep. The second argument refers to the directory that contains the JMS adapter configuration file; because this procedure directs you to actually change to the directory, the example shows ".". The config_file parameter refers to the name of your JMS adapter configuration file. Finally, the aesinternal.dat_file parameter refers to the location of the .aesinternal.dat file associated with your domain; by default this file is located in the DOMAIN_DIR/servername directory, where DOMAIN_DIR refers to the domain directory such as /oracle_cep/user_projects/domains/mydomain and servername refers to the server instance.

    The encryptMSAConfig command comes in two flavors: encryptMSAConfig.cmd (Windows) and encryptMSAConfig.sh (UNIX).

    After you run the command, the value of the <password> element will be encrypted, as shown in bold in the following example:

    <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>{Salted-3DES}B7L6nehu7dgPtJJTnTJWRA==</password>
  <work-manager>JettyWorkManager</work-manager>
  <concurrent-consumers>1</concurrent-consumers>
  <session-transacted>false</session-transacted>
</jms-adapter>

  4. Using your favorite XML editor, edit the JMS adapter configuration file. Change the <password> element (whose value is now encrypted) to <encrypted-password>, as shown in bold in the following example:

    <jms-adapter>
  <name>jmsInbound</name>
  <jndi-provider-url>t3://localhost:7001</jndi-provider-url>
  <destination-jndi-name>Queue1</destination-jndi-name>
  <user>weblogic</user>
  <encrypted-password>{Salted-3DES}B7L6nehu7dgPtJJTnTJWRA==</encrypted-password>
  <work-manager>JettyWorkManager</work-manager>
  <concurrent-consumers>1</concurrent-consumers>
  <session-transacted>false</session-transacted>
</jms-adapter>

11.5 Configuring the JMS Adapter EPN Assembly File

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

As with any other stage in the EPN, add listeners to the wlevs:adapter element 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 Event Processing application define where in the network the JMS adapters fit in.

For both JMS inbound and outbound adapters, if you have created a custom converter bean to customize the conversion between the JMS messages and event types, first use the standard bean Spring element to declare it in the EPN assembly file. Then pass a reference of the bean to the JMS adapter by specifying its id using the wlevs:instance-property element, with the name attribute set to converterBean, as shown:

<bean id="myConverter"
      class="com.customer.MessageConverter"/>

<wlevs:adapter id="jmsOutbound" provider="jms-outbound">  
    <wlevs:instance-property name="converterBean" ref="myConverter"/>
</wlevs:adapter>

In this case, be sure you do not specify an event type in the component configuration file because it is assumed that the custom converter bean takes care of specifying the event type.

This section describes:

For more information, see:

11.5.1 JMS Inbound Adapter EPN Assembly File Configuration

If you are specifying an inbound JMS adapter, set the provider attribute to jms-inbound, as shown:

<wlevs:adapter id="jmsInbound" provider="jms-inbound"/>

The value of the id attribute, in this case jmsInbound, must match the name specified for this JMS adapter in its configuration file. The configuration file configures the JMS destination from which this inbound JMS adapter gets its messages.

Because no converter bean is specified, Oracle Event Processing automatically converts the inbound message to the event type specified in the component configuration file by mapping property names.

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 destination 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-v11_1_1_6.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>

11.5.2 JMS Outbound Adapter EPN Assembly File Configuration

If you are specifying an outbound JMS adapter, set the provider attribute to jms-outbound, as shown:

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

The value of the id attribute, in this case jmsOutbound, must match the name specified for this JMS adapter in its configuration file. The configuration file configures the JMS destination to which this outbound JMS adapter sends messages.

Because no converter bean is specified, Oracle Event Processing automatically converts the incoming event types to outgoing JMS messages by mapping the property names.

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 channel. Oracle Event Processing automatically converts these events to JMS messages and sends the messages to the JMS destination 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-v11_1_1_6.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"/>
     <!-- Channel for events flowing from myProcessor to outbound JMS adapter -->
    <wlevs:channel id="streamOne">
       <wlevs:listener ref="jmsOutbound"/>
       <wlevs:source ref="myProcessor"/>
    </wlevs:channel>
</beans>

11.6 Configuring the JMS Adapter Component Configuration File

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.

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 element in the EPN assembly file that declares this adapter.

This section describes:

For more information, see:

11.6.1 JMS Inbound Adapter Component Configuration

Table 11-1 lists the jms-adapter element child elements applicable to the JMS inbound adapter.

Table 11-1 jms-adapter Inbound Child Elements

Child Element Description

bindings

Bindings are used to configure horizontal scale-out and are an advanced feature. Using the com.oracle.cep.cluster.hagroups.ActiveActiveGroupBean, you can partition an incoming JMS stream in Oracle Event Processing applications by utilizing the notification groups that the ActiveActiveGroupBean creates. Use this element to associate a notification group with a particular message-selector value.

For more information, see Section 25.1.2.2, "ActiveActiveGroupBean"

concurrent-consumers

Number of consumers to create. Default value is 1.

If you set this value to a number greater than 1:

connection-jndi-name

Optional. The JNDI name of the JMS connection factory. Default value is weblogic.jms.ConnectionFactory, for Oracle Event Processing server JMS.

connection-password

connection-encrypted-password

Optional. Either the password, or encrypted password, for connection-user.

Note: Specify either connection-password or connection-encrypted-password, but not both.

See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File" for details on encrypting the password.

connection-user

Optional. When Oracle Event Processing calls the createConnection method on the javax.jms.ConnectionFactory to create a connection to the JMS destination (JMS queue or topic), it uses the connection-user and connection-password (or connection-encrypted-password) settings, if configured. Otherwise, Oracle Event Processing uses the user and password (or encrypted-password) settings.

You can use the connection-user and connection-password (or connection-encrypted-password) settings in applications where one security provider is used for JNDI access and a separate security provider is used for JMS access.

destination-jndi-name

Required. The JNDI name of the JMS destination.

Note: Specify either destination-jndi-name or destination-name, but not both.

destination-name

Required. The actual name of the JMS destination.

Note: Specify either destination-jndi-name or destination-name, but not both.

destination-type

Define the JMS destination type for a JMS adapter. Valid values are TOPIC or QUEUE. This property must be set to TOPIC whenever the durable-subscription property is set to true.

Note: To support a durable subscription, set this to TOPIC and use it with durable-subscription set to true; give the subscription a unique identifier with durable-subscription-name.

durable-subscription

Specifies whether the JMS topic subscription of a JMS adapter is durable, meaning that it can persist even if subscribers become inactive. Valid values are true or false. This property is only valid if destination-type is set to TOPIC.

Note: To support a durable subscription, use this with destination-type set to TOPIC and durable-subscription-name set to a unique identifier.

durable-subscription-name

The name to uniquely identify a durable subscription of a JMS adapter. A durable subscription can persist even if subscribers become inactive.

Note: To support a durable subscription, use this with durable-subscription set to true and destination-type set to TOPIC.

event-type

Event type whose property names match inbound JMS Map Message property names. Specify this property only if you want Oracle Event Processing to automatically perform the conversion between JMS messages and events. If you have created your own custom converter bean, then do not specify this property

For more information, see Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

jndi-factory

Optional. The JNDI factory name. Default value is weblogic.jndi.WLInitialContextFactory, for Oracle Event Processing server JMS.

jndi-provider-url

Required. The URL of the JNDI provider.

message-selector

JMS message selector to use to filter messages. Only messages that match the selector will produce events.

Default: there is no selector; all messages will produce events.

password

encrypted-password

Required. Either the password, or encrypted password, for user.

Note: Specify either password or encrypted-password, but not both.

See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File" for details on encrypting the password.

session-ack-mode-name

Determines how messages are acknowledged. Once a message is successfully acknowledged it will never be resent following a failure.

Valid values from javax.jms.Session are:

  • AUTO_ACKNOWLEDGE: With this acknowledgment mode, the session automatically acknowledges a client's receipt of a message when the message has been successfully received. Applications that require message redelivery in response to failures during downstream message processing should use the session-transacted property to achieve this.

  • CLIENT_ACKNOWLEDG: With this acknowledgment mode, the client acknowledges a consumed message by calling the message's acknowledge method.

  • DUPS_OK_ACKNOWLEDGE: This acknowledgment mode instructs the session to lazily acknowledge the delivery of messages.

Default: AUTO_ACKNOWLEDGE.

session-transacted

Boolean value that specifies whether or not the session is transactional.

If the session is transacted then do not specify session-ack-mode-name.

Default: False.

user

Required. When Oracle Event Processing acquires the JNDI InitialContext, it uses the user and password (or encrypted-password) settings.

work-manager

Name of a work manager, configured in the Oracle Event Processing server config.xml file. This name corresponds to the value of the name child element of the work-manager element in config.xml.

If concurrent-consumers is greater than 1 and you want all the consumers to be run concurrently, then consider the configuration of the work-manager you associate with this JMS inbound adapter:

  • If the work-manager is shared with other components (such as other adapters and Jetty) then set the work-manager attribute max-threads-constraint greater than or equal to the concurrent-consumers setting.

  • If the work-manager is not shared (that is, it is dedicated to this inbound JMS adapter only) then set the work-manager attribute max-threads-constraint equal to the concurrent-consumers setting.

The default value is the work manager configured for the application itself.

For more information, see Section F.45, "work-manager".

The following configuration file shows a complete example of configuring an inbound 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>MyWorkManager</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>

11.6.2 JMS Outbound Adapter Component Configuration

Table 11-2 lists the jms-adapter element child elements applicable to the JMS outbound adapter.

Table 11-2 jms-adapter Outbound Component Configuration Child Elements

Child Element Description

connection-jndi-name

Optional. The JNDI name of the JMS connection factory. Default value is weblogic.jms.ConnectionFactory, for Oracle Event Processing server JMS.

connection-password

connection-encrypted-password

Optional. Either the password, or encrypted password, for connection-user.

Note: Specify either connection-password or connection-encrypted-password, but not both.

See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File" for details on encrypting the password.

connection-user

Optional. When Oracle Event Processing calls the createConnection method on the javax.jms.ConnectionFactory to create a connection to the JMS destination (JMS queue or topic), it uses the connection-user and connection-password (or connection-encrypted-password) settings, if configured. Otherwise, Oracle Event Processing uses the user and password (or encrypted-password) settings.

You can use the connection-user and connection-password (or connection-encrypted-password) settings in applications where one security provider is used for JNDI access and a separate security provider is used for JMS access.

delivery-mode

Specifies the delivery mode: persistent (default value) or nonpersistent.

destination-jndi-name

Required. The JNDI name of the JMS destination.

Note: Specify either destination-jndi-name or destination-name, but not both.

destination-name

Required. The actual name of the JMS destination.

Note: Specify either destination-jndi-name or destination-name, but not both.

event-type

Event type whose property names match inbound JMS Map Message property names. Specify this property only if you want Oracle Event Processing to automatically perform the conversion between JMS messages and events. If you have created your own custom converter bean, then do not specify this property

For more information, see Section 11.3, "Creating a Custom Converter Between JMS Messages and Event Types".

jndi-factory

Optional. The JNDI factory name. Default value is weblogic.jndi.WLInitialContextFactory, for Oracle Event Processing server JMS.

jndi-provider-url

Required. The URL of the JNDI provider.

password

encrypted-password

Required. Either the password, or encrypted password, for user.

Note: Specify either password or encrypted-password, but not both.

See Section 11.4, "Encrypting Passwords in the JMS Adapter Component Configuration File" for details on encrypting the password.

session-transacted

Boolean value that specifies whether or not the session is transactional.

If the session is transacted then do not specify session-ack-mode-name.

Default: False.

user

Required. When Oracle Event Processing acquires the JNDI InitialContext, it uses the user and password (or encrypted-password) settings.

The following configuration file shows a complete example of configuring an 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>