8 Oracle JCA Adapter for JMS

This chapter describes how to use the Oracle JCA Adapter for JMS (Oracle JMS Adapter), which enables an Oracle BPEL process or an Oracle Mediator component to interact with JMS.

This chapter includes the following topics:

Introduction to the Oracle JMS Adapter
Oracle JMS Adapter Features
Oracle JMS Adapter Concepts
Oracle JMS Adapter Use Cases

Introduction to the Oracle JMS Adapter

The JMS architecture uses one client interface to many messaging servers. The JMS model has two messaging domains, point-to-point and publish-subscribe. In the point-to-point domain, messages are exchanged through a queue and each message is delivered to only one receiver. In the publish-subscribe model, messages are sent to a topic and can be read by many subscribed clients.

For JMS adapter sample files, go to

http://www.oracle.com/technology/sample_code/products/adapters

This section includes the following topics:

Oracle JMS Adapter Integration with Oracle BPEL Process Manager
Oracle JMS Adapter Integration with Oracle Mediator

Oracle JMS Adapter Integration with Oracle BPEL Process Manager

The JCA Binding Component is used for the bidirectional integration of the JCA 1.5 resource adapters with BPEL Process Manager. The JCA Binding Component is based on standards and employs the Web service Invocation Framework (WSIF) technology for exposing the underlying JCA interactions as Web services.

For information on Oracle JMS Adapter architecture, adapter integration with Oracle BPEL Process Manager (Oracle BPEL PM), and adapter deployments, see Chapter 3, "Adapter Integration with Oracle Application Server Components."

Oracle JMS Adapter Integration with Oracle Mediator

Mediator supports Oracle JCA Adapters and enables you to define inbound and outbound adapter services for each. An inbound adapter service receives data from an external messaging system and transforms it into an XML message. An outbound adapter service sends data to a target application by transforming an XML message into the native format of the given adapter.

In the case of Oracle JMS Adapter service, by using Mediator, you can send or receive messages from a JMS queue or topic.

Oracle BPEL PM pre-dates Mediator, and most of this guide and the samples implicitly assume use with Oracle BPEL PM. However, the adapters work equally well with either Oracle BPEL PM or Mediator. For any mention of Oracle BPEL PM in this chapter, you may substitute Mediator, instead.

Oracle JMS Adapter Features

The Oracle JMS Adapter includes the following features:

Is based on JMS version 1.0.2b
Is a generic Oracle JMS Adapter

Works with any JMS provider. It has been certified against AQ JMS (JMS providers OJMS 8.1.7, 9.0.1.4, and 9.2), TIBCO JMS, IBM Websphere MQSeries (IBM MQSeries JMS 6.0), Weblogic JMS, Apache, and Active MQ.
Supports JMS topics and queues
Supports byte, text, and map message types.

Supports these data types only for this release. The Adapter Configuration Wizard provides the Native Format Builder wizard for consuming native data payloads at run time. The Native Format Builder wizard creates XSD definitions for the underlying native data.
Supports JMS headers and properties
Supports the JMS message selector

Supports the JMS message selector for performing filtering while subscribing to JMS topics and queues. This parameter is based on the SQL 92 language for filtering messages based on fields present in the JMS header and properties section.
Is DOM2 compliant

The Oracle JMS Adapter can process and generate document objects that are compliant with DOM2 specification.
Supports normalized message.

Header manipulation and propagation is a key business integration messaging requirement. Oracle BPEL PM, Mediator, Oracle JCA, and Oracle B2B rely extensively on header support to solve customers' integration needs. For example, a user can preserve a file name from the source directory to the target directory by propagating it through message headers. Another example: the outbound Oracle JMS Adapter facilitates asynchronous request/response by propagating the correlationId and the JMSReplyTo address as JMS headers. In Oracle BPEL PM and Mediator, users can access, manipulate, and set headers with varying degrees of UI support.

For more information, see Oracle BPEL Process Manager Correlation Support Within Adapters.

Propagating Headers in a Normalized Message:

Normalized Message is simplified to have only two parts, properties and payload.Typically, properties are name-value pairs of scalar types. To fit the existing complex headers into properties, they will be flattened into scalar types.

Manipulating Headers in Design-Time:

The user experience while manipulating headers in design time is simplified, because the complex properties are predetermined. In Mediator or Oracle BPEL designer, you can manipulate the headers with some reserved key words. For example, in Mediator designer, you can access an inbound Oracle File Adapter, fileName header by using the following expression:
```
$nmproperty.InboundFileHeaderType.fileName
```
However, this method does not address the properties that are dynamically generated based on your input. For example, in the Oracle AQ Adapter Wizard, you are allowed to propagate some of the fields from an AQ object as headers. Based on this user choice, the header definitions are generated. These definitions are not predetermined and hence cannot be accounted for in the list of predetermined property definitions. The user cannot design header manipulation of the dynamic properties before they are defined. To address this limitation, you must generate all the necessary services (composite entry points) and references. This restriction applies only to those services that are expected to generate dynamic properties. Once dynamic properties are generated, they must be captured in some given location for each composite. Only then can the user manipulate the dynamic properties in the Oracle Mediator or Oracle BPEL designer.
Supports specifying a durable JMS subscriber
Supports persistent and nonpersistent modes of a JMS publisher
Does not support connection retry functionality for MQ provider
Does not support outbound retry functionality for AQJMS on Solaris

Note:
When you use the Oracle JMS Adapter to connect to an AQ-JMS provider, and if the database that hosts the AQ destination is 10.1.0.4, then the adapter retry mechanism on the outbound direction will fail to reconnect to the database server if the database server goes down. This is because of a client JDBC issue with ojdbc14.jar. To resolve this you must download the 10.1.0.4 JDBC drivers and use them in the mid tier by replacing the libraries, specifically ojdbc14.jar in $MIDTIER_ORACLE_HOME/jdbc. For a detailed explanation about how to resolve this issue, refer to Metalink Note 317385.1.
The JMS API specifies three types of acknowledgments that can be sent by the JMS publisher:
- DUPS_OK_ACKNOWLEDGE, for consumers that are not concerned about duplicate messages
- AUTO_ACKNOWLEDGE, in which the session automatically acknowledges the receipt of a message
- CLIENT_ACKNOWLEDGE, in which the client acknowledges the message by calling the message's acknowledge method
Supports tracking message size

The Oracle JMS Adapter is message size aware. The Oracle JMS Adapter calculates the message size and reports the size back to the JCA Binding Component. The API, related to size, exposed by the JCA Binding Component can be used for reporting purposes.
Supports MapMessage Data Type

A MapMessage is used to send a set of name-value pairs where names are strings and values are Java primitive types. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. It inherits from a message and adds a map message body.

Oracle JMS adapter provides support for processing MapMessage. It now supports one new ActivationSpec and InteractionSpec property each namely JmsMapMessageConsumeActivationSpec and JmsMapMessageProduceInteractionSpec.

The PayloadEntry property specifies that the MapMessage entry will be used as the payload. Users have the option to send payload as an attachment if the AttachmentList property is defined.

All other MapMessage entries are converted to adapter properties identified by jca.jms.Map.xxxx, where xxxx is name of the MapMessage entry.

If both PayloadEntry and AttachmentList properties are not defined, then the entire MapMessage is converted to XML and the XML file is transferred as the payload.
Supports Enterprise Information System (EIS) Credentials

