30 JMS Transport

This chapter provides an overview of the JMS transport and describes how to use and configure it in your services. The chapter also describes features and concepts related to interoperability between Oracle Service Bus and WebLogic JMS and between Oracle Service Bus and WebSphere MQ

This chapter includes the following sections:

30.1 Overview of JMS Interoperability

Java API for XML-Remote Procedure Call (JAX-RPC) is considered the core Java API to build and deploy Web services using J2EE. JAX-RPC provides a simple, robust platform for building Web services applications by abstracting the complexity of mapping between XML types and Java types and the lower-level details of handling XML SOAP messages from the developer. JAX-RPC introduces a method call paradigm by providing two programming models:

  • A server-side model for developing Web services endpoints using Java classes or stateless EJB components

  • A client-side model for building Java clients that access Web services as local objects.

JAX-RPC mandates the use of SOAP and interoperability with other Web services built with other technologies. If you already have a stateless session EJB or a Java class that performs your business logic, J2EE lets you expose it as a service in a standard manner using JAX-RPC.

All Oracle Service Bus service types support JMS transport. Proxy services and business services must be configured to use JMS transport as described in the Section 2.3, "Working with Proxy Services"andSection 2.2, "Working with Business Services."

For information about Oracle WebLogic Server JMS, see:

30.2 Asynchronous Request-Response Messaging

Messaging can be categorized as follows:

  • One-way

  • Synchronous request-response

  • Asynchronous request-response

However, messaging over JMS is only one-way or through asynchronous request-response. Asynchronous request-response messaging using JMS is an alternative to messaging using HTTP or HTTP(S).

Using asynchronous request-response messaging has the following advantages:

  • The request thread does not get blocked while waiting for the response. This removes a thread management issue that can occur when numerous blocking request-response invocations are made. However, HTTP and HTTP(S) support a non blocking mode of operation.

  • The messaging is more reliable than HTTP because it can be:

    • Persisted on disk

    • Queued when the service is not available

    • Re-delivered if the server has an error or fails when the message is being processed

If you are using IBM WebSphere MQ, asynchronous request-response messages may be the best approach for interacting with some mainframes. The asynchronous service must echo the correlation ID or the message ID depending on the JMS request-response pattern that you use. The format of either ID used by Oracle Service Bus is compatible with IBM WebSphere MQ and with target services that use MQ native interfaces. For more information, see Section 30.10, "Message ID and Correlation ID Patterns for JMS Request/Response."

Asynchronous request-response messages are handled by the outbound and inbound transports. That is, the message flow, except for the $outbound and $inbound transport specific data, does not distinguish between JMS request-response and HTTP request-response.

Oracle Service Bus supports bridging between synchronous and asynchronous request and response. For example, a proxy service can be invoked using HTTP, and the proxy service routes to a JMS request-response business service. This is called synchronous-to-asynchronous service switching.

30.3 Using SOAP-JMS Transport

You can use JMS for SOAP transport instead of HTTP, as SOAP is transport-agnostic. SOAP JMS transport is necessary especially for enterprise customers. Oracle Service Bus supports SOAP messages with JMS request-response. Oracle Service Bus supports interoperability with Oracle WebLogic Server SOAP-based clients and services.

JMS is also an approach for reliable messaging.

30.3.1 Interoperating with Oracle WebLogic Server

When you use JMS binding to configure a service in Oracle WebLogic Server, use the following SOAP-JMS URI format with Oracle WebLogic Server:

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

When you configure the service in Oracle Service Bus, the URI must have the following format:

jms://host:port/connection_factory/jndi_destination

Both formats use the same jndi_destination. The jndi_destination must be the JNDI name of an existing QueueConnectionFactory in the target Oracle WebLogic Server.

Note:

While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

When you invoke Oracle WebLogic Server services from Oracle Service Bus, you must set the URI as a JMS property with the value as /contextURI/serviceName, inside the message flow on the outbound variable ($outbound) before a request is sent to the business service. Use the Transport Headers action to set this property.

For information about setting $outbound, see "Inbound and Outbound Variables" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

When an Oracle WebLogic Server Web services client invokes an Oracle Service Bus proxy service, the URI property is ignored. However, it can be passed through to an invoked service using the pass through options of the Transport Headers action. For more information, see Section 2.4.32, "Adding and Configuring Transport Headers Actions in Message Flows."

Oracle Service Bus can only invoke Oracle WebLogic request-response services running on version 9.2 or later. However, it can also invoke one-way JMS services.

