Oracle SOA Suite
soa, esb, All
Architect: SOA

Oracle Service Bus Federation with JMS Store-and-Forward and Dynamic Routing in SOA

by Irene Rusman

Published June 2008

This article describes the architecture, design, and configuration of the federation of Oracle Service Buses (formerly BEA AquaLogic Service Buses). The federation is formed by Oracle Service Bus (OSB) clustered domains linked by a messaging Store-and-Forward (SAF) system. In particular, the article looks at an architecture in which two peripheral clustered domains initiate request-response communication with the a third, central, domain. The peripheral domains use SAF to transmit the requests. The central domain uses SAF to transmit responses back to the peripheral domains.

In the article you'll learn how to configure the Oracle Service Bus domains and also get an overview of some peripheral but pertinent issues such as dynamic routing and response correlation within the federated architecture.


Oracle Service Bus JMS is an enterprise-class messaging system that supports the Java Message Service (JMS) specification JMS 1.1, and also provides numerous extensions to the standard JMS APIs. It is tightly integrated into the Oracle WebLogic Server platform, so you can build secure Java EE applications that can be monitored and administered through the Oracle Service Bus console.

In addition to fully supporting extended architecture (XA) transactions, Oracle Service Bus JMS features high availability through its clustering and server migration features. The Store-and-Forward feature allows storing the messages that could not be delivered until the target destination, perhaps residing on the remote host, becomes available. Out of the box, SAF is configured with default values, each of which can be tuned to satisfy the needs of the concrete application.

There are three common deployment topologies:

  • Distributed Hubs - distributed OSB domains are responsible for routing to each other, with no central coordinator. Divisional hubs service application domains for the respective divisions.
  • Enterprise Hub - a centralized enterprise OSB domain serving as a central coordinator, or enterprise service bus, to divisional or departmental OSB domains. Divisional hubs, in turn, service application domains for the respective divisions.
  • Composite Model - a combination of both the Enterprise and Distributed scenarios. In this case, Distributed OSB domains can still route to each other, such as when there is a high level of services interactions. An enterprise OSB domain can support a newly acquired corporation, connecting the federation to the external applications.

As a scenario, imagine a corporation deploying Oracle Service Bus Enterprise Hub: two peripheral domains connected to a central one. This scenario is depicted in the "Deployment Topology" section of the architecture overview.

Next, I'll describe the deployment architecture of the enterprise hub that enables cross-domain messaging.

Deployment Architecture and Set Up

The peripheral domains receive requests from the JMS clients, process them using proxy services, and route them to the local business service. This local business service is a mere shell. It's defined to enable storage of the outgoing request messages and forward them to the remote central hub.

The central hub processes the incoming messages using its proxy service and routes them to the local backend business service. When a business service sends the response message, it arrives first at the local proxy service. This local proxy service then stores the outgoing response messages and forwards them to the remote peripheral domains, ultimately to be delivered to the JMS clients.

At a minimum, you would need to configure three clustered domains. The federation would have two peripheral domains (Domain 1 and Domain 2 in Figure 1 below) through which clients send initial requests to the central domain. The central domain (Domain 3) receives the requests and sends the responses back to the clients through each of two peripheral domains. The central domain hosts the central proxy and backend business services.

Figure 1 depicts an example of the enterprise hub architecture. It shows three clustered domains, with proxy and business services configured on each of them, JMS destinations, and the flow of request and response messages.

enterprise hub architecture
Figure 1. Configuration of OSB to OSB via SAF with two Peripheral Proxy Service Domains sending requests to the Central Domain hosting the Backend Business Service

For simplicity, assume that each domain consists of an admin server and a cluster of two managed servers.

To describe the set-up, let's introduce names. Two peripheral domains are osb1 and osb2. The central domain is OSB3. The cluster servers will be called:

  • Domain osb1 - osb1Slave0, osb1Slave1
  • Domain osb2 - osb2Slave0, osb2Slave1
  • Domain osb3 - osb3Slave0, osb3Slave1