The Oracle JMS Adapter supports securing of the Enterprise Information System (EIS) credentials such as the user name and password, whenever it establishes an outbound connection with EIS. You can secure the user name and password for Oracle JMS Adapter by using Oracle WebLogic Server container-managed sign-on.

For more information about support for securing of the Enterprise Information System (EIS) credentials, see Securing Enterprise Information System Credentials.
Supports Streaming Large Payload

Oracle JMS Adapter provides support to stream payload. When you enable this feature, the payload is streamed to a database instead of getting manipulated in the SOA run time as in a memory DOM. This feature can be used while handling large payloads. To enable support to stream payload, ensure that you select the Enable Streaming check box while defining the consume operation parameters on the Consume Operation Parameters page in Oracle JDeveloper (JDeveloper). When the Enable Streaming check box is selected, a corresponding Boolean property EnableStreaming is appended to the ActivationSpec properties defined in the respective .jca file, as shown in the following example. If the EnableStreaming property does not exist, then the default value of false is assumed.
```
<activation-spec className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec">
  <property name="DestinationName" value="jms/DemoInQueue"/>
  <property name="UseMessageListener" value="false"/>
  <property name="PayloadType" value="TextMessage"/>
  <property name="EnableStreaming" value="true"/>
</activation-spec>
```
Supports Transactions

A transaction enables an application to coordinate a group of messages for production and consumption, treating messages sent or received as a single unit. When an application commits a transaction, all messages it received within the transaction are removed by the JMS provider. The messages it sent within the transaction are delivered as one unit to all JMS consumers. If the application rolls back the transaction, then the messages it received within the transaction are returned to the messaging system and the messages it sent are discarded. The Oracle JMS Adapter supports JMS transactions. A JMS-transacted session supports transactions that are located within the session. A JMS-transacted session's transaction does not have any effects outside of the session.
Supports Error Handling

For information about error handling, refer to Error Handling.
Supports Performance Tuning

The Oracle JMS Adapter supports performance tuning.

For more information, see "Oracle SOA JMS Adapter Tuning" in the Oracle Fusion Middleware Performance Guide.

Note:

Oracle JMS Adapter cannot be used programmatically inside an EJB or JMS client.

Oracle JMS Adapter Concepts

Messaging is any mechanism that enables 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, and 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, WLS 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).

This section includes the following topics:

Point-to-Point
Publish/Subscribe
Destination, Connection, Connection Factory, and Session
Structure of a JMS Message
Oracle JMS Adapter Header Properties

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 the subscribers are active. However, JMS API supports durable subscriptions that ensure that consumers receive messages that were published even when the subscribers 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.

For scenarios that requires you to work with durable subscriptions on Oracle WebLogic Server, a connector factory with ClientID property defined is required, as shown in the following example:

<FactoryProperties>ClientID=uniquename</FactoryProperties>

When defining multiple durable subscriber it would entail you to define multiple connector factory each with a unique ClientID property specified. You must take care to not use the same connector factory for any other adapter interaction (such as outbound interaction if it is used for processing inbound messages) because Oracle WebLogic Server allows a clientid to be bound only once. For a scenario in which a connector factory with ClientId defined is used on the inbound to process incoming messages a different connector factory should be used for the outbound adapter interactions.

Note:

You must manually remove durable subscribers that are not used by the BPEL partner link. Oracle JMS Adapter does not automatically remove these durable subscriptions.

The JMS API supports both synchronous and 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, an optional properties element, and an 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.

Oracle JMS Adapter Header Properties

For information about the Oracle JMS Adapter header properties, see Appendix A, "Oracle JMS Adapter Properties."

Oracle JMS Adapter Use Cases

This section includes the following topics:

Configuring Oracle JMS Adapter
Configuring Oracle JMS Adapter with TIBCO JMS
Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS
WLS JMS Text Message
Accessing Queues and Topics from WLS JMS Server in a Remote Oracle WebLogic Server Domain
Synchronous/Asynchronous Request Reply Interaction Pattern
AQ JMS Text Message
Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4 Server

Configuring Oracle JMS Adapter

The following use case demonstrates the procedure for configuring Oracle JMS Adapter and examines the resulting WSDL files and associated weblogic-ra.xml files.

This section includes the following topics:

Creating an Application and an SOA Project
Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter
Generated Files
weblogic-ra.xml file
Produce Message Procedure

Creating an Application and an SOA Project

You must first create an JDeveloper application to contain the SOA composite. Use the following steps to create a new application and an SOA project:

Open JDeveloper.
In the Application Navigator, click New Application.

The Create Generic Application - Name your Application page is displayed, as shown in Figure 8-1.
Enter a name for the application in the Application Name field. For example, AQQueue2Queue.
In the Application Template list, choose Generic Application.

Figure 8-1 The Create Generic Application - Name your application Page

Description of "Figure 8-1 The Create Generic Application - Name your application Page"
Click Next.

The Name your project dialog is displayed, as shown in Figure 8-2.
In the Project Name field, enter a descriptive name. For example, AQQueue2Queue.
In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.

Figure 8-2 The Create Generic Application - Name your Generic project Page

Description of "Figure 8-2 The Create Generic Application - Name your Generic project Page"
Click Next.

The Create Generic Application - Configure SOA settings page is displayed, as shown in Figure 8-3.

Figure 8-3 The Create Generic Application - Configure SOA Settings Page

Description of "Figure 8-3 The Create Generic Application - Configure SOA Settings Page"
Select Composite With BPEL from the Composite Template list, and then click Finish.

You have created a new application, and an SOA project. This automatically creates an SOA composite.

The Create BPEL Process page is displayed, as shown in Figure 8-4.

Figure 8-4 The Create BPEL Process Page

Description of "Figure 8-4 The Create BPEL Process Page"
Enter a name for the BPEL process in the Name field. In this example, use the default name.
Select Define Service Later in the Template list, and then click OK.

You have created a BPEL process.

Using the Adapter Configuration Wizard to Configure Oracle JMS Adapter

The following are the steps to configure an Oracle JMS Adapter by using the Adapter Configuration Wizard:

In the Component Palette, select SOA.
Drag and drop JMS Adapter from the Service Adapters list to the Exposed Services swim lane in the composite.xml page.

The Adapter Configuration Wizard is displayed.
Click Next.

The Adapter Configuration Wizard - Service Name page is displayed, as shown in Figure 8-5.

Figure 8-5 Service Name Page

Description of "Figure 8-5 Service Name Page"
Enter a name for the service, and then click Next.

The Adapter Configuration Wizard - JMS Provider page is displayed, as shown in Figure 8-6.

Figure 8-6 The Adapter Configuration Wizard - JMS Provider Page

Description of "Figure 8-6 The Adapter Configuration Wizard - JMS Provider Page"
Select any one operation. In this example, select Oracle Weblogic JMS.
- Oracle Enterprise Messaging Service (OEMS): This enables you to integrate with the Weblogic service or Advanced Queueing messaging service.
- Third Party: Select this option to integrate with a third party provider.
Click Next.

The Adapter Configuration Wizard - Service Connection page is displayed.
You must establish connectivity between the design-time environment and the server you want to deploy it to.

Perform the steps mentioned in Creating an Application Server Connection for Oracle JCA Adapters to create an application server connection.
Click Next. The Adapter Interface page is displayed, as shown in Figure 8-7.
In the Adapter Interface page, select Define from operation and schema (specified later).

Figure 8-7 The Adapter Configuration Wizard - Adapter Interface Page

Description of "Figure 8-7 The Adapter Configuration Wizard - Adapter Interface Page"
Click Next.