30.3.1.1 Configuring the Response Queues for Cross-Domain JMS Calls

When you configure the response queue for cross-domain JMS calls, make sure that there is a separate response queue corresponding to each requesting Managed Server.

For example, two Oracle Service Bus clustered domains (domain A and domain B) are communicating with an Oracle WebLogic Server domain that has 2 Managed Servers. If domain A has 3 Managed Servers and domain B has 4 Managed Servers, you need to configure 7 distinct queues to serve as response queues (3 + 4 = 7) on the Oracle WebLogic Server domain for sending responses back to domain A and domain B. These queues could be distributed queues (with members on both the Managed Servers of the Oracle WebLogic Server domain).

Note:

When the JMS requests come from multiple proxy services hosted by different remote domains, you must configure the back-end domain hosting the JMS business service with the separate sets of response queues corresponding to each requesting domain.

30.4 Naming Guidelines for Domains, WebLogic, and JMS Servers

If you are working with more than one domain, make sure that your configuration conforms to the following requirements:

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

Note the following rules for 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, Oracle Service Bus cannot determine to which server the message should be sent.

  • If you are using Store and Forward (SAF), duplicate JMS Server names in different domains do not pose a problem.

  • In the case of cross-domain communication, duplicate JMS server names can be a problem when you use the ReplyTo function. The 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 on how to configure and manage WebLogic JMS:

30.5 Specifying the JMS Type for Services

To support interoperability with heterogeneous endpoints, Oracle Service Bus lets you 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 non-Java-type messages. For more information, see "Content Types, JMS Type, and Encoding" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

30.6 Specifying the JMS Client ID in Proxy Services

The JMS client ID in a proxy service is the jms-client-id descriptor value, which is used to generate subscriber names and the client ID value for the topic's subscribers. When you configure a JMS proxy service with a topic destination, you can specify the JMS client ID to use when generating subscriber names and the subscriber client ID. This makes it easier to identify the subscriber and its corresponding proxy service when monitoring and managing the service and topic at runtime. This is only effective for durable subscriptions.

30.6.1 About the Client ID and Subscriber Name

A subscription for a topic destination can be identified by the client ID and subscriber name. These values are generated for different TopicMessagesDistribution configurations using the following descriptors.

  • jms-client-id: The value configured for the JMS Client ID property on a JMS proxy service targeted to a topic destination.

  • ejb-name: The name of the MDB generated by Oracle Service Bus for the proxy service. This is a unique ID value.

  • DomainName: The name of the Oracle Service Bus domain.

  • ServerName: The name of the runtime Oracle Service Bus server.

  • UniqueKey: The unique key generated by WebLogic Server when the generate-unique-client-id descriptor is set to true. The generate-unique-client-id descriptor is always set to true for MDBs deployed by JMS proxy services.

The following table shows how the subscriber client ID and name are generated for different distribution modes.

Topic Messages Distribution Subscriber Client ID Subscriber Name

One Copy Per Application

jms-client-id

ejb-name

One Copy Per Server

{jms-client-id}_{DomainName}_{ServerName}

ejb-name

Compatibility

{jms-client-id}_{DomainName}_{ServerName}_{UniqueKey}

Same as client ID


Additional descriptors affect the subscriber client ID. The distributed-destination-connection descriptor is always set to local, and the generate-unique-client-id descriptor is always set the true. For more information, see "Topic Subscription Identifiers" in Programming Message-Driven Beans for Oracle WebLogic Server.

30.6.2 Recommended Usage

It is not recommended to use the Topic Messages Distribution mode of Compatibility. Instead, use either One Copy Per Application or One Copy Per Server for better scalability (depending on your requirements). Compatibility mode is provided primarily for backward compatibility, and is typically used for durable subscriptions where cleanup activity might be done on topic subscribers related to a specific proxy service.

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

Example 30-1 Sample WSDL Definitions

<definitions ... xmlns:s0="http://www.oracle.com/test/">
   ...
   <types>
      <xsd:schema targetNamespace="http://www.oracle.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 an Oracle Service Bus message flow, you must:

  1. Replace the node for the $body variable with the following sample SOAP:

    Example 30-2 Sample SOAP

    <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</test: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.oracle.com/test/

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

  2. Configure a reply action with failure.

For information about configuring Reply Actions in the Oracle Service Bus Administration Console, see Section 2.4.22, "Adding and Configuring Reply Actions in Message Flows."

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 Oracle Fusion Middleware WebLogic Web Services Reference for Oracle WebLogic Server.

