5 Oracle Application Server Adapter for Java Message Service

Concepts

Messaging is any mechanism that allows communication between programs. Messages are structured data that one application sends to another. Message-oriented middleware (MOM) is an infrastructure that supports scalable enterprise messaging. MOM ensures fast, reliable asynchronous communication, guaranteed message delivery, receipt notification, and transaction control. JMS is a Java interface developed by Sun Microsystems for producing, sending, and receiving messages of an enterprise messaging system. JMS is an API that JMS vendors implement. Oracle provides two implementations of JMS: OC4J JMS and Oracle JMS based on Oracle advanced queues. A JMS producer creates JMS messages and a JMS consumer consumes JMS messages.

JMS supports two messaging paradigms: point-to-point (queues) and publish/subscribe (topics).

Point-to-Point

In point-to-point messaging, the messages are stored in a queue until they are consumed. One or more producers write to the queue and one or more consumers extract messages from the queue. The JMS consumer sends an acknowledgment after consumption of a message; this results in purging of the message from the queue.

Publish/Subscribe

In publish/subscribe messaging, producers publish messages to a topic and the consumer subscribes to a particular topic. Many publishers can publish to the same topic, and many consumers can subscribe to the same topic. All messages published to the topic by the producers are received by all consumers subscribed to the topic. By default, subscribers receive messages only when they are active. However, JMS API supports durable subscriptions that ensure that consumers receive messages that were published even when they are not up and running. The durable subscription involves registering the consumer with a unique ID for retrieving messages that were sent when the consumer was inactive. These messages are persisted by the JMS provider and are either sent to the consumer when it becomes active again or purged from storage if the message expires. The JMS producer can be set either to persistent or nonpersistent mode. The messages are not persisted in the latter case and can be used only for nondurable subscriptions.The JMS API supports both synchronous or asynchronous communication for message consumption. In the synchronous case, the consumer explicitly calls the receive() method on the topic or queue. In the asynchronous case, the JMS client registers a message listener for the topic or queue and the message is delivered by calling the listener's onMessage() method.

Destination, Connection, Connection Factory, and Session

The destination property contains the addressing information for a JMS queue or topic.Connections represent a physical connection to the JMS provider. The connection factory is used to create JMS connections. A session is used to create a destination, JMS producer, and JMS consumer objects for a queue or topic.

Structure of a JMS Message

The JMS message has a mandatory standard header element, optional properties element, and optional standard payload element. The payload can be a text message, byte message, map message, stream message, or object message. The properties element is JMS provider-specific and varies from one JMS provider to another.

JMS Header Properties

Table 5-1 describes the JMS header properties.

Using the Adapter Configuration Wizard to Configure a JMS Adapter

This section describes how to create an adapter service for a partner link.

1. Click Define Adapter Service (third icon) in the Create Partner Link window, as shown in Figure 5-1:

   Figure 5-1 Create Partner Link Window

   
   Description of "Figure 5-1 Create Partner Link Window"
   
   

   The Adapter Configuration Wizard - Welcome window appears.

2. If you do not want to see this window each time you use the Adapter Configuration Wizard, select the Skip this Page Next Time check box. Then click Next.

   Figure 5-2 Welcome Window for the Adapter Configuration Wizard

   
   Description of "Figure 5-2 Welcome Window for the Adapter Configuration Wizard"
   
   

3. Select JMS Adapter from the list of available adapter types and click Next.

   Figure 5-3 Adapter Type Window

   
   Description of "Figure 5-3 Adapter Type Window"
   
   

   The Service Name window appears.

4. Enter a name for the service. You may also add an optional description. Click Next.

   Figure 5-4 Service Name Window

   
   Description of "Figure 5-4 Service Name Window"
   
   

   The JMS Connection window appears.

5. Enter the JMS connection JNDI name and click Next.

   Figure 5-5 JMS Connection Window

   
   Description of "Figure 5-5 JMS Connection Window"
   
   
   
   

   Note: The JNDI name is key in determining the JMS type. The name must match an endpoint in the oc4j-ra.xml file, which defines the configuration properties.

   
   

   See "oc4j-ra.xml file" for more information.

   The Operation window appears.

6. Select Consume Message or Produce Message. The operation name is filled in automatically. Click Next.

   Figure 5-6 Operation Window

   
   Description of "Figure 5-6 Operation Window"
   
   

   In this case, Consume Message was selected. This enables the adapter to consume (receive) inbound messages from a JMS destination. The Consume Operation Parameters window appears.