The Adapter Configuration Wizard- Operation page is displayed.
Select Consume Message, Produce Message, or Request/Reply. In this example, select Consume Message.

The operation name is filled in automatically, as shown in Figure 8-8.

Figure 8-8 The Adapter Configuration Wizard - Operation Page

Description of "Figure 8-8 The Adapter Configuration Wizard - Operation Page"

The Consume Message option enables the adapter to consume (receive) inbound messages from a JMS destination.
Click Next.

The Adapter Configuration Wizard - Consume Operation Parameters page is displayed, as shown in Figure 8-9.

Figure 8-9 The Adapter Configuration Wizard - Consume Operation Parameters Page

Description of "Figure 8-9 The Adapter Configuration Wizard - Consume Operation Parameters Page"
Enter values for the following fields:
- Destination Name
  
  This is the JNDI name of the JMS queue or topic from which to receive the message. This is not an editable field. You must click Browse to browse for the queue or topic. The queue or topic to be chosen is based on the type of JMS provider you are using.
  
  For more information, see the following sections:
  - Configuring Oracle JMS Adapter with TIBCO JMS
  - Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS
- Message Body Type
  
  The supported values are TextMessage, BytesMessage, MapMessage. The StreamMessage message type is 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. Generally, a subscriber loses messages if the subscriber becomes disconnected, but a durable subscriber downloads stored messages when it reconnects.
  
  Note:
  When the JMS provider is Oracle Weblogic JMS or Oracle Advanced queueing messaging service, then the Durable Subscriber option will show up only when a topic is selected. However, the Durable Subscriber option always appears when the JMS provider is a third party.
- 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 always set to False by default.
- JNDI Name
  
  The value specified in the JNDI name should exist in the Oracle JMS Adapter weblogic-ra.xml file to ensure that the adapter runs in managed mode.
Note:
This example shows a consume message operation. For a produce message operation, this page is different. See Produce Message Procedure to see how this part of the procedure differs.

After you enter the appropriate parameters, click Next.
The Adapter Configuration Wizard - Messages page is displayed, as shown in Figure 8-10. The settings in this page 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.

Figure 8-10 The Adapter Configuration Wizard - Messages Page

Description of "Figure 8-10 The Adapter Configuration Wizard - Messages Page"
Click the Browse button.

The Type Chooser dialog is displayed, with the Type Explorer navigation tree, as shown in Figure 8-11.
Browse the tree and select the appropriate schema type, and then click OK.

Figure 8-11 Selecting a Schema from the Type Chooser Dialog

Description of "Figure 8-11 Selecting a Schema from the Type Chooser Dialog"

The Messages page is displayed again, this time with the Schema File URL field and the Schema Element field filled up, as shown in Figure 8-12.

Figure 8-12 Completed Messages Dialog

Description of "Figure 8-12 Completed Messages Dialog"
Click Next.

The Finish page is displayed. This box shows the path and name of the adapter file that the wizard creates.
Click Finish.

The composite.xml page is displayed.

Generated Files

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

<composite name="AQQueue2Queue"           revision="1.0"           label="2007-09-04_11-58-50_914"           mode="active"           state="on"           xmlns="http://xmlns.oracle.com/sca/1.0"           xmlns:xs="http://www.w3.org/2001/XMLSchema"           xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"           xmlns:orawsp="http://schemas.oracle.com/ws/2006/01/policy">
  <import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/"          location="Inbound.wsdl" importType="wsdl"/>
  <import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/"          location="Outbound.wsdl" importType="wsdl"/>
  <service name="Inbound">
    <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/#wsdl.interface(Consume_Message_ptt)"/>
    <binding.jca config="Inbound_jms.jca"/>
  </service>
  <component name="BPELProcess1">
    <implementation.bpel src="BPELProcess1.bpel"/>
  </component>
  <reference name="Outbound">
    <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/#wsdl.interface(Produce_Message_ptt)"/>
    <binding.jca config="Outbound_jms.jca"/>
  </reference>
  <wire>
    <source.uri>Inbound</source.uri>
    <target.uri>BPELProcess1/Inbound</target.uri>
  </wire>
  <wire>
    <source.uri>BPELProcess1/Outbound</source.uri>
    <target.uri>Outbound</target.uri>
  </wire>
</composite>

The following 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/Inbound/"          location="Inbound.wsdl" importType="wsdl"/>
  <import namespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Outbound/"          location="Outbound.wsdl" importType="wsdl"/>

This code segment imports the necessary namespace.

<definitions name="Inbound" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:imp1="http://xmlns.oracle.com/pcbpel/samples/expense">
    <types>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://xmlns.oracle.com/pcbpel/samples/expense" schemaLocation="xsd/expense.xsd"/>
        </schema>
    </types>
    <message name="ExpenseRecord_msg">
        <part name="ExpenseRecord" element="imp1:ExpenseRecord"/>
    </message>
    <portType name="Consume_Message_ptt">
        <operation name="Consume_Message">
            <input message="tns:ExpenseRecord_msg"/>
        </operation>
    </portType>

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

<adapter-config name="dequeue" adapter="Jms Adapter" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  <connection-factory location="eis/wls/Queue" UIConnectionName="wls3" UIJmsProvider="WLSJMS" adapterRef=""/>
  <endpoint-activation portType="Consume_Message_ptt" operation="Consume_Message">
    <activation-spec className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec">
      <property name="DestinationName" value="jms/DemoInQueue"/>
      <property name="UseMessageListener" value="false"/>
      <property name="PayloadType" value="TextMessage"/>
    </activation-spec>
  </endpoint-activation>
</adapter-config>

weblogic-ra.xml file

The weblogic-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 weblogic-ra.xml file:

<connection-instance>    <jndi-name>eis/wls/Queue</jndi-name>
    <connection-properties>
       <properties>
           <property>
               <name>ConnectionFactoryLocation</name>
               <value>weblogic.jms.XAConnectionFactory</value>
           </property>
           <property>
               <name>FactoryProperties</name>
               <value></value>
           </property>
           <property>
               <name>AcknowledgeMode</name>
               <value>AUTO_ACKNOWLEDGE</value>
           </property>
           <property>
              <name>IsTopic</name>
              <value>false</value>
           </property>
           <property>
               <name>IsTransacted</name>
               <value>false</value>
           </property>
           <property>
               <name>Username</name>
               <value></value>
           </property>
           <property>
               <name>Password</name>
               <value></value>
           </property>
           </properties>
      </connection-properties>
</connection-instance>

Note that you can also create a new connection by using the Oracle WebLogic Server Administration Console.

Creating a New Connection by Using the Oracle WebLogic Server Administration Console

The following are the steps for creating a new connection by using the Oracle WebLogic Server Administration Console:

Navigate to the Oracle WebLogic Server Administration Console: http://servername:portnumber/console.
Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.

The Home page of the Oracle WebLogic Server Administration Console is displayed.
Select Deployments in the Domain Structure pane.

The Oracle WebLogic Server Administration Console - Summary of Deployments page is displayed.
Under Deployments, click any JMS adapter that you have deployed. For example, click JmsAdapter.

The Oracle WebLogic Server Administration Console - Settings for JmsAdapter page is displayed.
Click the Configuration tab, and then click the Outbound Connection Pools tab.

The Outbound Connection Pool Configuration Table is displayed.
Click Next.

The Create a New Outbound Connection page is displayed.
Select the default outbound connection group, and then click Next.
Click Next.
In the JNDI Name field, enter the JNDI name that you want to use to obtain the new connection instance. For example, eis/wls/Queue.