30.8 Interoperability with WebSphere MQ

Oracle Service Bus connects to WebSphere MQ through the WebSphere MQ JMS interface. That is, Oracle Service Bus is a WebSphere MQ JMS client.

WebSphere MQ can interface with Oracle Service Bus in two ways:

  • Oracle Service Bus acts as the front-end of WebSphere MQ to accept service requests from other applications and converts them to WebSphere MQ requests.

  • WebSphere MQ sends messages to other applications through Oracle Service Bus.

For more information, see Section 33.9.1, "Using the WebSphere MQ JMS Interface."

30.9 Interoperability with Tibco EMS

When using Tibco Enterprise Messaging Service (EMS) as a messaging provider, you must modify setDomainEnv.cmd/sh so that EXT_PRE_CLASSPATH references the Tibco EMS client JARs.

30.10 Message ID and Correlation ID Patterns for JMS Request/Response

JMS is a standard API for accessing enterprise messaging systems. Oracle WebLogic JMS:

  • Enables Java applications sharing a messaging system to exchange messages.

  • Simplifies application development by providing a standard interface for creating, sending, and receiving messages.

For an overview and features of JMS, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

This section describes the Message ID and Correlation ID patterns supported in Oracle Service Bus for JMS request-response and describe how Oracle Service Bus uses these patterns to interoperate with Java API for Remote Procedure Call (JAX-RPC) Web services. Examples are also provided.

The following topics are included:

30.10.1 Overview of JMS Request-Response and Design Patterns

Messaging provides high-speed, asynchronous, program-to-program communication with guaranteed delivery and is often implemented as a layer of software called Message Oriented Middleware (MOM).

In enterprise computing, messaging makes communication between processes reliable, even when the processes and the connection between them are not so reliable. Processes may need to communicate for the following reasons:

  • One process has data that needs to be transmitted to another process.

  • One process needs to remotely invoke a procedure in another process.

Asynchronous request-response messages are the best approach to interacting with some mainframes, if you are using IBM WebSphere MQ.

30.10.1.1 Patterns for Messaging

Messaging patterns describe the format of messages that flow between parts of a system built with a MOM. There are several types of messages as follows:

  • A Command Message enables procedure call semantics to be executed in a messaging system.

  • A Document Message enables a messaging system to transport information, such as the information that should be returned to a sender as a result of a command message.

  • An Event Message uses messaging to perform event notification.

  • A Reply Message handles the semantics of remote procedure call results, that require the ability to handle both successful and unsuccessful outcomes.

  • A Reply Specifier enables a program making a request to identify the channel through which a reply should be sent.

  • A Correlation Identifier enables a requesting program to associate a specific response with its request. When the data to be conveyed spans several messages, a Sequence Identifier enables the receiver to accurately reconstruct the original data.

  • Message Expiration enables a sender to set a deadline by which the message should either be delivered or ignored.

  • Message Throttle enables a receiver to control the rate at which it receives messages.

In the case of Oracle Service Bus, each reply message should contain a unique identifier called the correlation ID, which correlates the request message and its reply.

When the caller creates a request message, it assigns a unique identifier to the request that is different from those for all other currently outstanding requests (for example, requests that do not yet have replies). When the receiver processes the request, it saves the identifier and adds the request's identifier to the reply.

When the caller processes the reply, it uses the request identifier to correlate the request with the reply. This is called a correlation identifier because of the way the caller uses the identifier to correlate each reply with the request.

A correlation ID is usually put in the header of a message. The ID is not a part of the command or data the caller is trying to communicate to the receiver.

The receiver saves the ID from the request and adds it to the reply for the caller's benefit. Since the message body is the content being transmitted between the two systems and the ID is not a part of that, the ID is added to the header.

In the request message, the ID can be stored as a correlation ID property or simply a message ID property. When used as a correlation ID, this can cause confusion about which message is the request and which is the reply. If a request has a message ID but no correlation ID, then a reply has a correlation ID that is the same as the request's message ID.

The correlation ID format used internally by Oracle Service Bus is compatible with WebSphere MQ and works with target services that are using MQ native interfaces.

The outbound transport handles asynchronous request-response messages. That is, the message flow, except for the $outbound transport specific data, does not distinguish between JMS request-response and HTTP request-response.

