Interoperability Solutions Guide

Interoperability with JMS

AquaLogic Service Bus is certified against the following JMS implementations:

WebLogic Server 9.x JMS
IBM WebSphere MQ/JMS 5.3

Configuring proxy services and business services to use the JMS transport is described in the Proxy Services and Business Services sections of the Using the AquaLogic Service Bus Console.

All of the AquaLogic Service Bus service types support the JMS transport. For information about the AquaLogic Service Bus service types and the transports for each of the service types, see "Selecting a Service Type" in Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.

For information about WebLogic Server 9.x JMS, see the following resources:

Managing Your Applications in Programming WebLogic JMS
Configure JMS Servers in the WebLogic Server Administration Console Online Help

This section includes the following additional JMS interoperability topics:

Asynchronous Request/Response

For information about designing asynchronous request/response messaging, including the use of the JMS Correlation ID to link the request and response messages, see "Asynchronous Request/Response" in Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.

SOAP/JMS Transport

When using the JMS binding to configure a business service in BEA WebLogic Workshop, the SOAP/JMS URI format you must provide in the AquaLogic Service Bus Console is:

jms://host:port/factoryJndiName/destJndiName

However, BEA WebLogic Workshop expects the following format:

jms://host:port/factoryJndiName/destJndiName?URI=/process/myprocess.jpd

To overcome this problem, you must set the URI as a JMS property inside the message flow on the outbound variable ($outbound) before it is sent. For information about setting $outbound, see "Inbound and Outbound Variables" in Message Context in the Using the AquaLogic Service Bus Console.

When using the JMS binding to configure a business service in WebLogic Server 8.1, you must use the following SOAP/JMS URI format in the AquaLogic Service Bus Console:

jms://host:port/factoryJndiName/destJndiName?URI=/contextURI/serviceName

You must set the URI as a JMS property inside the message flow on the outbound variable ($outbound) before a request is sent to the business service.

When using the JMS binding to configure a business service in WebLogic Server 9.x, you must use the following SOAP/JMS URI format in the AquaLogic Service Bus Console:

jms://host:port/contextURI/serviceName?URI=destJndiName

You must configure the business service to use the JNDI name of an existing QueueConnectionFactory in the target WebLogic Server. You must also set a user defined JMS property with the name as URI and the value as /contextURI/serviceName inside the message flow on the outbound variable ($outbound) before a request is sent to the business service.

Naming Guidelines for WebLogic Servers, JMS Servers, and Domains

Unique naming rules apply to all WebLogic Server deployments if more than one domain is involved. Therefore, make sure of the following:

WebLogic Server instances and domain names are unique.
WebLogic JMS server names are uniquely named across domains.
If a JMS file store is being used for persistent messages, the JMS file store name must be unique across domains.

Regarding JMS Server names:

You cannot have duplicate JMS server names within the same domain. If you do, when messages are sent to a destination at a particular JMS server, it is ambiguous as to which server the message should be sent.
If you are using Store and Forward (SAF), having duplicate JMS Server names in different domains does not pose a problem.
In the case of cross-domain communication, having duplicate JMS Server names can be a problem when using the ReplyTo function. For a scenario in which two domains each have a JMS Server with the same name, a ReplyTo message sent from a given domain is returned to the JMS server on the same domain that received the message instead of being returned to the domain that sent the original message.

For more information about configuring and managing WebLogic JMS, see:

Managing Your Applications in Programming WebLogic JMS
Configure JMS Servers in the WebLogic Server Administration Console Online Help

For information about WebLogic Server Domains, see Understanding Domain Configuration.

Specifying the JMS Type for Services

To support interoperability with heterogeneous endpoints, AquaLogic Service Bus allows you to control the content type used, the JMS type used, and the encoding used when configuring message flows. The JMS type can be byte or text. For more information, see "Content Types, JMS Type, and Encoding" in Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.

AquaLogic Service Bus and MQ/JMS Interoperability

For information about AquaLogic Service Bus and MQ/JMS interoperability, see Interoperability with WebSphere MQ.

WSDL-Defined SOAP Fault Messages

When consuming a WSDL that explicitly defines a fault, the WebLogic clientgen tool generates a subclass of java.lang.Exception for the XML fault type. When the WebLogic Server JAX-RPC stack inspects a SOAP response message and determines that the response message contains a SOAP fault, it tries to map the fault to a clientgen-generated exception Java class.

For example, if a WSDL contains the definitions shown in the following listing, the clientgen tool generates a Java class com.bea.test.TheFaultType that extends java.lang.Exception. A JAX-RPC client can catch com.bea.test.TheFaultType when invoking the related method of the service stub.

Listing 3-1 Example WSDL Definitions

<definitions ... xmlns:s0="http://www.bea.com/test/">

...

   <types>

      <xsd:schema targetNamespace="http://www.bea.com/test/">

...

         <xsd:complexType name="theFaultType">

            <xsd:sequence>

               <xsd:element name="ID" type="xsd:int" />

               <xsd:element name="message" type="xsd:string" />

            </xsd:sequence>

         </xsd:complexType>

         <xsd:element name="theFault" type="theFaultType" />

      </xsd:schema>

   </types>

...

   <message name="theFaultMessage">

      <part element="s0:theFaultPart" name="theFault" />

   </message>

...

   <binding ...>

      <operation ...>

         <soap:operation soapAction="..." style="document" />

         <input ...>

...

         </input>

         <output ...>

...

         </output>

         <fault ...>

            <soap:fault name="theFaultPart" use="literal" />

         </fault>

      </operation>

   </binding>

...

</definitions>

The SOAP message must contain a fault of the correct format so that the JAX-RPC stack throws the correct exception. If the fault is constructed from inside a AquaLogic Service Bus message flow, you must:

Replace the node for the $body variable with the following example listing:

Listing 3-2

<soap-env:Body>

      <soap-env:Fault>

         <faultcode xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">soap:Server</faultcode>

         <faultstring>Some literal string</faultstring>

         <detail>

            <test:theFault>

               <test:ID>Any user defined code</e2eb:Id>

               <test:message>A specific literal message</test:message>

            </test:theFault>

         </detail>

      </soap-env:Fault>

</soap-env:Body>

where:

soap-env is the system prefix for the namespace http://schemas.xmlsoap.org/soap/envelope/
test is the prefix for the namespace http://www.bea.com/test/.

If the prefix test is not already known to AquaLogic Service Bus, you must declare it.

Configure a reply action with failure.

For information about configuring Reply Actions in the AquaLogic Service Bus Console, see Proxy Services Actions in Using the AquaLogic Service Bus Console.

The clientgen tool is used to generate the client-side artifacts, such as the JAX-RPC stubs, needed to invoke a Web Service. See Ant Task Reference in Programming Web Services for WebLogic Server.