Note that you can specify any name for the JNDI field. However, you must ensure that you use the same JNDI name while defining the consume or produce operation parameters in JDeveloper.
Click Finish.

The Save Deployment Plan Assistant page is displayed.

The configuration changes that you made must be stored in a new deployment plan.
In the Path field, select or enter the path of a deployment plan file. The path must end with '.xml'.
Click OK.

You have created a new connection. After you have done this, you must verify whether the properties you have created are correct.
In the Settings for JmsAdapter page, click the Configuration tab, and then click the Properties tab.

The connection that you created is listed in this page. Verify whether this value is correct. For example, if you are connecting to a third-party JMS server, then ensure that the Connection Factory Location field has the correct value applicable for a third-party JMS server.

Note:
In this example, you created a new connection for Oracle JMS Adapter by using the Oracle WebLogic Server Administration Console. To create connection for other adapters, you must follow the same steps. However, ensure that you select the appropriate adapter for which you want to create a connection in Step 4.
Click Save.

Produce Message Procedure

A produce message operation has certain differences in the definition procedure, particularly in Step 13 of Using the Adapter Configuration Wizard to Configure Oracle 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 page is shown in Figure 8-13.

Destination Name:

The JNDI name of the JMS queue or topic to which the message must be delivered. The name to enter is based on the type of JMS provider you use.

For more information about destination name, see the following:
- Configuring Oracle JMS Adapter with TIBCO JMS
- Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS
Message Body Type:

The supported values are TextMessage, BytesMessage, and MapMessage. StreamMessage is 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 15 of Using the Adapter Configuration Wizard to Configure Oracle 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 time 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 8-13 Produce Operation Parameters Page

Description of "Figure 8-13 Produce Operation Parameters Page"

Configuring Oracle JMS Adapter with TIBCO JMS

This section describes how to configure Oracle JMS Adapter with Tibco JMS for direct connection and nondirect connection.

NonDirect Connection

Perform the following steps:

Copy the following file to the <SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/lib folder:
- /<YOUR-TIBCO-INSTALL-LOCATION>/clients/java/tibjms.jar

Configure the connector factory by modifying the weblogic-ra.xml file in AS11gR1SOA/soa/connectors/JmsAdapter.rar, as shown in the following example:

<connection-instance>
          <jndi-name>eis/tibjms/Topic</jndi-name>
          <connection-properties>
                    <properties>
                               <property>
                                        <name>ConnectionFactoryLocation</name>
                                        <value>TopicConnectionFactory</value>
                               </property>
                               <property>
                                        <name>FactoryProperties</name>
<value>java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tibjmsnaming://<HOST>:<PORT>;java.naming.security.principal=<USERNAME>;java.naming.security.credentials=<PASSWORD></value>
                               </property>
                               <property>
                                        <name>AcknowledgeMode</name>
                                        <value>AUTO_ACKNOWLEDGE</value>
                               </property>
                               <property>
                                        <name>IsTopic</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>IsTransacted</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>Username</name>
                                        <value><USERNAME></value>
                               </property>
                               <property>
                                        <name>Password</name>
                                        <value><PASSWORD></value>
                              </property>
                    </properties>
          </connection-properties>
</connection-instance>
<connection-instance>
          <jndi-name>eis/tibjms/Queue</jndi-name>
          <connection-properties>
                    <properties>
                               <property>
                                        <name>ConnectionFactoryLocation</name>
                                        <value>QueueConnectionFactory</value>
                               </property>
                               <property>
                                        <name>FactoryProperties</name>
<value>java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory;java.naming.provider.url=tibjmsnaming://<HOST>:<PORT>;java.naming.security.principal=<USERNAME>;java.naming.security.credentials=<PASSWORD></value>
                               </property>
                               <property>
                                        <name>AcknowledgeMode</name>
                                        <value>AUTO_ACKNOWLEDGE</value>
                               </property>
                               <property>
                                        <name>IsTopic</name>
                                        <value>false</value>
                               </property>
                               <property>
                                        <name>IsTransacted</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>Username</name>
                                        <value><USERNAME></value>
                               </property>
                               <property>
                                        <name>Password</name>
                                        <value><PASSWORD></value>
                               </property>
                    </properties>
          </connection-properties>
</connection-instance>

Note that the default <USERNAME> and <PASSWORD> are admin and password, respectively.

Alternatively, to configure a new connection factory by using the Oracle WebLogic Server Administration Console, use the steps mentioned in Adding an Adapter Connection Factory.

Direct Connection

Perform the following steps:

Copy the following file to the <SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/lib folder:
- /<YOUR-TIBCO-INSTALL-LOCATION>/clients/java/tibjms.jar

Configure the connector factory by modifying the weblogic-ra.xml file in AS11gR1SOA/soa/connectors/JmsAdapter.rar, as shown in the following example:

<connection-instance>
          <jndi-name>eis/tibjmsDirect/Queue</jndi-name>
          <connection-properties>
                    <properties>
                               <property>
                                        <name>ConnectionFactoryLocation</name>
                                        <value>com.tibco.tibjms.TibjmsQueueConnectionFactory</value>
                               </property>
                               <property>
                                        <name>FactoryProperties</name>
                                        <value>ServerUrl=tcp://<HOST>:<PORT>;UserName=<USERNAME>;UserPassword=<PASSWORD></value>
                               </property>
                               <property>
                                        <name>AcknowledgeMode</name>
                                        <value>AUTO_ACKNOWLEDGE</value>
                               </property>
                               <property>
                                        <name>IsTopic</name>
                                        <value>false</value>
                               </property>
                               <property>
                                        <name>IsTransacted</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>Username</name>
                                        <value><USERNAME></value>
                               </property>
                               <property>
                                        <name>Password</name>
                                        <value><PASSWORD></value>
                               </property>
                    </properties>
          </connection-properties>
</connection-instance>
<connection-instance>
          <jndi-name>eis/tibjmsDirect/Topic</jndi-name>
          <connection-properties>
                    <properties>
                                <property>
                                        <name>ConnectionFactoryLocation</name>
                                         <value>com.tibco.tibjms.TibjmsTopicConnectionFactory</value>
                               </property>
                               <property>
                                        <name>FactoryProperties</name>
                                        <value>ServerUrl=tcp://<HOST>:<PORT>;UserName=<USERNAME>;UserPassword=<PASSWORD></value>
                               </property>
                               <property>
                                        <name>AcknowledgeMode</name>
                                        <value>AUTO_ACKNOWLEDGE</value>
                               </property>
                               <property>
                                        <name>IsTopic</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>IsTransacted</name>
                                        <value>true</value>
                               </property>
                               <property>
                                        <name>Username</name>
                                        <value><USERNAME></value>
                               </property>
                               <property>
                                        <name>Password</name>
                                        <value><PASSWORD></value>
                               </property>
                     </properties>
           </connection-properties>
</connection-instance>

Note that the default <USERNAME> and <PASSWORD> are admin and password, respectively.

Alternatively, to configure a new connection factory by using the Oracle WebLogic Server Administration Console, use the steps mentioned in Adding an Adapter Connection Factory.

Configuring Oracle JMS Adapter with IBM WebSphere MQ JMS

This section describes how to configure Oracle JMS Adapter with IBM WebSphere MQ JMS for non-XA and XA data sources.

Non-XA Data Sources

Perform the following steps:

Copy the following files to the <SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/lib folder:
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mq.jar
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mqjms.jar
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/dhbcore.jar