7. Enter values for the following fields:

   • Destination Name

     The JNDI name of the JMS queue or topic from which to receive the message. The name to enter is based on the type of JMS provider you are using. See the following sections for details:

     • "Configuring for OJMS"

     • "Configuring for OC4J JMS"

     • "Configuring for TIBCO JMS"

     • "Configuring for IBM Websphere JMS"

   • Message Body Type

     Select either TextMessage or BytesMessage.

     The StreamMessage and MapMessage message types are not supported in this release.

   • Durable Subscriber ID

     This field is optional. If you are setting up a durable subscriber, then the durable subscriber ID is required. Normally a subscriber loses messages if it becomes disconnected, but a durable subscriber downloads stored messages when it reconnects.

   • Message Selector

     This field is also optional. It filters messages based on header and property information. The message selector rule is a Boolean expression. If the expression is true, then the message is consumed. If the expression is false, then the message is rejected.

     For example, you can enter logic such as:

     • JMSPriority > 3. Based on this, messages with a priority greater than 3 are consumed; all other messages are rejected.

     • JMSType = 'car' AND color = 'blue' AND weight > 2500

     • Country in ('UK', 'US', 'France')

   • Use MessageListener

     This field is set to true by default, which means that the server does an asynchronous callback to the adapter. If this is set to false, the adapter performs a synchronous blocking receive.

   
   

   Note: This example shows a consume message operation. For a produce message operation, this window is different. See "Produce Message Procedure" to see how this part of the procedure differs.

   
   

   After you enter the appropriate parameters, click Next.

   Figure 5-7 Consume Operation Parameters Window

   
   Description of "Figure 5-7 Consume Operation Parameters Window"
   
   

8. The Messages window appears. These settings define the correct schema for the message payload.

   You can perform one of the following:

   • Check Native format translation is not required (Schema is Opaque), which disables the rest of the fields.

   • Click Define Schema for Native Format to start the Native Format Builder Wizard, which guides you through the process of defining the native format.

   • Enter the path for the schema file URL (or browse for the path).

   The following steps demonstrate the last option: browsing for the schema file URL. Click the Browse button.

   Figure 5-8 Messages Window

   
   Description of "Figure 5-8 Messages Window"
   
   

   The Type Chooser window appears, with the Type Explorer navigation tree.

9. Browse the tree and select the appropriate schema type. Then click OK.

   Figure 5-9 Selecting a Schema from the Type Chooser Window

   
   Description of "Figure 5-9 Selecting a Schema from the Type Chooser Window"
   
   

   The Messages window appears again, this time with the Schema File URL field and the Schema Element field filled in.

   Figure 5-10 Completed Messages Window

   
   Description of "Figure 5-10 Completed Messages Window"
   
   

10. Click Next.

    The Finish window appears. This box shows the path and name of the adapter file that the wizard creates.

11. Click Finish.

    The Create Partner Link window appears with the fields populated.

    Figure 5-11 Completed Create Partner Link Window

    
    Description of "Figure 5-11 Completed Create Partner Link Window"
    
    

12. Click OK.

Generated WSDL File

The following WSDL file is generated by the Adapter Configuration Wizard:

<definitions
     name="JMS_Example"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/jms/JMS_Example/"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/jms/JMS_Example/"
     xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
     xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
     xmlns:opaque="http://xmlns.oracle.com/pcbpel/adapter/opaque/"
     xmlns:pc="http://xmlns.oracle.com/pcbpel/"
     xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/jms/"
    >

This code segment defines the name of the adapter, and the locations of various necessary schemas and other definition files.

    <import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/"
 location="jmsAdapterInboundHeader.wsdl"/>

This code segment imports the necessary namespace.

    <types>
    <schema targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/opaque/"
            xmlns="http://www.w3.org/2001/XMLSchema" >
      <element name="opaqueElement" type="base64Binary" />
    </schema>
    </types>
    <message name="Consume_Message_msg">
        <part name="opaque" element="opaque:opaqueElement"/>
    </message>
    <portType name="Consume_Message_ptt">
        <operation name="Consume_Message">
            <input message="tns:Consume_Message_msg"/>
        </operation>
    </portType>

This code segment defines the message type, name, and the port type for the partner link.

    <binding name="Consume_Message_binding" type="tns:Consume_Message_ptt">
    <pc:inbound_binding />
        <operation name="Consume_Message">
      <jca:operation
          ActivationSpec="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec"
          DestinationName="jms/DemoQue"
          UseMessageListener="true"
          PayloadType="TextMessage"
          OpaqueSchema="true" >
      </jca:operation>
      <input>
        <jca:header message="hdr:InboundHeader_msg" part="inboundHeader"/>
      </input>
        </operation>
    </binding>