When you define a JMS request-response business or proxy service, you must first choose a design pattern. To do this, select the Is Response Required option for a JMS proxy service or a Response Queues option for a JMS business service, then select one of the following correlation patterns on the JMS Transport Configuration page:

  • JMS Correlation ID—the default pattern

  • JMS Message ID

Note:

JMS request-response messaging does not have reliable responses, because the mapping of the correlationID to the proxy service is stored in memory. If there is a failure or system restart between sending the request and receiving the response, the response is discarded.

To work around that situation, instead of using JMS request-response, use two JMS one-way proxy services: one for delivering the message and a second for delivering the response.

For information about creating JMS proxy and business services, see Section 2.3, "Working with Proxy Services" and Section 2.2, "Working with Business Services."

The following sections discuss these patterns. To compare the two patterns, see Section 30.10.4, "Comparison of Message ID and Correlation ID Patterns."

30.10.2 JMS Message ID Pattern

When you create a business service using the JMS Message ID pattern, you can configure the responses to go to a single URI, or, for failover support, you can configure a response queue for each request URI on each Managed Server in the Oracle Service Bus cluster. These queues must be collocated with the request queues for the service. The proxy service uses this information to set the JMSReplyTo property when invoking the business service so that the response is processed by the Managed Server that issued the request.

When you define a proxy service using the JMS Message ID pattern, you need not define the ResponseURI because the proxy service replies to the queue specified in the JMSReplyTo property. However, you can enter the JNDI name of the JMS connection factory for the response message.

Note:

By default, the connection factory of the request message is used. This is useful when you use a non-XA connection factory for JMS responses, but have an XA connection factory for the request.

For the deployment descriptors to be set appropriately for XA-capable resources, you must set the XA attribute on the referenced connection factory before creating a proxy service.

The invoked service must copy the message ID from the request (the value of the JMS header field JMSMessageID) to the correlation ID of the response (setting the JMS header field JMSCorrelationID). In addition, the invoked service must reply to the queue specified in the JMSReplyTo header field.

If you choose the JMS Message ID Pattern, the response arrives at the appropriate managed node.

A JMS proxy service using this pattern can be used in a cluster without further configuration. A JMS business service is available in a cluster. However, when a Managed Server is added to the cluster, all the business services become invalid. To correct this, ensure that the number of response queues equals the number of Managed Servers that specify the JMS Message ID correlation pattern in the Oracle Service Bus cluster.

Note:

The JMS Message ID correlation pattern is not supported when a proxy service invokes another proxy service.

30.10.3 JMS Correlation ID Pattern

When you design a business service in Java, make sure that you set the value of JMS Correlation ID on the response to the value of JMS Correlation ID on the request before sending the JMS response to a queue.

You can obtain the JMS Correlation ID when you receive a message using:

String getJMSCorrelationID()

The above method returns correlation ID values as Strings that provide specific message IDs or application-specific values.

To set the JMS Correlation ID when you send a message:

void setJMSCorrelationID(String correlationID) 

30.10.4 Comparison of Message ID and Correlation ID Patterns

The JMS request-response patterns differ in the following ways:

  • The method by which the response is correlated with the request

  • The choice of the response queue

The differences between these two patterns are summarized in Table 30-1.

Table 30-1 Differences Between Message ID and Correlation ID Patterns

JMS Pattern Name Response Queue CorrelationID

Correlation ID Pattern

All responses go to the same fixed queue(s).

The server copies the request Correlation ID to the response Correlation ID.

Message ID Pattern

The responses dynamically go to the queue indicated by the JMSReplyTo property.

The server copies the request Message ID to the response Correlation ID.


When the Correlation ID pattern is used, the service that is invoked replies to the queue that corresponds to the request URI. The response always arrives on the same queue and the client has no control over the queue to which the response arrives. For example, if 10 clients send a message to request URI "A", they all get the response to the queue that corresponds with request URI "A". Therefore, clients must filter the messages in the response queue to select the ones that pertain to them. Filtering criteria are configured in the request message Correlation ID property, and the server is configured to echo this to the response Correlation ID property.

In the case of Message ID pattern, the client's JMSReplyTo property tells the server where the response should be sent. This queue is specific to the client's server and hence responses to different clients will go to different queues. The server sets the JMS Correlation ID of the response to the JMS Message ID of the request.

Correlation by MessageID is commonly used by many IBM MQ applications as well as JMS applications and is the standard method to correlate request and response.