Configure the connector factory by modifying the weblogic-ra.xml file in AS11gR1SOA/soa/connectors/JmsAdapter.rar, as shown in the following example:

<connection-factory connector-name="Jms Adapter" location="eis/webspheremq/Queue"><config-property name="connectionFactoryLocation" value="com.ibm.mq.jms.MQQueueConnectionFactory" encodedcredential="false"/><config-property name="factoryProperties"value="QueueManager=<QUEUEMANAGER>;TransportType=1;HostName=<YOUR-HOST>;Port=<YOURPORT>;Channel=<CHANNEL>" encoded-credential="false"/><config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" encoded-credential="false"/><config-property name="isTopic" value="false" encoded-credential="false"/><config-property name="isTransacted" value="true" encoded-credential="false"/><config-property name="username" value="<USERNAME>" encoded-credential="false"/><config-property name="password" value="<PASSWORD>" encoded-credential="false"/></connection-factory>

Note that the default <USERNAME> and <PASSWORD> are MUSR_MQADMIN and password, respectively.

Alternatively, to configure a new connection factory by using the Oracle WebLogic Server Administration Console, use the steps mentioned in Adding an Adapter Connection Factory.

XA Data Sources

Perform the following steps:

Copy the following files to the <SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/lib folder:
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mq.jar
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/com.ibm.mqjms.jar
- /<YOUR-MQSERIES-INSTALL-LOCATION>/java/lib/dhbcore.jar
- com.ibm.mqetclient.jar
  
  This is an IBM-extended transactional client, which is an optional component that requires separate licensing.

Configure the connector factory by modifying the weblogic-ra.xml file in AS11gR1SOA/soa/connectors/JmsAdapter.rar, as shown in the following example:

<connection-factory connector-name="Jms Adapter" location="eis/webspheremq/Queue"><config-property name="connectionFactoryLocation" value="com.ibm.mq.jms.MQXAQueueConnectionFactory"encoded-credential="false"/><config-property name="factoryProperties"value="QueueManager=<QUEUEMANAGER>;TransportType=1;HostName=<YOUR-HOST>;Port=<YOURPORT>;Channel=<CHANNEL>" encoded-credential="false"/><config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE" encoded-credential="false"/><config-property name="isTopic" value="false" encoded-credential="false"/><config-property name="isTransacted" value="false" encoded-credential="false"/><config-property name="username" value="<USERNAME>" encoded-credential="false"/><config-property name="password" value="<PASSWORD>" encoded-credential="false"/></connection-factory>

Note that the default <USERNAME> and <PASSWORD> are MUSR_MQADMIN and password, respectively.

Alternatively, to configure a new connection factory by using the Oracle WebLogic Server Administration Console, use the steps mentioned in Adding an Adapter Connection Factory.

Right-click the queue and select Put Test Message to send message by using WebSphere MQ Explorer.
Right-click the queue and select Browse Messages to browse messages in outbound queue by using WebSphere MQ Explorer.

WLS JMS Text Message

This use case demonstrates how the Oracle JMS Adapter dequeues from and enqueues to the WLS JMS Queue.

This sample (adapters-jms-101-wlsjms-textmessageusingqueues) is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

This section includes the following topics:

Meeting Prerequisites
Creating an Application Server Connection
Creating an Application and an SOA Project
Creating an Inbound Adapter Service
Creating an Outbound Adapter Service
Wiring Services and Activities
Deploying with JDeveloper
Monitoring Using the Fusion Middleware Control Console

Meeting Prerequisites

You must perform the following prerequisite for this use case:

Creating Queues in the Oracle WebLogic Server Administration Console

Perform the following steps to create queues required for this use case:

Navigate to the Oracle WebLogic Server Administration Console: http://servername:portnumber/console
Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.

The Home page of the Oracle WebLogic Server Administration Console is displayed, as shown in Figure 8-14.

Figure 8-14 The Oracle WebLogic Server Administration Console Home Page

Description of "Figure 8-14 The Oracle WebLogic Server Administration Console Home Page"
Navigate to Services, Messaging, JMS Modules in the Domain Structure pane.

The Oracle WebLogic Server Administration Console - JMS Modules page is displayed.
Click one of the existing modules. In this example, click SOAJMSModule.

The Oracle WebLogic Server Administration Console - Settings for SOAJMSModule page is displayed.
Under the Summary of Resources section, click New.

The Oracle WebLogic Server Administration Console - Create a New JMS System Module Resource page is displayed.
Select Queue, and then click Next.
Enter the following queue details:
- Name
- JNDI Name
- Template
Click Next.
Select the subdeployment you want to use from the Subdeployments list.
Click Finish.

You have created the queue, ReceiveQueue.
Repeat steps 1 through 10, and create a queue named SendQueue.

Creating an Application Server Connection

You must establish connectivity between the design-time environment and the server you want to deploy to. Perform the steps mentioned in Creating an Application Server Connection for Oracle JCA Adapters to create an application server connection.

Creating an Application and an SOA Project

You must create an JDeveloper application to contain the SOA composite. Use the following steps to create a new application and an SOA project:

Open JDeveloper.
In the Application Navigator, click New Application. The Create Generic Application - Name your Application dialog is displayed.
Enter a name for the application in the Application Name field. For example, queue2queue.
In the Application Template list, choose Generic Application.
Click Next.

The Name your project page is displayed.
In the Project Name field, enter a descriptive name. For example, queue2queue.
In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.
Click Next. The Create Generic Application - Configure SOA settings page is displayed.
Select Composite With BPEL from the Composite Template list, and then click Finish.

You have created a new application, and an SOA project.

The Create BPEL Process page is displayed.
Enter a name for the BPEL process in the Name field. For example, queue2queue.
Select Define Interface Later in the Template list, and then click OK.

You have created a BPEL process.

The queue2queue application, queue2queue project, and the SOA composite appear in the design area.
Copy the Q2Qorders.xsd file from the following location to the XSD folder in your project:

http://www.oracle.com/technology/sample_code/products/adapters

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message to a queue:

Drag and drop JMS Adapter from the Service Adapters list to the Exposed Services swim lane in the composite.xml page.

The Adapter Configuration Wizard Welcome page is displayed.
Click Next.

The Service Name page is displayed.
Enter Inbound in the Service Name field, and click OK.

The JMS Provider page is displayed.
Select Oracle Weblogic JMS in the Oracle Enterprise Messaging Service (OEMS) box, as shown in Figure 8-15, and click Next. The Service Connection page is displayed.

Figure 8-15 The Adapter Configuration Wizard JMS Provider Page

Description of "Figure 8-15 The Adapter Configuration Wizard JMS Provider Page"
Select the connection created in Creating an Application Server Connection, as shown in Figure 8-16.

Figure 8-16 The Adapter Configuration Wizard Service Connection Page

Description of "Figure 8-16 The Adapter Configuration Wizard Service Connection Page"
Click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.
Select Consume Message, as shown in Figure 8-17, and click Next.

The Consume Operation Parameters page is displayed.

Figure 8-17 The Adapter Configuration Wizard Operation Page

Description of "Figure 8-17 The Adapter Configuration Wizard Operation Page"
Click Browse and select ReceiveQueue in the Destination field.

The Consume Operation Parameters page is displayed.
Enter the parameters for the consume operation, and then click Next.

The Messages page is displayed.

Note:
The value specified in the JNDI name should exist in the Oracle JMS Adapter weblogic-ra.xml file to ensure that the adapter runs in managed mode.
Click Browse at the end of the URL field.