Using this architecture, let's look at the scenario that we are aiming for in a little more detail:
  • The first JMS client sends requests to request-response JMS Proxy Services in osb1. The second JMS client sends requests to request-response JMS Proxy Services in osb2.
  • To enable correct distribution of the responses, the requests contain a "reply-to" property that is read by the Oracle Service Bus at run time.
  • Requests are routed to the local request-response JMS Business Services within their own domains osb1 and osb2.
  • Requests are forwarded via SAF to the request-response JMS Proxy Services in osb3.
  • Requests are routed to a backend service configured as request-response JMS Business Services in osb3.
  • The backend application sets a response correlation ID to the request message ID, to correlate the response message by request message ID.
  • The backend application reads the "reply-to" property of the request to identify the response queue.
  • Responses are put in the response queues of the backend Business Service.
  • Responses are sent from the response queues of the backend Business Service to the response queues of the JMS Proxy Services in osb3.
  • Responses are forwarded via SAF to the response queues of the Business Services in osb1 and osb2.
  • Responses are further sent to response Uniform Distributed Queues (UDQ) of the Proxy Services in osb1 and osb2.
  • If the clients correlate by message ID and the inbound response JMS correlation ID matches inbound request JMS message ID, the clients receive the responses (Each time the JMS server produces the message, it assigns to it a message ID)
  • .
The important thing to remember here is that the Oracle Service bus is designed by contract. And the user has to fulfill his or her part of the contract.
  • The backend user application in the central domain osb3 has to read the "reply-to" property from the message header and send the response message to that destination.
  • The user has to set correlation by message ID on the proxy service in the central domain osb3. Only then will the response destinations be set dynamically based on the "reply-to" and the responses forwarded to the correct peripheral domains.
The described central hub architecture is scalable. There could be more than two peripheral domains. With each additional peripheral domain, the number of the inbound response queues in the central domain will grow to serve the added peripheral domain.

The client is free to send the request through any of the peripheral domains to request the service in the central domain. Therefore, each of the peripheral domains can be taken offline without affecting the client's ability to reach the service in the central domain.

Having the backend application in the central domain promotes reuse of the centralized service. The clients have the benefit of using the peripheral domains for local services and the central domain for the centralized ones. Organization of the OSB domains in the Enterprise Hub therefore promotes service usage optimization.

The rest of this article describes how to configure such an Enterprise Hub.


In the following sections you'll learn how to configure the domains comprising the Enterprise Hub.

SAF Configuration

Start with the "Configure JMS SAF" chapter of the WebLogic Server documentation. There you'll find detailed instructions on SAF administration and configuration. (Note: This article is for advanced users who already have experience with SAF. I'll outline only specifics of the SAF configuration for the Enterprise Hub.)

Each domain will have an SAF agent deployed on the cluster. The proxy service in the central domain osb3 will have the exported physical uniform distributed queue (UDQ) for requests:

Business services in peripheral domains aslb1 and osb2 will have corresponding imported request UDQs:
You need to specify local response queues (or, UDQs per each managed server, if needed) for the business service when using a JMS message ID correlation pattern, as explained in Understanding Message ID and Correlation ID Patterns for JMS Request/Response. Therefore, the proxy service in domains osb1 and osb2 will have local exported response queues.


The proxy service in the central domain osb3 will have corresponding imported local response queues. For forwarding to osb1:

For forwarding to osb2:
An important element of the peripheral osb1 and osb2 SAF configuration is the <reply-to-saf-remote-context-name> parameter. The SAF system reads the value of this parameter to define the response destination in the central domain before it is forwarded to the peripheral domain. <reply-to-saf-remote-context-name> should be a fully qualified name consisting of a JMS system module name and the name of the remote context in the central domain. For example:
You set <reply-to-saf-remote-context-name> among other imported destination parameters using the WebLogic admin console as described in the "Configure JMS SAF" chapter of the WebLogic Server documentation.

Oracle Service Bus Pipeline Configuration

Pipeline configuration particularities for SOAP messages over JMS

The WebLogic JAX-RPC Web services engine code has the following algorithm for correlating response messages: if the JMS correlation ID is present on a request message, the JAX-RPC Web services engine will set the same JMS correlation ID on the response message; if no correlation ID is set on the request, then the response correlation ID is set to the request message ID.