This code segment defines the necessary bindings for the consume message operation, the target queue, and identifies the message header.

    <service name="JMS_Example2">
        <port name="Consume_Message_pt" binding="tns:Consume_Message_binding">
      <jca:address location="eis/Jms/topics.xml" />
        </port>
    </service>
  <plt:partnerLinkType name="Consume_Message_plt" >
    <plt:role name="Consume_Message_role" >
      <plt:portType name="tns:Consume_Message_ptt" />
    </plt:role>
  </plt:partnerLinkType>
</definitions>

This last part defines the database connection, the connection factory (as defined in the oc4j-ra.xml file), and the name and role of the partnerLinkType and portType.

oc4j-ra.xml file

The oc4j-ra.xml file defines the endpoints for the JMS connection factories. The connection factories include configuration properties for each endpoint. Endpoints are added to accommodate different types of connections, as demonstrated in the following sections. The following example is from the generic oc4j-ra.xml file:

<?xml version="1.0"?>
<!DOCTYPE oc4j-connector-factories PUBLIC "-//Oracle//DTD Oracle Connector
 9.04//EN" "http://xmlns.oracle.com/ias/dtds/oc4j-connector-factories-9_04.dtd">
<oc4j-connector-factories>
     <connector-factory location="eis/MyJmsTopic1" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"
                      value="jms/TopicConnectionFactory"/>
     <config-property name="factoryProperties" value=""/>
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/>
     <config-property name="isTopic" value="true"/>
     <config-property name="isTransacted" value="true"/>
     <config-property name="username" value="admin"/>
     <config-property name="password" value="welcome"/>
</connector-factory>
<connector-factory location="eis/MyJmsTopic2" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"

...
</oc4j-connector-factories>

Produce Message Procedure

A produce message operation has certain differences in the definition procedure, particularly in Step 7 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter". Instead of specifying consume operation parameters, you specify the following produce operation parameters. This enables the adapter to produce (send) outbound messages for a JMS destination. The Produce Operation Parameters window is shown in Figure 5-12.

• Destination Name:

  The JNDI name of the JMS queue or topic to which to deliver the message. The name to enter is based on the type of JMS provider you are using. See the following sections for detail:

  • "Configuring for OJMS"

  • "Configuring for OC4J JMS"

  • "Configuring for TIBCO JMS"

  • "Configuring for IBM Websphere JMS"

• Message Body Type:

  The supported values are TextMessage or BytesMessage. The StreamMessage and MapMessage message types are not supported in this release.

• Delivery Mode:

  The values are Persistent or Nonpersistent. A persistent delivery mode specifies a persistent JMS publisher; that is, a publisher that stores messages for later use by a durable subscriber. A durable subscriber is a consume message with a durable subscriber ID in the corresponding field in step 7 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter". A nondurable subscriber loses any messages that are produced when the adapter is not active. A durable subscriber downloads messages that have been stored in the persistent publisher, and therefore does not have to remain active at all times to receive all the messages.

• Priority:

  Select a priority value, with 9 representing the highest priority and 0 representing the lowest priority. The default is 4.

• TimeToLive:

  The amount of time before the message expires and is no longer available to be consumed.

Figure 5-12 Produce Operation Parameters Window

Description of "Figure 5-12 Produce Operation Parameters Window"

Configuring for OJMS

Configure the OJMS provider within the resource-provider element in the global application.xml file. You can configure the resource provider with a URL property. The following demonstrates a URL configuration:

<resource-provider class="oracle.jms.OjmsContext" name="ojmsdemo">
     <description>OJMS/AQ</description> 
     <property name="url" value="jdbc:oracle:thin:@localhost:1521:my" /> 
     <property name="username" value="jmsuser" /> 
     <property name="password" value="jmsuser" /> 
</resource-provider>

In the oc4j-ra.xml file, add the following code segments:

<connector-factory location="eis/aqjms/Topic" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"  
           value="java:comp/resource/ojmsdemo/TopicConnectionFactories/myTCF" /> 
     <config-property name="factoryProperties" value="" /> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
     <config-property name="isTopic" value="true" /> 
     <config-property name="isTransacted" value="true" /> 
     <config-property name="username" value="jmsuser" /> 
     <config-property name="password" value="jmsuser" /> 