The Type Chooser dialog is displayed.
Select Project Schema Files, Q2Qorders.xsd, and Items, as shown in Figure 8-18.

Figure 8-18 The Type Chooser Dialog

Description of "Figure 8-18 The Type Chooser Dialog"
Click Next. The Q2Qorders.xsd schema file is displayed in the URL in the Messages page, as shown in Figure 8-19.

Figure 8-19 The Adapter Configuration Wizard - Message Page

Description of "Figure 8-19 The Adapter Configuration Wizard - Message Page"
Click Next. The Finish page is displayed.
Click Finish. You have configured a JMS inbound adapter service.

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service to enqueue the request messages and dequeue the corresponding response messages (report) from a queue:

Drag and drop JMS Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter Outbound in the Service Name field, and click OK. The JMS Provider page is displayed.
Select Oracle Weblogic JMS in the Oracle Enterprise Messaging Service (OEMS) box, and click Next. The Service Connection page is displayed.
Select the connection created in Creating an Application Server Connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.
Select Produce Message, and click Next. The Produce Operation Parameters page is displayed.
Click Browse and select SendQueue in the Destination field. The Produce Operation Parameters page is displayed.
Click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, Q2Qorders.xsd, and Items.
Click Next. The Q2Qorders.xsd schema file is displayed in the URL in the Message dialog.
Click Next. The Finish page is displayed.
Click Finish. You have configured the JMS adapter service, and the composite.xml page is displayed.

Wiring Services and Activities

You must wire the three components that you have created, Inbound adapter service, BPEL process, and Outbound adapter reference. Perform the following steps to wire components together:

Drag the small triangle in the inbound Oracle JMS Adapter component in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the outbound Oracle JMS Adapter in the External References area.

The JDeveloper Composite.xml is displayed, as shown in Figure 8-20.

Figure 8-20 The JDeveloper - Composite.xml

Description of "Figure 8-20 The JDeveloper - Composite.xml"
Click File, Save All.
Double-click queue2queue.

The queue2queue.bpel page is displayed.
Drag and drop the Receive, Assign, and Invoke activities in the order mentioned from the Component Palette to the Components area, as shown in Figure 8-21.

Figure 8-21 The queue2queue.bpel Page

Description of "Figure 8-21 The queue2queue.bpel Page"
Double-click Receive.

The Receive dialog is displayed.
Click the Browse Partner Links icon at the end of the Partner Link field.

The Partner Link Chooser dialog is displayed.
Select Inbound, and then click OK.

The Receive dialog is displayed with the Partner Link field populated with the value Inbound.
Click the Auto-Create Variable icon that is displayed at the end of the Variable field.

The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Select the Create Instance box, as shown in Figure 8-22, and click OK.

Figure 8-22 The Receive Dialog

Description of "Figure 8-22 The Receive Dialog"
Double-click the Invoke activity.

The Invoke dialog is displayed.
Click the Browse Partner Links icon at the end of the Partner Link field.

The Partner Link Chooser dialog is displayed.
Select Outbound, and then click OK.

The Invoke dialog is displayed with the Partner Link field populated with the value Outbound.
Click the Automatically Create Input Variable icon that is displayed at the end of the Input Variable field.

The Create Variable dialog is displayed.
Accept the defaults, and click OK.

The Invoke dialog is displayed, as shown in Figure 8-23.

Figure 8-23 The Invoke Dialog

Description of "Figure 8-23 The Invoke Dialog"
Click OK.
Double-click the Assign activity.

The Assign dialog is displayed.
Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.
Select the variables, as shown in Figure 8-24, and click OK.

Figure 8-24 The Create Copy Operation Dialog

Description of "Figure 8-24 The Create Copy Operation Dialog"
Click OK in the Assign dialog.
Click File, Save All.

Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, use the following steps:

Create an application server connection by using the procedure described in Chapter 2, "Creating an Application Server Connection for Oracle JCA Adapters."
Deploy the application by using the procedure described in Deploying Oracle JCA Adapter Applications from JDeveloper.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed EM Composite by using the Fusion Middleware Control Console. Perform the following steps:

Navigate to http://servername:portnumber/em.

The composite you deployed is displayed in the Application Navigator.
In the Last 5 Instances pane, there is an entry of a new instance. This is the instance that was triggered when you enqueued a message using queue2queue.java.
Click one of the instances. The Flow Trace page is displayed.
Click the TextMessage component instance. The Audit page is displayed.
Click the Flow-Debug tab to debug the instance.

Accessing Queues and Topics from WLS JMS Server in a Remote Oracle WebLogic Server Domain

Oracle JMS Adapter can be used to access remote WLS JMS destinations. Remote destinations refer to queues or topics that are defined in a WLS JMS server, which is part of a remote Oracle WebLogic Server domain.

In order to do so, ensure that you use the connector factory configured to interact to the remote WLS JMS server. You can achieve this by setting the <FactoryProperties> property of the connector factory defined in weblogic-ra.xml to remote server configuration, as shown in the following example:

<property>
<name>FactoryProperties</name>
<value>java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory;java.naming.provider.url= t3://<HOST>:<PORT>;java.naming.security.principal= <USERNAME>;java.naming.security.credentials=<PASSWORD></value>
</property>

To enable Oracle JMS Adapter to read from a remote queue that is present in a remote WLS JMS server, you must configure the following:

You must have a unique domain name and JMS server name in both the servers.
You must enable global trust between the two servers.

Refer to the following link for information about how to enable global trust between servers:

http://download.oracle.com/docs/cd/E13222_01/wls/docs100/ConsoleHelp/taskhelp/security/EnableGlobalTrustBetweenDomains.html

This configuration holds good when you connect to queues or topics present in WLS9.2 server.

Synchronous/Asynchronous Request Reply Interaction Pattern

Oracle JMS Adapter supports both synchronous and asynchronous request reply interaction pattern.

Synchronous Request Reply Pattern

You can use the Adapter Configuration Wizard to model a process that will allow Oracle JMS Adapter to be used in a synchronous request reply interaction pattern. In this case, the Oracle JMS Adapter sends a request to the request queue and waits for a response from the reply queue before further execution continues. Underneath, the Oracle JMS Adapter uses a new interaction pattern JmsRequestReplyInteractionSpec. This interaction spec allows for a request and reply destination name to be configured.

A variation, new to 11g Release 1 (11.1.1), allows usage of temporary destination as part of the reply queue. Basically, this pattern allows an Oracle JMS Adapter to send a message to a JMS destination. In turn, the adapter will set the JMSReplyTo header to the reply destination. This value is then used by a third party client to send the message to the reply destination which is then dequeued by the Oracle JMS Adapter.

When using the Oracle JMS Adapter in a synchronous pattern ensure that you use a non-XA connection factory and set the connector factory isTransacted property to true in weblogic-ra.xml.

When you use the Oracle JMS Adapter in a synchronous pattern with Oracle WebLogic Server JMS, the connection factory must be weblogic.jms.ConnectionFactory or any other non-XA connection factory. Also, if Oracle WebLogic Server JMS is running in the local JVM (the same JVM as the adapter), then you must ensure that the connector factory isTransacted property is set to false in weblogic-ra.xml.

For more information, see the following samples on http://www.oracle.com/technology/sample_code/products/adapters/index.html:

adapters-jms-106-wlsjms-syncrequestreply
adapters-jms-107-wlsjms-syncrequestreplywithtemporaryreplydestination

Asynchronous Request Reply Pattern