If you have multiple Oracle WebLogic client domains invoking a target Oracle WebLogic domain using JMS request-response with the Message ID pattern, you can set up both the request and response queues as SAF queues. However, this is not possible with the Correlation ID pattern that uses a single queue for all the responses for a given request URI.

The Correlation ID pattern has two major advantages:

  • The response queue configuration is simple and it need not change every time a new Managed Server is added to the cluster.

  • Correlation ID can also be used in cases where a proxy service in the domain needs to invoke another proxy service in the same domain.

30.10.5 Interoperating with JAX-RPC Over JMS

The Oracle Service Bus development environment lets you create JAX-RPC Web services that use the JMS transport, in addition to HTTP-HTTPS. These JMS transport JAX-RPC Web services use a JMS queue as the mechanism for retrieving and returning values associated with operations. You can use the JMS Message ID pattern to invoke a JMS transport JAX-RPC Web service.

You can also invoke a JMS Request-Response Oracle Service Bus proxy service from a JAX-RPC static stub, which the Oracle WebLogic clientgen Ant task generates.

This section includes the following topics:

30.10.5.1 Invoking a JAX-RPC Web Service Using the JMS Message ID Pattern

To invoke a JMS transport JAX-RPC Web service using the JMS Message ID pattern, complete the following steps:

  1. Create a JMS Request-Response Oracle Service Bus business service that uses the JMS Message ID pattern to invoke the JMS transport JAX-RPC Web service. For more information, see Section 3.1.15, "JMS Transport Configuration Page (Business Services)."

    This business service uses JMS transport. The JMS queue JNDI name portion of the end point URI must be the same as the queue attribute specified in the @WLJmsTransport annotation of the JMS transport JAX-RPC Web service. For example:

    jms://localhost:7001/AJMSConnectionFactoryJNDIName/JmsTransportServiceRequestQueue
    

    The JNDI name of the JMS queue (or queues) assigned to the Destination field, in the Target - Destinations area, must be associated with a JMS server targeted at the Oracle WebLogic Server name that is displayed in the Target field.

    Note:

    While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

  2. Create an Oracle Service Bus proxy service that contains a Routing (or Service Callout) action to the JMS Request/Response business service that you created in step 1.

    The Request Actions area of the Routing action must contain a Set Transport Headers for the Outbound Request action. When you configure the Transport Headers action, you must add two JMS headers for the Outbound Request action. For detailed instructions about how to configure a Transport Headers action, see Section 2.4.32, "Adding and Configuring Transport Headers Actions in Message Flows."

    In brief:

    1. Configure a Transport Headers Action by selecting Other in the Add Header field and entering a URI in the field provided.

    2. Select Set Header to <Expression> and create the expression by entering a concatenation of the values specified for the contextPath and serviceUri attributes (in the @WLJmsTransport annotation of the JMS transport JAX-RPC Web Service), preceded by a forward-slash. For example, you have the following @WLJmsTransport annotation:

      @WLJmsTransport(
      contextPath="transports",
      serviceUri="JmsTransportService",
      portName="JmsTransportPort",
      queue="JmsTransportServiceRequestQueue"
      )
      

      You would enter the following expression in the XQuery Text input area when you configure the Transport Headers:

      /transports/JmsTransportService
      
    3. To specify the second JMS Header, select Other in the Add Header field again, and enter _wls_mimehdrContent_Type in the associated field.

    4. Select Set Header to <Expression> and enter text/xml; charset=UTF-8 in the XQuery Text input area.

30.10.5.2 Invoking a JMS Request-Response Proxy Service from a JAX-RPC Client

For a scenario in which a JAX-RPC Oracle WebLogic Server client invokes a proxy service, you must set the _wls_mimehdrContent_Type JMS header for the proxy service's inbound response.

You must specify the header when you issue the response to the incoming JMS Message ID Pattern request.

For example, for the scenario in which you have a JAX-RPC client calling an Oracle Service Bus proxy service, which subsequently calls an Oracle WebLogic Server Web service, the route node configuration is as follows:

For the Request Pipeline 

  1. Set the transport header for Web service context 'URI' (for example: interop/AllocJmsDocLit).

  2. Set the transport header for _wls_mimehdrContent_Type with text/xml; charset=UTF-8.

  3. Select Outbound request from the Set Transport headers menu items.

  4. Enable Pass all Headers through Pipeline.

For the Response Pipeline 

  1. Add an empty transport header and select Inbound response from the Set Transport headers menu.

  2. Enable Pass all Headers through Pipeline.

    Note:

    For detailed instructions about how to configure a Transport Headers action, see Section 2.4.32, "Adding and Configuring Transport Headers Actions in Message Flows."