</connector-factory>
<connector-factory location="eis/aqjms/Queue" connector-name="Jms Adapter">
    <config-property name="connectionFactoryLocation" value="
         java:comp/resource/ojmsdemo/QueueConnectionFactories/myQCF" /> 
    <config-property name="factoryProperties" value="" /> 
    <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
    <config-property name="isTopic" value="false" /> 
    <config-property name="isTransacted" value="true" /> 
    <config-property name="username" value="jmsuser" /> 
    <config-property name="password" value="jmsuser" /> 
</connector-factory>

In this case, correct JMS connection JNDI names for Step 5 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter" are eis/aqjms/Topic or eis/aqjms/Queue.

Set the isTransacted value in the oc4j-ra.xml file to true. Setting it to false leads to exception errors.

Access the OJMS Resources

The OJMS syntax for the connection factory is as follows:

java:comp/resource + JMS_provider_name + TopicConnectionFactories + user_defined_name

or

java:comp/resource + JMS_provider_name + QueueConnectionFactories + user_defined_name

The user_defined_name can be anything and does not match any other configuration. The ConnectionFactories details what type of factory is being defined. For this example, the JMS provider name is defined in the resource-provider element as ojmsdemo.For a queue connection factory: Because the JMS provider name is ojmsdemo and you decide to use a name of myQCF, the connection factory name is java:comp/resource/ojmsdemo/QueueConnectionFactories/myQCF. For a topic connection factory: Because the JMS provider name is ojmsdemo and you decide to use a name of myTCF, the connection factory name is java:comp/resource/ojmsdemo/TopicConnectionFactories/myTCF. The user-defined names of myQCF and myTCF are not used for anything else in your logic. Therefore, you can choose any name.

Destination

The OJMS syntax for any destination is as follows:

java:comp/resource + JMS_provider_name + Topics + Destination_name

or

java:comp/resource + JMS_provider_name + Queues + Destination_name

The topic or queue details which type of destination is being defined. The destination name is the actual queue or topic name defined in the database.For this example, the JMS provider name is defined in the resource-provider element as ojmsdemo. In the database, the queue name is aqQueue.For a queue: If the JMS provider name is ojmsdemo and the queue name is aqQueue, the JNDI name for the queue is java:comp/resource/ojmsdemo/Queues/aqQueue.For a topic: If the JMS provider name is ojmsdemo and the topic name is aqTopic, the JNDI name for the topic is java:comp/resource/ojmsdemo/Topics/aqTopic.

OJMS and Remote Databases

To configure the adapter to use a remote database, the entries in the application.xml file must look as follows:

<resource-provider class="oracle.jms.OjmsContext" name="ojmsdemo"> 
<description>OJMS/AQ</description> 
<property name="url" 
value="jdbc:oracle:thin:@remote-host:remote-port:remote-sid" /> 
<property name="username" value="jmsuser" /> 
@ <property name="password" value="jmsuser" /> 
</resource-provider>

Configuring for OC4J JMS