You can use the Adapter Configuration Wizard to model a process that allows Oracle JMS Adapter to be used in an asynchronous request reply interaction pattern.

Basically this pattern allows an Oracle JMS Adapter to send a message to a JMS destination. When a message is received on the reply queue, the Oracle JMS Adapter is able to route message to the correct composite or the component instance. The correlation is done based on the JMSMessageID of the request message, which becomes the JMSCorrelationID of the reply message, and the conversation ID of the underlying component.

For more information, see the following samples on http://www.oracle.com/technology/sample_code/products/adapters/index.html:

adapters-jms-105-wlsjms-nativecorrelation

AQ JMS Text Message

This use case demonstrates how the Oracle JMS Adapter dequeues from and enqueues to the AQ JMS Queue.

This sample (adapters-jms-108-aqjms-textmessageusingqueues) is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

This section includes the following topics:

Meeting Prerequisites
Create an Application Server Connection
Creating an Application and an SOA Project
Creating an Inbound Adapter Service
Creating an Outbound Adapter Service
Wiring Services and Activities
Deploying with JDeveloper
Monitoring Using the Fusion Middleware Control Console

Meeting Prerequisites

You must perform the following prerequisites to complete this use case:

Configuring AQ JMS in Oracle WebLogic Server Administration Console
Creating Queues in Oracle Database

Configuring AQ JMS in Oracle WebLogic Server Administration Console

To configure AQ JMS in Oracle WebLogic Server Administration Console, you must perform the following steps:

Adding an Oracle WebLogic JMS Module
Adding an AQJMS Foreign Server to the JMS Module
Configuring the AQJMS Foreign Server
Adding Connection Factories to the AQ JMS Foreign Server
Adding Destinations to the AQJMS Foreign Server

Adding an Oracle WebLogic JMS Module

Note that adding an Oracle WebLogic JMS module is optional. You can also create an AQJMS foreign server in a preexisting JMS module.

Navigate to the Oracle WebLogic Server Administration Console: http://servername:portnumber/console.
Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.

The Home page of the Oracle WebLogic Server Administration Console is displayed.
Navigate to Services, Messaging, JMS Modules in the Domain Structure pane.

The Oracle WebLogic Server Administration Console - JMS Modules page is displayed.
Click New to create a new WebLogic JMS module.

The Oracle WebLogic Server Administration Console - Create JMS System Module page is displayed.
Enter a name for the JMS module, and then click Next.

The Oracle WebLogic Server Administration Console - Create JMS System Module page is displayed.
Select a target server where your SOA component is running, and then click Next.

The Oracle WebLogic Server Administration Console - Create JMS System Module page is displayed.
Click Finish.

You have created a JMS module.

Adding an AQJMS Foreign Server to the JMS Module

The next step is to add an AQ JMS foreign server to the JMS module by performing the following:

Click the JMS module that you created.

The Oracle WebLogic Server Administration Console - Settings for AQJMSModule page is displayed.
Click New in the Summary of Resources table to create a new JMS system module resource.

The Oracle WebLogic Server Administration Console - Create a New JMS System Module Resource page is displayed.
Under Choose the type of resource you want to create, select Foreign Server, and then click Next.

The Oracle WebLogic Server Administration Console - Create a New JMS System Module Resource page is displayed.
In the Name field, enter a name for the foreign server, and then click Finish.

The Oracle WebLogic Server Administration Console - Settings for <JMS Module Name> page is displayed.

Configuring the AQJMS Foreign Server

The next step is to configure the AQJMS foreign server that you created:

Click the AQ JMS Foreign Server listed under the Summary of Resources table.

The Oracle WebLogic Server Administration Console - Settings for TestAQJMS_ForeignServer page is displayed.
Enter the following values:
- JNDI Initial Context Factory: oracle.jms.AQjmsInitialContextFactory
  
  If the AQJMS Foreign Server is used by the WebLogic server side components, then you must configure a data source with this AQ JMS Foreign Server, by specifying the following values:
  
  In the JNDI Properties field, enter datasource=<datasource jndi location>. Replace the place holder with the JNDI location of your data source.
  
  However, if the AQJMS Foreign Server is used by WebLogic application client, then you must configure the JDBC URL with the AQ JMS foreign server you created.
- JNDI Connection URL: Specify the URL that WebLogic Server will use to contact the JNDI provider.
  
  This value is required only if the AQJMS foreign server is used by the WebLogic application client.
- JNDI Properties Credential: Specify any Credentials that must be set for the JNDI provider.
  
  This value is required only if the AQJMS foreign server is used by the Weblogic application client.

Note:

If you want to use RAC database as adapter endpoint, then the datasource pointed by the JNDI property, mentioned in the preceding step, must point to a multi data source.

Individual data sources and multi data sources used for such endpoints must use the recommended setting listed in Recommended Setting for Data Sources Used by Oracle JCA Adapters.

Adding Connection Factories to the AQ JMS Foreign Server

To add connection factories to the AQJMS foreign server:

In the Connection Factories tab in the Settings for <Foreign Server Name> page, click the AQJMS foreign server that you created.
Click New.

The Oracle WebLogic Server Administration Console - Create a New Foreign JMS Connection Factory page is displayed.
In the Name field, enter a name for this connection factory. This is a logical name that would be referenced by Oracle WebLogic Server.
In the Local JNDI Name field, enter the local JNDI name that you would use in your application to look up this connection factory.

Note:
Ensure that you specify aqjms/XAQueueConnectionFactory for local JNDI name if you are connecting to a queue with JNDI name eis/aqjms/Queue that is provided with the sample use case, AQQueuetoQueue.
Else, specify aqjms/XATopicConnectionFactory if you are connecting to a topic with JNDI name eis/aqjms/Topic.
In the Remote JNDI Name field, enter one of the following values depending on your requirement. If you use this connection factory in a global transaction, then use an XA-based connection factory, else use non-XA based connection factory.
- QueueConnectionFactory
- TopicConnectionFactory
- ConnectionFactory
- XAQueueConnectionFactory
- XATopicConnectionFactory
- XAConnectionFactory
Click OK.

Adding Destinations to the AQJMS Foreign Server

To add destinations to the AQJMS foreign server:

Click the Destinations tab in the Settings for <Foreign Server Name> page.
Click New and specify a name for this destination. This is a logical name that will be referenced by the Oracle WebLogic Server and has nothing to do with the destination name.
In the Local JNDI Name field, enter the local JNDI name you would use in your application to look up this destination.
In the Remote JNDI Name field, enter Queues/<queue name>if the destination is a queue, or enter Topics/<topic name> if the destination is a topic.
Click OK.
Restart the Oracle WebLogic Server Administration Console.

You have configured AQJMS in an Oracle WebLogic Server.

Creating Queues in Oracle Database

To create queues:

Run the setup_user.sql script.
Run the create_start_queues.sql script.

These scripts are located in the adapters-jms-108-aqjms-textmessageusingqueues sample artifacts/sql directory. The adapters-jms-108-aqjms-textmessageusingqueues sample is located here:

http://www.oracle.com/technology/sample_code/products/adapters

Create an Application Server Connection

Creating an Application and an SOA Project

You must create an JDeveloper application to contain the SOA composite. Use the following steps to create a new application and an SOA project:

Open JDeveloper.
In the Application Navigator, click New Application. The Create Generic Application - Name your Application dialog is displayed.
Enter a name for the application in the Application Name field. For example, AQQueue2Queue.
In the Application Template list, choose Generic Application.
Click Next.