30.10.6 JMS Message ID Pattern Examples

The following examples describe the different methods by which the JMS Message ID pattern can be used.

30.10.6.1 Example 1: An MQ Service Uses a JMS Message ID to Correlate the Request-Response Message

In Figure 30-1, the server that hosts the MQ service in the request-response communication echoes the request message ID to the response correlation ID, and sends the response to the replyTo queue. The response travels back and is correlated using the JMS MessageID. The Oracle Service Bus replyTo destination is set, one per Oracle Service Bus node in a cluster, when the business service is configured. A JMS or MQ native client can also invoke a JMS request-reply proxy service using the JMS Message ID pattern. The client needs to set the replyTo property to the queue where it expects the response.

The key to supporting this use case is that JMS Message ID is expected to correlate the request-response message. You also need to create as many MQ series outbound response queues as there are cluster servers.

Figure 30-1 MQ Service Uses a JMS Message ID to Correlate the Request/Response Message

Description of Figure 30-1 follows
Description of "Figure 30-1 MQ Service Uses a JMS Message ID to Correlate the Request/Response Message"

30.10.6.2 Example 2: A JAX-RPC Client with Oracle Service Bus Proxy Service

Figure 30-2 represents a JAX-RPC client sending a message to an Oracle Service Bus proxy service, that is, the JAX-RPC inbound case. The JAX-RPC stack employs a temporary queue to receive the response. The Oracle Service Bus JMS transport honors this temporary queue during runtime.

Figure 30-2 JAX-RPC Client with Oracle Service Bus Proxy Service

Description of Figure 30-2 follows
Description of "Figure 30-2 JAX-RPC Client with Oracle Service Bus Proxy Service"

30.10.6.3 Example 3: Oracle Service Bus as a Client of an Oracle WebLogic Server JAX-RPC Request/Response Service

Figure 30-3 represents the JAX-RPC outbound case or the interoperability of an Oracle WebLogic Server JAX-RPC request/response service with an Oracle Service Bus proxy service.

Figure 30-3 Oracle Service Bus as a Client of an Oracle WebLogic Server JAX-RPC Request/Response Service

Description of Figure 30-3 follows
Description of "Figure 30-3 Oracle Service Bus as a Client of an Oracle WebLogic Server JAX-RPC Request/Response Service"

Note:

When a proxy service in one Oracle WebLogic Server domain needs to send a message to a proxy service in a second domain, the message must first be routed to a pass-through business service in domain 1. JMS Store and Forward between domain 1 and domain 2 forwards the inbound request message to the proxy service in domain 2. When you use JMS request/response, you can choose to forward the inbound response message from domain 2 to domain 1 using JMS Store and Forward as well. In the latter case, exported inbound request and imported inbound response queues must be configured in domain 2 for the proxy service in domain 2. Pay close attention to the JMS Store and Forward configuration.

30.11 Using the JMS Transport

You can select JMS as the transport protocol for proxy and business services of any service type (except Transport Typed Service type for business service). The proxy services and business services can be configured to use the JMS transport as described in:

For more information, see Section 2.2, "Working with Business Services" and Section 2.3, "Working with Proxy Services." For information about error handling for business services, see Section 30.11.6, "Error Handling."

When you configure a proxy service, you can use a Transport Header action to set the header values in messages. For more information, see Section 30.11.3, "Transport Headers."

For information about interoperability of Oracle Service Bus with WebSphere MQ, see Chapter 33, "MQ Transport."

In Oracle Service Bus, you can use the default dispatch policy when you configure a service or, optionally, configure custom work managers in WLS.

30.11.1 Security

The JMS transport does not support two-way SSL.

30.11.2 Configuring Proxy Services using JMS Transport Protocol

You can select the JMS transport protocol when you configure any type of proxy service and the endpoint URI is of the form:

jms://<host:port[,host:port]*/connection_factory/jndi_destination>

where

  • host is the name of the system that hosts the service.

  • port is the port number at which the connection is made.

  • [,host:port]* indicates that you can configure multiple hosts with corresponding ports.

  • connection_factory: The name of the JNDI Connection Factory. For more information on how to define a connection factory queue, see "Configure resources for JMS system modules" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

  • jndi_destination: The name of the JNDI destination.

To target a JMS destination to multiple servers, use the following format of the URI: jms://host1:port,host2:port/connection_factory/jndi_destination

