24 Oracle SOA Suite Transport (SOA-DIRECT)

This chapter provides an overview of the SOA-DIRECT transport and describes how to use and configure it in your services.

Oracle Service Bus provides a SOA-DIRECT transport that lets you invoke Oracle SOA Suite service components, such as BPEL processes, human tasks, rules, and Oracle Mediator components.

Note:

The SOA-DIRECT transport is for communicating with Oracle SOA Suite 11g and later service components. Oracle Service Bus provides a bpel-pm transport to communicate with Oracle SOA Suite 10g Release 3. For information on that transport, see Chapter 34, "Oracle BPEL Process Manager Transport (for use with Oracle SOA Suite 10g only)."

This chapter includes the following sections:

Section 24.1, "About the SOA-DIRECT Transport"
Section 24.2, "Using SOA Suite Services with Oracle Service Bus"
Section 24.3, "Transport Configuration Reference"
Section 24.4, "WS-Addressing Reference"
Section 24.5, "XML Examples"

24.1 About the SOA-DIRECT Transport

The SOA-DIRECT transport provides native connectivity between Oracle Service Bus and Oracle SOA Suite service components. Oracle SOA Suite provides a "direct binding" framework that lets you expose Oracle SOA Suite service components in a composite application, and the Oracle Service Bus SOA-DIRECT transport interacts with those exposed services through the SOA direct binding framework, letting those service components interact in the service bus layer and leverage the capabilities and features of Oracle Service Bus.

For more information on SOA binding components, see "Getting Started with Binding Components" and "Using the Direct Binding Invocation API" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Note:

The SOA-Direct transport supports WSDL type services with SOAP 1.1, SOAP 1.2, or, alternatively, XML bindings. The SOA direct binding framework only exposes direct binding services as WSDL with SOAP 1.1 and SOAP 1.2 bindings, not XML. However, if you want to use an XML binding, you must manually customize the imported SOA service WSDLs for the direct binding services. An XML binding has no effect on the message payload, since messages between the SOA-DIRECT transport and SOA binding components are always abstract (no binding).

The SOA-DIRECT transport supports the following features:

Invocation of any SOA binding component services through Java remote method invocation (RMI)
WS-Addressing, including optional auto-generation of ReplyTo properties for asynchronous callbacks
Identity propagation
Transaction propagation
Attachments
Optimized RMI transport for invoking SOA services
High availability and clustering support
Failover and load balancing (not available for services in the Service Callback role
Connection and application retries on errors

24.1.1 WS-Addressing

The SOA-DIRECT transport uses only WS-Addressing for message correlation in synchronous and asynchronous communications. The transport automatically generates the following WS-Addressing properties in the SOAP header when you configure a callback proxy in the business service configuration:

ReplyTo – For setting the callback address and connection details in asynchronous callbacks.
ReferenceParameters – Contains the callback properties for ReplyTo, including JNDI and connection factory properties, for the following supported WS-Addressing versions:
- http://www.w3.org/2005/08/addressing
- http://schemas.xmlsoap.org/ws/2004/08/addressing
ReferenceProperties – Contains the callback properties for ReplyTo, including JNDI and connection factory properties, for the following supported WS-Addressing version: http://schemas.xmlsoap.org/ws/2003/03/addressing.

For ReplyTo and ReferenceParameters examples, see Section 24.4, "WS-Addressing Reference."

For all other WS-Addressing properties, you must add or transform them in Oracle Service Bus proxy service message flows if they are not available or suitable for pass-through to the SOA-DIRECT business service.

If you use correlation and callback mechanisms other than WS-Addressing, you must transform messages in proxy service pipelines to support WS-Addressing between Oracle Service Bus and SOA framework service components.

For WS-Addressing examples with the SOA-DIRECT transport, see Section 24.4, "WS-Addressing Reference" and Section 24.5, "XML Examples."

24.1.2 Security

The SOA-DIRECT transport supports one-way SSL. To use SSL, enable SSL in the domain, use the secure protocol in the endpoint URI, such as HTTPS, iiops, or t3s, and reference the secure port in the URI. For more information on the SOA-DIRECT URI, see Section 24.3.1, "SOA-DIRECT Endpoint URI."

You can provide identity propagation with the SOA-DIRECT transport by passing the caller's subject through the service or with a service account bound to the service. Because the SOA-DIRECT transport deals with only normalized, abstract messages, the transport does not support WS-Security. For more information on security settings, see Section 24.3.2, "SOA-DIRECT Transport Configuration for Business Services."

24.1.3 Environment Values

The SOA-DIRECT transport stores the following environment values for SOA-DIRECT services:

JNDI Service Account (security category)
Pass Caller's Subject (security category)
Invocation Service account (security category)
Work Manager (environment category)

For information on these values, see Section 24.3.2, "SOA-DIRECT Transport Configuration for Business Services."

24.1.4 Error Handling

The SOA-DIRECT transport recognizes connection and application errors, letting you configure the appropriate retry settings in the transport configuration. The transport throws generic errors for errors that are neither connection nor application related.

24.1.4.1 Connection Errors

The SOA-DIRECT transport raises connection errors in the following situations:

The target service does not exist
A naming exception occurs during the RMI lookup or invocation (with the exception of javax.naming.NamingSecurityException, which is a generic error).
A remote exception occurs during the RMI lookup or invocation.

24.1.4.2 Application Errors

The SOA-DIRECT transport raises application errors when the outbound business service receives a SOAP fault.

You can deselect Retry Application Errors on the service configuration page to prevent retries on application errors—errors that are likely to keep failing despite retries.

24.1.4.3 Generic Errors

The SOA-DIRECT transport raises a generic error in the following situations:

All errors other than connection and application errors.
A javax.naming.NamingSecurityException, which is thrown during the JNDI lookup, is not considered a connection error as are other naming exceptions.

24.2 Using SOA Suite Services with Oracle Service Bus

This section describes synchronous and asynchronous communication patterns between Oracle Service Bus and Oracle SOA Suite composites.

24.2.1 Simple Use Cases – Synchronous

This section describes the simple, most common use cases for communicating natively to and from SOA composites through Oracle Service Bus: synchronous communication.

24.2.1.1 Synchronous Invocation of a SOA Composite

The Oracle Service Bus SOA-DIRECT transport can invoke any component in a SOA composite that is exposed as a direct binding service.

Figure 24-1 illustrates a synchronous communication pattern between a client and an Oracle SOA service component through Oracle Service Bus using a SOA-DIRECT business service and direct binding service.

Figure 24-1 Client Invoking a SOA Binding Service Synchronously

Description of "Figure 24-1 Client Invoking a SOA Binding Service Synchronously"

24.2.1.1.1 Creating and Configuring the Services

Use the following guidelines to invoke an Oracle SOA direct binding service from a client through Oracle Service Bus:

Create a SOA-DIRECT business service in Oracle Service Bus that represents the SOA service component you want to invoke.
- In Oracle Service Bus, create a WSDL resource based on the corresponding Oracle SOA direct binding service WSDL.
  
  You can locate the SOA direct binding service WSDL in Oracle JDeveloper using the SOA Resource Browser, as described in "Developing SOA Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
- Create a new business service.
- Select WSDL Web Service as the Service Type.
- Select the WSDL resource you created, and choose the appropriate port or binding.
  
  Note:
  
  If you select the port, the transport type and URI will be automatically propagated in the next configuration page.
- Select the soa-direct transport in the business service configuration.
- Set the endpoint URI as described in Section 24.3.1, "SOA-DIRECT Endpoint URI."
- Configure the remainder of the business service, described in Section 24.3.2, "SOA-DIRECT Transport Configuration for Business Services."
Create a proxy service in Oracle Service Bus that invokes the business service. Choose the transport type that is used by the client. For proxy configuration details, see Section 4.3, "Proxy Service Configuration" and Chapter 3, "Transport Configuration."

If you are using stateful services to ensure that messages are associated with the correct conversation, see Section 24.2.1.3, "Associating Messages with the Correct Conversation."

24.2.1.2 Synchronous Invocation from a SOA Composite

A SOA composite can invoke any Oracle Service Bus SB WSDL-based proxy service. To invoke an SB proxy service, the SOA service component must use a direct binding reference of Target Type "Oracle Service Bus." (For more information on target types, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.)

Table 24-0 illustrates a synchronous communication pattern between an Oracle SOA service component and an external service through Oracle Service Bus.

Figure 24-2 SOA Binding Service Invoking an External Service Synchronously

Description of "Figure 24-2 SOA Binding Service Invoking an External Service Synchronously"

24.2.1.2.1 Creating and Configuring the Services

Use the following guidelines to invoke an external service from a SOA composite using direct binding references:

Create a business service in Oracle Service Bus that represents the external service you want to invoke. Choose the transport type that is supported by this service. For business service configuration details, see Section 4.2, "Business Service Configuration." and Chapter 3, "Transport Configuration."
Create an SB proxy service in Oracle Service Bus that invokes the business service.
- Create a WSDL resource to be used by the proxy that invokes the business service.
- Create a new proxy service.
- Select WSDL Web Service as the Service Type.
- Select the WSDL for the proxy service, and select the desired port or binding.
- Select the sb transport in the proxy service configuration.
- Configure the remainder of the proxy service. For more information, see Section 4.3, "Proxy Service Configuration" and Chapter 27, "SB Transport."
Note:

Use the SB proxy service effective WSDL and port type to define the direct binding reference that invokes Oracle Service Bus. You can import this WSDL into an Oracle SOA Suite project.

If you are using stateful services, ensure that messages are associated with the correct conversation. See Section 24.2.1.3, "Associating Messages with the Correct Conversation."

24.2.1.3 Associating Messages with the Correct Conversation

When using stateful services, the messages sent synchronously between Oracle Service Bus and Oracle SOA composites are known as a conversation. To ensure that messages are correctly associated with each other as part of a conversation, the Oracle Service Bus SOA-DIRECT transport provides built-in support for WS-Addressing.

For more information on WS-Addressing, see Section 24.4.2, "MessageID / RelatesTo Headers." For an example of conversation ID setting, see Section 24.5.1, "Conversation ID Examples."

24.2.2 Advanced Use Cases – Asynchronous

This section describes asynchronous communications between a SOA composite and Oracle Service Bus using the SOA-DIRECT transport.

Note:

Only the following SOA service components currently support asynchronous conversations using WS-Addressing: BPEL Process, Mediator, and Human Task.

24.2.2.1 Asynchronous Invocation of a SOA Composite

The Oracle Service Bus SOA-DIRECT transport can invoke asynchronous SOA service components that are exposed as direct binding services.

Figure 24-3 illustrates an asynchronous communication pattern between a client and an Oracle SOA composite through Oracle Service Bus using a direct binding service, the SOA-DIRECT transport, and the SB transport.

Figure 24-3 Client Invoking a SOA Binding Service Asynchronously

Description of "Figure 24-3 Client Invoking a SOA Binding Service Asynchronously"

24.2.2.1.1 Creating and Configuring the Services

Use the following guidelines to invoke the SOA direct binding service asynchronously from a client through Oracle Service Bus:

On the inbound client side, create the Oracle Service Bus artifacts to interact with the client: a request proxy service that invokes the outbound SOA-DIRECT business service, and a callback business service that handles the callback to the client. Use the transport type used by the client.
- Request Proxy Service
  
  Configure the proxy service that receives the client request. This proxy service invokes the outbound request SOA-DIRECT business service.
  
  Since the callback is sent to a different connection, Oracle Service Bus must be able to remember the original callback location when calling back the client. When using WS-Addressing, the callback address is sent to the request proxy service in the ReplyTo address header. Before invoking the SOA-DIRECT business service, the request proxy can pass this address as a referenceParameter property inside the ReplyTo header. Following the WS-Addressing specification, the referenceParameter property is inserted in the SOAP header block of the callback. The callback SB proxy can then extract this callback address and set the callback business service URI.
  
  For information on setting a callback address, see Section 24.4.1, "ReplyTo Header" and Section 24.5.2, "Asynchronous Composite to Composite Native Communication Through Oracle Service Bus Example."
- Callback Business Service
  
  Configure the business service you need to handle the callback. This business service is invoked by the outbound callback SB proxy service.
  
  For service and transport configuration guidance, see Section 4.2, "Business Service Configuration" and Chapter 3, "Transport Configuration".
On the Oracle Service Bus outbound side, create the artifacts to interact with the SOA composite: a request SOA-DIRECT business service that makes the request to the Oracle SOA direct binding service exposing the asynchronous service component you want to invoke, and a callback SB proxy service that handles the callback from the direct binding service and invokes the inbound callback business service.
- Request SOA-DIRECT Business Service
  - In Oracle Service Bus, create a WSDL resource based on the corresponding Oracle SOA direct binding service WSDL.
    
    You can locate the SOA direct binding service WSDL in Oracle JDeveloper using the SOA Resource Browser, as described in "Developing SOA Composite Applications with Oracle SOA Suite" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
  - Create a new business service.
  - Select WSDL Web Service as the Service Type. Browse to the WSDL resource you created and select the appropriate port or binding for the direct binding service.
    
    If you select the port, the transport type and URI are automatically propagated in the next configuration page.
  - Select the soa-direct transport in the business service configuration.
  - Set the URI, described in Section 24.3.1, "SOA-DIRECT Endpoint URI."
  - On the transport configuration page, set the Role to Asynchronous Client.
  - Optionally use the Callback Proxy option to select the SB callback proxy service you created.
    
    When you select a callback proxy, the SOA-DIRECT transport automatically generates the WS-Addressing headers to tell the SOA direct binding service that it expects the asynchronous callback response to be sent to the specified callback proxy.
    
    For approaches to setting a callback address if you do not select a callback proxy in the SOA-DIRECT business service, see Section 24.4, "WS-Addressing Reference" and Section 24.5.2, "Asynchronous Composite to Composite Native Communication Through Oracle Service Bus Example."
  - Configure the remainder of the business service. For more information, see Section 24.3, "Transport Configuration Reference" and Section 4.2, "Business Service Configuration."
  - Invoke this business service from the request proxy service.
Callback SB Proxy Service
- Create a new proxy service.
- Select WSDL Web Service as the Service Type.
- Browse to the WSDL corresponding to direct binding service's WSDL, and select the appropriate port or binding.
- Select the sb transport in the proxy service configuration.
- Complete the proxy service configuration. For more information, see Section 4.3, "Proxy Service Configuration" and Chapter 27, "SB Transport."

24.2.2.2 Asynchronous Invocation from a SOA Composite

An asynchronous SOA service component in a SOA composite can invoke external services through Oracle Service Bus. To do so, the SOA service component must use a direct binding reference of Target Type of "Oracle Service Bus." (For more information on target types, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.)

Figure 24-4 illustrates an asynchronous communication pattern between an Oracle SOA service component and an external service through Oracle Service Bus using a direct binding reference, the SB transport, and the SOA-DIRECT transport.

Figure 24-4 SOA Binding Service Invoking an External Service Asynchronously

Description of "Figure 24-4 SOA Binding Service Invoking an External Service Asynchronously"

24.2.2.2.1 Creating and Configuring the Services

Use the following guidelines to invoke an external service asynchronously from an Oracle SOA direct binding reference through Oracle Service Bus.

In Oracle Service Bus, on the inbound side, create the artifacts to interact with the SOA composite: a request SB proxy service that receives the SOA direct binding reference request and a callback SOA-DIRECT business service that handles the callback to the SOA direct binding reference.
- Request SB Proxy Service
  - Create a WSDL resource representing the interface used to interact with the direct binding reference.
  - Create a new proxy service.
  - Select WSDL Web Service as the Service Type.
  - Browse to the WSDL you created and select the appropriate port or binding.
  - Select the sb transport in the proxy service configuration page.
  - Complete proxy service configuration. For more information, see Section 4.3, "Proxy Service Configuration" and Chapter 27, "SB Transport."
    
    Since the callback is sent to a different connection, Oracle Service Bus must be able to "remember" the original callback location when calling back the client. When using WS-Addressing, the callback address is sent to the request proxy service in the ReplyTo address header. Before invoking the external service, the request proxy service passes this address as a referenceParameter property inside the ReplyTo header. Following the WS-Addressing specification, the referenceParameter property is inserted in the SOAP header block of the callback. The callback proxy service can then extract this callback address and set the callback business service URI.
    
    For information on setting a callback address, see Section 24.4.1, "ReplyTo Header" and Section 24.5.2, "Asynchronous Composite to Composite Native Communication Through Oracle Service Bus Example."
- Callback Business Service
  - Create a new business service.
  - Select WSDL Web Service as the Service Type.
  - Browse to the WSDL representing the callback interface with the direct binding reference, and select the appropriate port or binding.
  - Select the soa-direct transport in the business service configuration.
  - Set the service URI to "callback," as described in Section 24.3.1, "SOA-DIRECT Endpoint URI."
    
    In general, the callback URI is dynamically set in the invoking proxy using URI rewriting. However, if the callback address is always known, you can provide the exact callback address instead of "callback."
  - Set the role to Service Callback on the SOA-DIRECT transport configuration page.
  - Configure the remainder of the business service, as described in Section 24.3.2, "SOA-DIRECT Transport Configuration for Business Services" and Section 4.2, "Business Service Configuration."
On the Oracle Service Bus outbound side, create the artifacts to interact with the external service: a request business service that makes the request to the external service and a callback proxy service that handles the callback from this service.
- Request Business Service
  
  Configure the business service to invoke the external service. This business service will be invoked by the request SB proxy service. Choose the transport type that is supported by this service. For business service configuration details, see Section 4.2, "Business Service Configuration" and Chapter 3, "Transport Configuration."
- Callback Proxy Service
  
  Configure the proxy service to pass the callback address to the business service. The callback URI is provided in the request. Use URI rewriting to extract the callback URI and forward it to the SOA-DIRECT business service. Choose the transport type that is supported by this service. For proxy service configuration details, see Section 4.3, "Proxy Service Configuration" and Chapter 3, "Transport Configuration."
  
  For information on setting the callback addresses using WS-Addressing, see Section 24.4, "WS-Addressing Reference."

24.3 Transport Configuration Reference

This section describes the endpoint URL format and configuration options for the SOA-DIRECT transport.

24.3.1 SOA-DIRECT Endpoint URI

Following is the URI pattern for the SOA-DIRECT transport. Optional elements are in brackets [].

callback – This is the URI for SOA-DIRECT business services in the Service Callback role handling the inbound request. The actual URI is specified dynamically at runtime in the proxy service pipeline. However, if the callback address is always known, you can provide the exact callback address.

For all other SOA-DIRECT business service roles:

[protocol://authority]/default/compositeName[!versionNumber[*label]]/serviceName

protocol

Use one of the following RMI / JNDI protocols:
- iiop / iiops – For generic, server-agnostic use.
- t3 / t3s – For use with Oracle WebLogic Server.
- http / https – For tunneling and use with Oracle WebLogic Server.
  
  For HTTP(S) protocols, enable HTTP tunneling on the server. For SSL protocols, enable SSL on the server.
The protocol and authority are optional when the SOA services are co-located on the same server as Oracle Service Bus.

Following are descriptions of the other endpoint URI elements:

authority – The IP address or host name and the port of the SOA server or cluster hosting the SOA service components.

The protocol and authority are optional when the SOA services are co-located on the same server as Oracle Service Bus.
default – This domain name value is always "default."
compositeName – The name of the composite application where the binding component service is defined.
!versionNumber – Optional. The composite application version number. If you do not specify a version, the current version is used.
- *label – Optional, used with !versionNumber; the label hash used in the SOA service WSDL.
serviceName – The name of the SOA binding component service.

While you can specify more than one URI on a service for load balancing and failover, only one URI is allowed for services in the Service Callback role, described in Table 24-1. Therefore, load balancing and failover are not available for services in the Service Callback role.

24.3.1.1 Cluster URI

Following is the format for the endpoint URI in a cluster:

t3://example_managed1:port1,example_managed2:port2/service_path

Where t3://example_managed1:port1,example_managed2:port2 is the JNDI provider URL.

24.3.1.2 URI Examples

Following are URI examples for the SOA-DIRECT transport:

t3s://example:7002/default/compositeApp/1.0/myService

Points to a service deployed on a single node.
/default/compositeApp!1.0/myService

Points to a service co-located on the same server as Oracle Service Bus.
t3://soaserver.example.com:7001/default/VacationRequest!1.0*ec2dd6c5-1667-4885-a634-2364547beb2d/directclient

Points to a service deployed on a single node using a version and hash code. This is the default format in SOA binding component service WSDLs.
t3://example_managed1:8001,example_managed2:8002/default/myComposite/myService

Points to a clustered SOA framework environment identified by "myService." Because no specific version is specified, the most recent version of the service is used.

24.3.2 SOA-DIRECT Transport Configuration for Business Services

Table 24-1 describes the transport-specific configuration options for the SOA-DIRECT transport.

Table 24-1 SOA-DIRECT Transport Configuration

Property	Description
JNDI Service Account	Optional. Specifies the security credentials for the JNDI lookup of the target SOA service. The service account must be static. Click Browse and select a service account. If you do not specify a service account, an anonymous subject is used.
Role	Required. Identifies the communication pattern the service uses. Select one of the following options: Synchronous Client (default) – In this role, because there is no asynchronous callback, the Callback Proxy option is disabled. The WS-Addressing Version option is also disabled. Asynchronous Client – In this role, because asynchronous callback is usually required, you can identify a Callback Proxy, and you must select a WS-Addressing Version. The asynchronous option is enabled only when the WSDL service is of type SOAP. Service Callback – This role is for returning the asynchronous callback to a SOA service after an external service invocation. Load balancing or failover are not available for services in the Service Callback role.
Callback Proxy	Optional. Enabled only for the Asynchronous Client role. This option lets you specify the proxy service that receives callbacks. When you select a callback proxy, if no WS-Addressing is provided by the request or the proxy service pipeline, Oracle Service Bus automatically populates the ReplyTo property in the SOAP header. You must select a WSDL proxy service that uses the SB transport (for RMI), and the callback proxy service must understand WS-Addressing. WS-Addressing properties that are sent in the request or set in the proxy service pipeline are used instead of the callback proxy you set in this option. If you do not specify a Callback Proxy, and the request does not contain ReplyTo properties, you must provide ReplyTo properties in the SOAP header through the proxy service pipeline.
Fault Proxy	This option is not currently supported. You must configure your callback services to handle faults in an asynchronous pattern.
WS-Addressing Version	Required. Enabled only for the Asynchronous Client role. Specify the default WS-Addressing version to use when no WS-Addressing is provided in the request or the proxy service pipeline. WS-Addressing properties that are sent in the request or set in the proxy service pipeline are used instead of the WS-Addressing version you set in this option. For WS-Addressing version mismatches between environments, perform any necessary transformations in the proxy service pipeline. For more information, see Section 24.5.1.4, "Transformation Examples."
Dispatch Policy	Select the instance of Oracle WebLogic Server Work Manager that you want to use for the dispatch policy for this endpoint. The default Work Manager is used if no other Work Manager exists. For information about Work Managers, see: "Using Work Managers to Optimize Scheduled Work" in Oracle Fusion Middleware Configuring Server Environments for Oracle WebLogic Server "Using Work Managers with Oracle Service Bus" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus
Pass Caller's Subject	Optional. Select this option to have Oracle Service Bus pass the authenticated subject from the proxy service when invoking the SOA service. The Invocation Service Account option, an alternative to Pass Caller's Subject, is disabled when you select this option. Note: Make sure that domain trust is enabled between client and target server if they are in different domains. For more information, see "Important Information Regarding Cross-Domain Security Support" in Oracle Fusion Middleware Securing Oracle WebLogic Server.
Invocation Service Account	Optional. Alternative to Pass Caller's Subject, which lets you specify custom security credentials by selecting a service account for RMI invocation. You can specify any type of service account (Pass Through, Static, Mapping). Click Browse and select a service account. If you do not specify a service account, an anonymous subject is used.

24.4 WS-Addressing Reference

This section describes specific WS-Addressing properties that the SOA-DIRECT transport uses to communicate natively with an Oracle SOA composite. This section also describes ways to provide callback addresses in asynchronous communication, as described in Section 24.2.2, "Advanced Use Cases – Asynchronous."

See Section 24.5, "XML Examples" for WS-Addressing examples.

24.4.1 ReplyTo Header

In an asynchronous communication, a service callback is sent on a different connection than the request. As a service developer, you must supply the correct callback address in an asynchronous exchange so that the callback is sent to the correct client. When using the SOA-DIRECT transport with WS-Addressing correlation, the callback address is specified in the "ReplyTo" WS-Addressing header.

24.4.1.1 Calling a SOA Composite Asynchronously with a SOA-DIRECT Business Service

The SOA-DIRECT business service can optionally generate the ReplyTo header. In the business service configuration, if you select a Callback Proxy to handle the callback, the SOA-DIRECT transport sets the correct callback address corresponding to this callback proxy in the ReplyTo header. This header is generated only if the incoming message does not already contain a ReplyTo header.

For more information, see Section 24.2.2.1, "Asynchronous Invocation of a SOA Composite."

24.4.1.2 Calling Back to a SOA Composite Asynchronously with a SOA-DIRECT Business Service

When calling an external service from an Oracle SOA composite through Oracle Service Bus, you must manually set a callback address. To do this, set the callback address as the ReplyTo value in the proxy service that invokes the callback SOA-DIRECT business service.

For more information, see Section 24.2.2.2, "Asynchronous Invocation from a SOA Composite."

24.4.2 MessageID / RelatesTo Headers

MessageID and RelatesTo WS-Addressing headers are used to store the conversation ID in conversations between Oracle Service Bus and Oracle SOA service components, ensuring related messages remain in the same conversation.

Unlike ReplyTo, the SOA-DIRECT transport does not provide built-in support for the MessageID or RelatesTo headers. Instead, you must set the correct values for those headers in the pipeline of the proxy service that invokes a SOA-DIRECT business service.

The following describe when MessageID and RelatesTo headers are used in synchronous and asynchronous conversations:

Synchronous conversation: The MessageID header value determines the conversation ID in the initial request. Then, for subsequent requests within the same conversation, the conversation ID must be provided in the RelatesTo header.
Asynchronous callbacks - The MessageID header value determines the conversation ID in the initial request. Then, for the callback, the conversation ID must be provided in the RelatesTo header.

For more implementation on establishing a conversation ID to make sure messages participate in the correct conversation, see Section 24.2.1.3, "Associating Messages with the Correct Conversation" and the Section 24.5.1, "Conversation ID Examples."

24.5 XML Examples

Following are examples of XML messaging between Oracle Service Bus and Oracle SOA service Components.

24.5.1 Conversation ID Examples

This section provides different examples of establishing a conversation ID among messages in a conversation between Oracle Service Bus and Oracle SOA composites.

In Figure 24-5, a client is synchronously invoking a BPEL Process component in an Oracle SOA composite. The business service (B1) uses the SOA-DIRECT transport to invoke a process. The proxy service (P1) handles any necessary conversation ID mapping. The SOA composite exposes the BPEL Process as a direct binding service.

Figure 24-5 Operations in a Synchronous Exchange Through Oracle Service Bus

Description of "Figure 24-5 Operations in a Synchronous Exchange Through Oracle Service Bus"

24.5.1.1 Port and Message Definitions

The examples in this section use the following port and message definitions defined in the WSDL.

<wsdl:types>
    <xsd:schema
            targetNamespace="http://www.sample.org/spec/samples/types"
            elementFormDefault="qualified">
        <xsd:complexType name="ValueHolder">
            <xsd:all>
                <xsd:any minOccurs="1"/>
            </xsd:all>
        </xsd:complexType>
    </xsd:schema>
</wsdl:types>
<message name="create"/>
<message name="putRequest">
    <part name="key" type="xsd:string"/>
    <part name="value" type="types:ValueHolder"/>
</message>
<message name="putResponse">
    <part name="value" type="types:ValueHolder"/>
</message>
...
<message name="dispose"/>
<portType name="ServiceMap">
    <operation name="create">
        <input message="tns:create"/>
    </operation>
    <operation name="put">
        <input message="tns:putRequest"/>
        <output message="tns:putResponse"/>
    </operation>
    ...
    <operation name="dispose">
        <input message="tns:dispose"/>
    </operation>
</portType>

24.5.1.2 WS-Addressing that Sets the Conversation ID

This example shows how WS-Addressing is used to set the conversation ID among messages in a conversation.

Figure 24-5 shows the communication pattern.

Create Operation

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Put Operation

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:111111111</wsa03:MessageID>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

The <put> operation also has a MessageID, but it is ignored because the RelatesTo has a value that provides the conversation ID.

24.5.1.3 Message Payload Data that Sets the Conversation ID

This example shows how message payload data can be used to set the conversation ID among messages in a conversation.

In these examples, the proxy service maps the ID to the MessageID / RelatesTo SOAP headers.

Figure 24-5 shows the communication pattern.

Create Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <createResponse>
            <mapID>uuid:123456789</mapID>
        </createResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to SOA composite (through a SOA-DIRECT business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Not shown: The ID was generated in the request of the proxy service pipeline and inserted as a <wsa03:MessageID> before invoking the process. On the process side, the Create operation is one-way, so a SOAP response must be created before replying to the client. The response sends back the ID that was generated by the proxy service.

Put Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <put>
            <mapID>uuid:123456789</mapID>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to SOA composite (through a SOA-DIRECT business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Dispose Operation

Client to proxy service

<soap:Envelope>
    <soap:Body>
        <dispose>
            <mapID>uuid:123456789</mapID>
        </dispose>
    </soap:Body>
</soap:Envelope>

Proxy service to SOA composite (through a SOA-DIRECT business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <dispose/>
    </soap:Body>
</soap:Envelope>

24.5.1.4 Transformation Examples

In these examples, the client uses a more recent version of the WS-Addressing spec (wsa04 prefix). The proxy service is responsible for transforming the SOAP headers to use the wsa03 prefix. The proxy service developer configures the transformation.

Figure 24-5 shows communication pattern.

Create Operation

Client to proxy service

<soap:Envelope>
    <soap:Header>
        <wsa04:MessageID>uuid:123456789</wsa04:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Proxy service to SOA composite (through a SOA-DIRECT business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:123456789</wsa03:MessageID>
    </soap:Header>
    <soap:Body>
        <create/>
    </soap:Body>
</soap:Envelope>

Put Operation

Client to proxy service

<soap:Envelope>
    <soap:Header>
        <wsa04:MessageID>uuid:111111111</wsa04:MessageID>
        <wsa04:RelatesTo>uuid:123456789</wsa04:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

Proxy service to SOA composite (through a SOA-DIRECT business service)

<soap:Envelope>
    <soap:Header>
        <wsa03:MessageID>uuid:111111111</wsa03:MessageID>
        <wsa03:RelatesTo>uuid:123456789</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body>
        <put>
            <key>key</key>
            <value>
                <PO/>
            </value>
        </put>
    </soap:Body>
</soap:Envelope>
<soap:Envelope>
    <soap:Body>
        <putResponse>
            <value/>
        </putResponse>
    </soap:Body>
</soap:Envelope>

24.5.2 Asynchronous Composite to Composite Native Communication Through Oracle Service Bus Example

The following example shows the SOAP headers involved in a SOA composite invoking another SOA composite asynchronously through Oracle Service Bus. The first SOA composite uses a BPEL Process exposed as a direct binding reference to invoke Oracle Service Bus. The second SOA composite uses a BPEL process exposed as a direct binding service to receive requests from Oracle Service Bus.

In Figure 24-6, P1 and P2 are proxy services that pass messages (and perform transformations) to B1 and B2 business services, which are required to make calls to SOA composites using the Oracle Service Bus SOA-DIRECT transport.

Figure 24-6 SOA Composite Invoking an SOA Composite Through Oracle Service Bus

Description of "Figure 24-6 SOA Composite Invoking an SOA Composite Through Oracle Service Bus"

Refer to Figure 24-6 for the following SOAP header examples.

24.5.2.1 Port and Message Definitions

<message name="LoanServiceRequestMessage">
    <part name="payload" element="types:loanApplication"/>
</message>
<message name="LoanServiceResultMessage">
    <part name="payload" element="types:loanOffer"/>
</message>
<portType name="LoanService">
    <operation name="initiate">
        <input message="tns:LoanServiceRequestMessage"/>
    </operation>
</portType>
<portType name="LoanServiceCallback">
    <operation name="onResult">
        <input message="tns:LoanServiceResultMessage"/>
    </operation>
</portType>

24.5.2.2 BP1 to P1 – Initiate operation

<soap:Envelope>
    <soap:Header>
        <wsa03:ReplyTo>
            <wsa03:Address>
                 t3://soaserver:8001/default/AmericanLoanClient/LoanserviceRequester
            </wsa03:Address>
        </wsa03:ReplyTo>
        <MessageID>AmericanLoanClient~1.0/60007</MessageID>
    </soap:Header>
    <soap:Body >
        <loanApplication>
            ...
        </loanApplication>
    </soap:Body>
</soap:Envelope>

24.5.2.3 P1/B1 to BP2

<soap:Envelope>
    <soap:Header>
        <wsa03:ReplyTo>
            <wsa03:Address>http://serverB:7001/P2</wsa03:Address>
            <wsa03:referenceParameters>
                <osb:Callback>
                    <osb:Address>
                         t3://soaserver:8001/default/AmericanLoanClient/LoanserviceRequesterRef#LoanserviceRequesterBpel
                    </osb:Address>
                </osb:Callback>
            </wsa03:referenceParameters>
        </wsa03:ReplyTo>
        <MessageID>AmericanLoanClient~1.0/60007</MessageID>
    </soap:Header>
    <soap:Body >
        <loanApplication>
            ...
        </loanApplication>
    </soap:Body>
</soap:Envelope>

The ReplyTo callback address is set by B1, which gets the value from the Callback Proxy field in the SOA-DIRECT transport configuration, as described in Section 24.3.2, "SOA-DIRECT Transport Configuration for Business Services." B1's callback proxy is P2.

You must wrap the original replyTo information and send it as reference properties so that it is echoed back in the onResult callback message (to follow).

Note:

This sample uses osb:Callback and osb:Address for illustration purpose only. There is no standard or Oracle Service Bus standard elements defined for WS-Addressing support.

24.5.2.4 BP2 to P2 – onResult operation

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>AmericanLoanClient~1.0/60007</wsa03:RelatesTo>
        <osb:Callback>
            <osb:Address>
                  t3://soaserver:8001/default/AmericanLoanClient/LoanserviceRequesterRef#LoanserviceRequesterBpel
            </osb:Address>
        </osb:Callback>
    </soap:Header>
    <soap:Body >
        <loanOffer>
            ...
        </loanOffer>
    </soap:Body>
</soap:Envelope>

The reference property osb:Callback is sent back as a SOAP header by the Oracle BPEL Process Manager engine.

24.5.2.5 P2/B2 to BP1 – onResult operation

<soap:Envelope>
    <soap:Header>
        <wsa03:RelatesTo>AmericanLoanClient~1.0/60007</wsa03:RelatesTo>
    </soap:Header>
    <soap:Body >
        <loanOffer>
            ...
        </loanOffer>
    </soap:Body>
</soap:Envelope>

Proxy service P2 removes the temporary osb:Callback header; but prior to deleting this header, the replyTo address value is copied to the $outbound variable so that the SOA-DIRECT transport in business service B2 can send the callback message to the correct SOA service component.