For a federated architecture, we need to correlate by message ID. Therefore, we need to ensure that the backend application receives the request message with no JMS correlation ID set. Since both inbound and outbound transports are JMS, you'll provide WebLogic JAX-RPC Web services engine code with required headers by explicitly passing through transport headers of the outbound request message using the Transport Headers action in the Route node.

To exclude the JMS correlation ID from the set of passed headers, delete the JMS correlation ID using another Transport Headers action. This will ensure that the backend code of the JAX-RPC Web services engine will be correlating responses by JMS Message ID.

Using dynamic routing of messages to choose the remote domain

If static configuration of the proxy and business service end points is not sufficient for the use case at hand, then you can route the message based on its headers by reading them at run time. To accomplish that, you configure the Dynamic Routing action (or the Dynamic Publishing action, if no response is expected).

When you configure Dynamic Routing, you must specify the service. If it is a plain JMS service, you specify the full path to it. If the service is WSDL based, you choose it from WSDL. Specifying an operation is optional. Dynamic Routing and Dynamic Publishing allow dynamic service selection, based on message content or headers, with the ability to transform messages based on the target service.

Below are basic examples showing that you can provide the name of the service directly or using XQuery:

   <ctx:service isProxy="false">soapjms/JMSTransportService-BS</ctx:service>

   <ctx:service isProxy="false">{$header/service[0]/text() }</ctx:service>
You can also create an XQuery for Dynamic Routing as a resource and specify the name of the resource in the configuration. This route instruction will match the service and the operation, if provided, in the business service definition and invoke that service (operation).

Dynamic Routing is a powerful feature. Applying Dynamic Routing in the distributed domain environment of the OSB federation enables sending messages to any remote domain. Dynamic Routing is a computation of the message destination performed in a Route node at run-time. The result of the computation overrides the predefined target service and, optionally, if specified, the operation.

The best way to organize Dynamic Routing is to create a Routing Table. The Routing Table is simply an XML file registered as an XQuery resource, for example:

You can then use the Assign action of the messaging processing to get the physical destination by passing the logical one:
<ctx: route>
    <ctx: service>
    </ctx: service>
</ctx: route>
The $logicalidentifier will be the actual XPath to extract the logical identifier from the message. If the message contains the logical identifier in its body, the XPath expression will start with the $body.

Configuration of OSB for Dynamic Routing is described in the section "Using Dynamic Routing" of Modeling Message Flow in OSB.

Setting routing attributes with routing options

The Routing Options action is for setting various properties in the outbound Message Context variable. These properties include Quality-of-Service, URI, and Mode, which affect the behavior of Publish and Route actions. Although these elements can be set using Assign, Insert, Replace, and Delete, using these actions requires some knowledge of XPath and/or XQuery, as well as knowledge about the XML structure of the outbound context variable.

The goal of the Routing Options action is to make it easier for the user to set these properties. An additional goal is performance, as the primary representation of the inbound and outbound context variables starting with AquaLogic Service Bus 2.5 is a POJO (Plain Old Java Object). This action allows for direct POJO manipulation rather than having to first materialize an XML representation that the more general transformations actions require.

The set of properties that can be manipulated with the Routing Options action is:

  • URI - specifies where the message should be sent
  • Mode - specifies if the communication pattern is request-only or request-response
  • Quality-of-service - specifies if the quality-of-service is best-effort or exactly-once
  • Retry-count - specifies the maximum number of retries that the transport layer should attempt in the face of transport failures
  • Retry-interval - specifies the wait time in milliseconds between retry attempts
Note: When executing the Routing Options action, the context variable outbound is retrieved from the Message Context. If the variable has not yet been defined, an error will be raised. Otherwise, the action will proceed to set those elements in outbound as specified in the action's configuration.


The goal of this article is to show that Oracle Service Bus is designed with flexibility to form federations. We want to encourage IT departments to take advantage of the network of Service Buses at the onset of the deployments. That would be the right strategic approach in the anticipation of the future growth of the IT infrastructure.

The configuration details equip advanced users with the confidence that the network of the Service Buses is a real deal. It takes out guesswork and enables faster proliferation of the best practices.

Irene Rusman is a Senior Software Engineer with Oracle. She works on Oracle Service Bus system integration.