where connection_factory is the name of the connection factory queue. For more information on how to define a connection factory queue, see "Configure resources for JMS system modules" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

Note:

While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

To configure a proxy service using JMS transport protocol, see Section 3.1.16, "JMS Transport Configuration Page (Proxy Services)."

30.11.3 Transport Headers

The various headers related to the JMS transport are listed in Table 30-2. All the headers except the Unit of Order header are common to both outbound requests and inbound response.

Table 30-2 JMS Transport Headers

Header Description

JMSMessageID

The JMSMessageID header field contains a value that uniquely identifies the message sent by a provider.

JMSDeliveryMode

The JMSDeliveryMode header field contains the delivery mode specified when the message was sent.

JMSExpiration

This header contains the expiration time of the message that is calculated as the sum of the time-to-live value specified on the send method and the current GMT value.

JMSPriority

The JMSPriority header field contains the priority of the message.

When a message is sent, this field is ignored. After the send operation is complete, the field holds the value that is specified by the method sending the message.

JMSType

The JMSType header field contains the message type identifier that is specified by a client when a message is sent.

JMSCorrelation ID

This is used to link one message with another. For example to link a request message with a response message.

JMSXAppID

This is one of the JMS defined properties that specifies the identity of the application that sends the message. This is set by the JMS provider

JMSXGroupID

This one of the properties defined by JMS that specifies the group id of the message group to which the message belongs. This is set by the client

JMSXGroupSeq

This one of the properties defined by JMS that specifies the sequence of the message inside the message group.

JMS_IBM_Format

This contains the nature of the application data. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_format.html.

JMS_IBM_Report_Exception

Request exception reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/topic/com.ibm.websphere.xms.602.doc/props/prp_jms_ibm_rep_exprn.html.

JMS_IBM_Report_Expiration

Request expiration reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r1mx/index.jsp?topic=/com.ibm.websphere.xms.610.doc/props/prp_jms_ibm_rep_exprn.html.

JMS_IBM_Report_COA

Request a confirm on arrival reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_rep_coa.html.

JMS_IBM_Report_COD

Request a confirm on delivery reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r1mx/topic/com.ibm.websphere.xms.612.doc/props/prp_jms_ibm_rep_cod.html.

JMS_IBM_Report_PAN

Request a positive action notification reports. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_rep_pan.html.

JMS_IBM_Report_NAN

Request a positive action notification reports. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_rep_nan.html.

JMS_IBM_Report_Pass_Msg_ID

Request that the message identifier of any report or reply message is the same as that of the original message. For more Information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_rep_pmid.html.

JMS_IBM_Report_Pass_Correl_ID

Request that the correlation identifier of any report or reply message is the same as that of the original message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/topic/com.ibm.websphere.xms.doc/props/prp_jms_ibm_rep_pcid.html.

JMS_IBM_Report_Discard_Msg

Request that the message is discarded if it cannot be delivered to its intended destination. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/topic/com.ibm.websphere.xms.602.doc/props/prp_jms_ibm_rep_dism.html.

JMS_IBM_MsgType

The type of a message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_msgtype.html.

JMS_IBM_Feedback

This indicates the nature of a report message. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_feedback.html.

JMS_IBM_Last_Msg_In_Group

Indicates whether the message is the last message in a message group. For more information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.websphere.xms.doc/props/prp_jms_ibm_last_mig.html.

JMS_BEA_UnitOfOrder

This header is valid for the request and response.


30.11.3.1 Configuring Transport Headers

You can configure the transport headers for both inbound and outbound requests in the Message Flow. For information about the transport headers related to the JMS transport, see Section 30.11.3, "Transport Headers."

In the pipeline, use a Transport Header action to set the header values in messages. For information about adding transport header actions, see "Adding Transport Header Actions" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

Note:

For information about the limitations for JMS transport headers, see "Understanding How the Runtime Uses the Transport Settings in the Test Console" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus and "Limitations to Transport Header Values You Specify in Transport Header Actions" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

30.11.4 Sending and Receiving Java Objects in Messages

You can directly send Java Objects using the JMS transport. To enable Java Object support in the request or response, create a proxy and/or business service of type Messaging Service, and select Java on the Messaging page for the request and/or response, depending on whether you are sending or receiving the Java Objects through Oracle Service Bus.