If the OC4J JMS server is running on another remote host, you can configure the JMS adapter to talk to the server by using the following connector entry. Note that the only difference with this connector entry is in the factory properties. The factory properties can establish a JNDI context for the adapter. Substitute [hostname] with the hostname of the server on which the OC4J JMS server is running. If the RMI port of the remote OC4J instance is not the default value (23791), you must specify the RMI port in the provider URL (that is, ormi://remotehost.domain.com:23795).

<connector-factory location="eis/RemoteOC4JJMS/Queue" connector-name="Jms Adapter">     <config-property name="connectionFactoryLocation"
           value="jms/QueueConnectionFactory" /> 
     <config-property name="factoryProperties"
value="java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory;java.naming.provider.url=ormi://[hostname]; java.naming.security.principal=admin;java.naming.security.credentials=welcome" /> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
     <config-property name="isTopic" value="false" /> 
     <config-property name="isTransacted" value="true" /> 
     <config-property name="username" value="admin" /> 
     <config-property name="password" value="welcome" /> 
</connector-factory>

In this case, the correct JMS connection JNDI name for Step 5 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter" is eis/RemoteOC4JJMS/Queue.

In addition, you must have the file META-INF/application-client.xml in the classpath. The contents of the file can be the following:

<application-client/>

To put this file in the classpath, put the specified contents into the file at Oracle_Home\integration\orabpel\system\classes\META-INF\application-client.xml and restart Oracle BPEL Server.

If you set isTransacted to true in the oc4j-ra.xml file for an outbound connection, you receive an error. Do not set this value to true for outbound connections.

Destination Name

The destination name for OC4J JMS is either a JNDI location (for example, jms/demoQueue or jms/demoTopic) or the actual name of the destination as configured in jms.xml (for example, Demo Queue or Demo Topic).

Configuring for TIBCO JMS

The BPEL OC4J application.xml file should contain the following jar file, where Tibco EMS is installed in C:\tibco\ems. The JMS and JNDI jar files are already present in the classpath and do not need to be included.

<library path=ÓC:\tibco\ems\clients\java\tibjms.jarÓ />

Create the appropriate endpoints for the JMS connection factories in oc4j-ra.xml. After this change is made, restart Oracle BPEL Server. Here are the appropriate code segments. You can modify the necessary parameters and use this for your purpose:

<connector-factory location="eis/tibjms/Topic" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"
           value="TopicConnectionFactory" /> 
     <config-property name="factoryProperties"
value="java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tibjmsnaming://localhost:7222;java.naming.security.principal=admin;java.naming.security.credentials=password" /> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
     <config-property name="isTopic" value="true" /> 
     <config-property name="isTransacted" value="true" /> 
     <config-property name="username" value="admin" /> 
     <config-property name="password" value="password" /> 
</connector-factory>
<connector-factory location="eis/tibjms/Queue" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"
           value="QueueConnectionFactory" /> 
     <config-property name="factoryProperties" value="java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tibjmsnaming://localhost:7222;java.naming.security.principal=admin;java.naming.security.credentials=password" /> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
     <config-property name="isTopic" value="false" /> 
     <config-property name="isTransacted" value="true" /> 
     <config-property name="username" value="admin" /> 
     <config-property name="password" value="password" /> 
</connector-factory>

In this case, correct JMS connection JNDI names for Step 5 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter" are eis/tibjms/Topic or eis/tibjms/Queue.

When using Tibco JMS, always set the ClientID property as follows in the Oracle_Home\integration\orabpel\system\appserver\oc4j\j2ee\home\application-deployments\default\FtpAdapter\oc4j-ra.xml file:

<config-property name="factoryProperties" 
    value="ClientID=clientId{time}"/> 

The substring {time} instructs the run time to replace it with the value of Java System.currentTimeMillis(). The other supported substitutions are:

• {checksum}

  A checksum based on the values of the oc4j-ra.xml connection factory properties (referenced through jca:address).

• {sequence}

  Next member of an increasing series of integers starting at zero.

These settings enable you to specify a fixed or a variable ClientID in oc4j-ra.xml.

<connector-factory location="eis/tibjmsDirect/Topic" connector-name="Jms Adapter"> 
     <config-property name="connectionFactoryLocation" 
                      value="com.tibco.tibjms.TibjmsTopicConnectionFactory"/> 
     <config-property name="factoryProperties" 
  @ value="ServerUrl=tcp://152.69.159.188:7222;UserName=admin;UserPassword=passwor d"/> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/> 
     <config-property name="isTopic" value="true"/> 
     <config-property name="isTransacted" value="true"/> 
     <config-property name="username" value="admin"/> 
     @ <config-property name="password" value="password"/> 
</connector-factory> 

Configuring for IBM Websphere JMS

The BPEL OC4J application.xml file should contain the following jar files, assuming MQ Series is installed in the C:\mqseries directory.

<library path="C:\mqseries\java\lib\com.ibm.mq.jar" />

<library path="C:\mqseries\java\lib\com.ibm.mqjms.jar" />

Create the appropriate endpoints for the JMS connection factories in oc4j-ra.xml. After this change is made, you must restart Oracle BPEL Server. Here are the appropriate code segments. You can modify the necessary parameters and use this for your purpose.

<connector-factory location="eis/mqseries/Queue" connector-name="Jms Adapter">
     <config-property name="connectionFactoryLocation"
           value="com.ibm.mq.jms.MQQueueConnectionFactory" /> 
     <config-property name="factoryProperties" value="QueueManager=my.queue.manager;TransportType=1;HostName=myhost.com;Port=1414;Channel=MYCHANNEL" /> 
     <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" /> 
     <config-property name="isTopic" value="false" /> 
     <config-property name="isTransacted" value="true" /> 
     <config-property name="username" value="MUSR_MQADMIN" /> 
     <config-property name="password" value="password" /> 
</connector-factory>

In this case, the correct JMS connection JNDI name for Step 5 of "Using the Adapter Configuration Wizard to Configure a JMS Adapter" is eis/mqseries/Queue.

Destination Name

The destination name is the name of the topic or queue listed in your MQ Series configuration. For example, the name of the queue can be queue:///MYQUEUE?targetClient=1.