The Name your project page is displayed.
In the Project Name field, enter a descriptive name. For example, AQQueue2Queue.
In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.
Click Next. The Create Generic Application - Configure SOA Settings page is displayed.
Select Composite With BPEL from the Composite Template list, and then click Finish.

You have created a new application and an SOA project.

The Create BPEL Process page is displayed.
Enter a name for the BPEL process in the Name field.
Select Define Interface Later in the Template list, and then click OK.

You have created a BPEL process.

The AQQueue2Queue application, the AQQueue2Queue project, and the SOA composite appear in the design area.
Copy the expense.xsd file to the XSD folder in your project.

This file is located in the adapters-jms-108-aqjms-textmessageusingqueues sample artifacts/schemas directory. The adapters-jms-108-aqjms-textmessageusingqueues sample is located here:

http://www.oracle.com/technology/sample_code/products/adapters

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service to dequeue the message to a queue:

Drag and drop JMS Adapter from the Service Adapters list to the Exposed Services swim lane in the composite.xml page. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter Inbound in the Service Name field, and click OK. The JMS Provider page is displayed.
Select Oracle Advanced Queueing in the Oracle Enterprise Messaging Service (OEMS) box, and click Next. The Service Connection page is displayed.
Select the connection created in Creating an Application Server Connection.
Click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.
Select Consume Message, and click Next. The Consume Operation Parameters page is displayed.
Click Browse and select testInQueue in the Destination field.
Click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, expense.xsd.
Click Next. The expenses.xsd schema file is displayed in the URL field in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have configured a JMS inbound adapter service.

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the request messages and dequeue the corresponding response messages (report) from a queue:

Drag and drop JMS Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter Outbound in the Service Name field, and click OK. The JMS Provider page is displayed.
Select Oracle Advanced Queueing in the Oracle Enterprise Messaging Service (OEMS) box, and click Next. The Service Connection page is displayed.
Select the connection created in Creating an Application Server Connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation page is displayed.
Select Produce Message, and click Next. The Produce Operation Parameters page is displayed.
Click Browse and select testOutQueue in the Destination field. The Produce Operation Parameters page is displayed.
Click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, expense.xsd.
Click Next. The expense.xsd schema file is displayed in the URL field in the Message dialog.
Click Next. The Finish page is displayed.
Click Finish. You have configured the JMS adapter service, and the composite.xml page is displayed.

Wiring Services and Activities

You must wire the three components that you have created: Inbound adapter service, BPEL process, and Outbound adapter reference. Perform the following steps to wire the components together:

Drag the small triangle in the inbound Oracle JMS Adapter component in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the outbound Oracle JMS Adapter in the External References area.

The JDeveloper Composite.xml is displayed, as shown in Figure 8-25.

Figure 8-25 JDeveloper - Composite.xml

Description of "Figure 8-25 JDeveloper - Composite.xml"
Click File, Save All.
Double-click the BPEL process. The BPELProcess1.bpel page is displayed.
Drag and drop the Receive, Assign, and Invoke activities, in the order mentioned, from the Component Palette to the Components area.
Double-click the Receive activity.

The Receive dialog is displayed.
Click the Browse Partner Links icon at the end of the Partner Link field.

The Partner Link Chooser dialog is displayed.
Select Inbound, and then click OK.

The Receive dialog is displayed with the Partner Link field populated with the value Outbound.
Click the Auto-Create Variable icon that is displayed at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box.
Double-click the Invoke activity to Outbound.

The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon that is displayed at the end of the Input Variable field.
Click the Browse Partner Links icon at the end of the Partner Link field.

The Partner Link Chooser dialog is displayed.
Select Outbound, and then click OK.

The Invoke dialog is displayed with the Partner Link field populated with the value Outbound.
Accept the defaults, and click OK.
Click OK.
Double-click the Assign activity.

The Assign dialog is displayed.
Click the plus icon, and select Copy Operation.

The Create Copy Operation dialog is displayed.
Select the variables, and click OK.
Click OK in the Assign dialog.
Click File, Save All.

Note:

When using Oracle JMS Adapter to dequeue from AQ JMS Topics with durable subscriptions, if you notice that the dequeue operation exhibits slow performance, then you can speed up the entire performance by using multiple inbound threads for each adapter service.

Oracle JMS Adapter allows multiple inbound threads if you specify an endpoint property adapter.jms.receive.threads.

However, note that this workaround is not applicable when using non-durable subscriptions because doing so will result in duplicate messages.

Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile by using JDeveloper, perform the following steps:

Create an application server connection by using the procedure described in Chapter 2, "Creating an Application Server Connection for Oracle JCA Adapters."
Deploy the application by using the procedure described in Deploying Oracle JCA Adapter Applications from JDeveloper.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed EM Composite by using the Fusion Middleware Control Console. Perform the following steps:

Navigate to http://servername:portnumber/em. The composite you deployed is displayed in the Application Navigator.
In the Last 5 Instances pane, there is an entry of a new instance. This is the instance that was triggered when you enqueued a message by using AQQueue2Queue.java.
Click one of the instances. The Flow Trace page is displayed.
Click the TextMessage component instance. The Audit page is displayed.
Click the Flow-Debug tab to debug the instance.

Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4 Server

This section describes the procedure for accessing queues and topics you created in Oracle Application Server 11g from OC4J 10.1.3.4. To do this, you must configure Oracle BPEL PM JMS adapter with Oracle WebLogic Server.

The following are the steps to configure Oracle BPEL PM JMS adapter with Oracle WebLogic Server:

Create the wlfullclient.jar file using the following steps:
1. Change to the server/lib directory, as shown in the following example:
```
cd WL_HOME/server/lib
```
2. Use the following command to create the wlfullclient.jar file in the server/lib directory:
```
java -jar ../../../modules/com.bea.core.jarbuilder_X.X.X.X.jar
```
  where X.X.X.X is the version number of the jarbuilder module in the WL_HOME/server/lib directory. For example:
```
java -jar ../../../modules/com.bea.core.jarbuilder_1.0.1.0.jar
```
Copy the wlfullclient.jar file to the 10.1.3.4. server at the following location:
```
<ORACLEAS_HOME>/j2ee/<OC4J_INSTANCE>/connectors/JmsAdapter/JmsAdapter
```

Configure the connector factory setting in the oc4j-ra.xml file, as shown in the following example:

<connector-factory location="eis/wlsjms/Queue" connector-name="Jms Adapter">
        <config-property name="connectionFactoryLocation"                value="weblogic.jms.ConnectionFactory"/>
        <config-property name="factoryProperties"          value="java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory;java.naming.provider.url=t3://w3.us.oracle.com:7001;java.naming.security.principal=weblogic;java.naming.security.credentials=weblogic"/>
       <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/>
       <config-property name="isTopic" value="false"/>
       <config-property name="isTransacted" value="false"/>
       <config-property name="username" value=""/>
       <config-property name="password" value=""/>
   <connection-pooling use="none">
   </connection-pooling>
     <security-config use="none">
     </security-config>
</connector-factory>

Note:

The isTransacted configuration property value must typically be set to FALSE. Currently, XA integration with WebLogic JMS is not supported unless the adapter is deployed on Oracle WebLogic Server.

Modify the server.xml file of the 10.1.3.4 server to include the environment-naming-url-factory-enabled="true" property, as shown in the following example:
```
<application-server
...
...
environment-naming-url-factory-enabled="true"
...
> 
```
Restart the 10.1.3.4 server to make the changes come into effect.