Dequeuing a Java object message from the JMS destination involves de-serializing the Java object. For this to work, you must package the Java classes for the Java objects that are to be dequeued into a JAR file and import the JAR into your Oracle Service Bus project. Then, in the JMS transport-specific configuration page for a service, select the JAR in the Client Jar field. The Client Jar field is available in JMS proxy services when you select Java as the message type for the request, and in business services when you select Java as the message type for the response. For more information, see Section 4.2, "Business Service Configuration" and Section 4.3, "Proxy Service Configuration."

Java Objects in Oracle Service Bus are stored in the pipeline object repository and referenced in the SOAP body by a <java-content ref="jcid" /> element and attribute, where jcid is the key to the object in the object repository. If a Java Object is null, the object is represented in the pipeline as ref="jcid:null".

Only one Java Object is allowed in each message.

For Java-type message types, Oracle Service Bus does not support large messages (content streaming) or testing Java-type services in the Test Console.

30.11.5 Configuring Business Services using JMS Transport Protocol

You can select the JMS transport protocol when you configure any type of business service and the endpoint URI is of the form:

jms://<host:port[,host:port]*/connection_factory/jndi_destination >

where

  • host is the name of the system that hosts the service.

  • port is the port number at which the connection is made.

  • [,host:port]* indicates that you can configure multiple hosts with corresponding ports.

  • connection_factory: The name of the JNDI Connection Factory. For more information on how to define a connection factory queue, see "Configure resources for JMS system modules" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

  • jndi_destination: is the name of the JNDI destination.

To target a target a JMS destination to multiple servers, use the following format of the URI: jms://host1:port,host2:port/connection_factory/jndi_destination

where connection_factory is name of the connection factory queue. For more information on how to define a connection factory queue, see "Configure resources for JMS system modules" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

Note:

While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help.

When you register a JMS business service, you must manually edit the URI from the WSDL file when adding it to the service definition. The URI format is as follows:

jms://<host>:<port>/connection_factory/jndi_destination

To configure a business service using the JMS transport protocol, see Section 3.1.15, "JMS Transport Configuration Page (Business Services)."

Note:

To configure a JMS request-response application with response correlation by JMS ID for a business service, you must:

  • Create UDQs and local queues targeted to one chosen JMS server.

  • Disable the default targeting for the UDQs that deploys the UDQ on the cluster and creates the member queues on all JMS.

30.11.6 Error Handling

You can configure JMS-transport business services to handle application and communications errors as follows:

  • Application Errors

    You can specify whether or not to retry business service endpoint URIs when application errors occur. For more information, see Retry Application Errors option in Section 4.2.4, "Business Service Transport Configuration Page."

    An application error occurs when for a JMS business service configured with request/response, the System.getProperty("com.bea.wli.sb.transports.jms.ErrorPropertyName", "SERVER_ERROR") property is true in the response message. In this scenario, the JMS transport provider calls the error method with the TRANSPORT_ERROR_APPLICATION error code.

  • Communication Errors

    You can configure business service URIs to be taken offline when such communication errors occur. When you configure the operational settings for the business service, you can enable the business service endpoint URIs to be taken offline after the specified retry interval. For more information, see "Configuring Operational Settings for Business Services" and "Viewing Business Services Endpoint URIs Metrics" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus.

    Connection errors occur when any JMS exceptions or naming exceptions occur during any of the following activities:

    • Looking up a JMS connection factory.

    • Creating a JMS connection from a JMS connection factory.

    • Creating a JMS session using a connection object.

    • Looking up of a JMS destination.

    • Creating a sender from the session object.

    • Sending a JMS message using the sender and destination object.

  • Pipeline Exceptions with Java Objects

    After an exception occurs in a JMS proxy service, such as while routing a Java Object message to a business service or to a Java Callout, the message payload must be properly formed so that the proxy service can access the exception instance and return it to the calling client. Make sure the payload conforms to the following format:

    <soap:Body xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <ctx:java-content ref="key1" 
        xmlns:ctx="http://www.bea.com/wli/sb/context" />
    </soap:Body>
    

    where key1 is the key to the Java Object in the object repository. If the payload is not in this format, the pipeline passes a null payload to the inbound JMS transport.

    Using an Error Handler

    You can catch pipeline errors involving Java Objects using an error handler. The $fault variable in the error handler contains the reference to the exception instance ("java-exception" element).

    In situations where the $fault variable does not contain a reference to the exception instance, you can use a Java Callout within the error handler that uses the available $fault information to generate an exception instance in the previously described $body payload format. You must use a Reply with Failure action so that the $body is made available as the payload to the inbound JMS transport.