36 Using the SOA-DIRECT Transport

This chapter provides an overview of the SOA-DIRECT transport and describes how to use and configure it in your services. The SOA-DIRECT transport 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. Service Bus also provides a bpel-10g transport to communicate with Oracle SOA Suite 10g Release 3. For information on that transport, see Using the Oracle BPEL Process Manager Transport .

This chapter includes the following sections:

• Introduction to the SOA-DIRECT Transport

• Using SOA Suite Services with Service Bus

• SOA-DIRECT Transport Configuration Reference

• WS-Addressing Reference

• XML Messaging Examples

36.1 Introduction to the SOA-DIRECT Transport

The SOA-DIRECT transport provides native connectivity between 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. The 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 Service Bus.

For more information on SOA binding components, see "Getting Started with Binding Components" and "Using the Direct Binding Invocation API" in the Developing SOA Applications with Oracle SOA Suite.

36.1.1 SOA-DIRECT Transport Features

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

36.1.2 Service Binding Types

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 WSDL files 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).

36.1.3 WS-Addressing for the SOA-DIRECT Transport

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 information 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 WS-Addressing Reference. For all other WS-Addressing properties, you must add or transform them in Service Bus pipelines 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 pipelines to support WS-Addressing between Service Bus and SOA framework service components.

For WS-Addressing examples with the SOA-DIRECT transport, see WS-Addressing Reference and XML Messaging Examples.

36.1.4 SOA-DIRECT Transport 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 SOA-DIRECT Endpoint URIs.

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 Configuring Business Services to Use the SOA-DIRECT Transport.

36.1.5 SOA-DIRECT Transport 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.

• Connection Errors

• Application Errors

• Generic Errors

36.1.5.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.

36.1.5.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.

36.1.5.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.

36.2 Using SOA Suite Services with Service Bus

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

• Simple Use Cases – Synchronous

• Advanced Use Cases – Asynchronous

36.2.1 Simple Use Cases – Synchronous

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

• Transactional Boundaries

• Synchronous Invocation of a SOA Composite

• Synchronous Invocation from a SOA Composite

• Associating Messages with the Correct Conversation

36.2.1.1 Transactional Boundaries

When synchronous BPEL components use the direct binding to interact with proxy services, the Service Bus and BPEL components share the same transactional context by participating in the same global transaction. The pipeline can perform any back-end activity within the same transactional context initiated by the BPEL component. In order to guarantee data consistency, everything that was done in that transaction must be rolled back if something fails to maintain state during processing. Note that the direct binding is typically used because transaction or security propagation is needed.

Service Bus direct binding failures are thrown back to the BPEL component as system faults, because Service Bus always marks the transaction for rollback in case of processing failure within the request pipeline. Therefore, any fault thrown from the Service Bus direct binding is a rollback fault and is interpreted as system fault on the SOA Suite side.

For more information about this behavior, see "BPELCaller Calls BPELCallee That Has bpel.config.transaction Set to required" in Developing SOA Applications with Oracle SOA Suite. This section explains transactional behavior between BPEL components with synchronous interfaces.

36.2.1.2 Synchronous Invocation of a SOA Composite

The SOA-DIRECT transport can invoke any component in a SOA composite that is exposed as a direct binding service. Figure 36-1 illustrates a synchronous communication pattern between a client and an Oracle SOA service component through Service Bus using a SOA-DIRECT business service and direct binding service.

Figure 36-1 Client Invoking a SOA Binding Service Synchronously

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

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

• Create a SOA-DIRECT business service in Service Bus that represents the SOA service component you want to invoke.

  • In Service Bus, create a WSDL resource based on the corresponding Oracle SOA direct binding service WSDL file.

    You can locate the SOA direct binding service WSDL file in JDeveloper using the SOA Resource Browser, as described in "Developing SOA Composite Applications with Oracle SOA Suite" in the Developing SOA Applications with Oracle SOA Suite.

  • Create a new business service with a soa-direct transport type and a WSDL 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.

  • Set the endpoint URI as described in SOA-DIRECT Endpoint URIs.

  • Configure the remainder of the business service, described in Configuring Business Services to Use the SOA-DIRECT Transport.

• Create a proxy service in Service Bus that invokes the business service. Choose the transport type that is used by the client. For proxy configuration information, see the online help provided with Service Bus.

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

36.2.1.3 Synchronous Invocation from a SOA Composite

A SOA composite can invoke any 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 How to Create an Outbound Direct Binding Reference in Developing SOA Applications with Oracle SOA Suite.

Figure 36-2 illustrates a synchronous communication pattern between an Oracle SOA service component and an external service through Service Bus.

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

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

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

• Create a business service in 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 information, see the online help provided with Service Bus.

• Create an SB proxy service in Service Bus that invokes the business service.

  • Create a WSDL resource to be used by the proxy service that invokes the business service.

  • Create a new proxy service with an sb transport type and a WSDL service type.

  • Select the WSDL file for the proxy service, and select the desired port or binding.

  • Configure the remainder of the proxy service. For more information, see Using the SB Transport.

  Note:

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

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

36.2.1.4 Associating Messages with the Correct Conversation

When using stateful services, the messages sent synchronously between 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 SOA-DIRECT transport provides built-in support for WS-Addressing.

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

36.2.2 Advanced Use Cases – Asynchronous

This section describes asynchronous communications between a SOA composite and 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.

• Asynchronous Invocation of a SOA Composite

• Asynchronous Invocation from a SOA Composite

36.2.2.1 Asynchronous Invocation of a SOA Composite

The SOA-DIRECT transport can invoke asynchronous SOA service components that are exposed as direct binding services. Figure 36-3 illustrates an asynchronous communication pattern between a client and an Oracle SOA composite through Service Bus using a direct binding service, the SOA-DIRECT transport, and the SB transport.

Figure 36-3 Client Invoking a SOA Binding Service Asynchronously

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

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

• On the inbound client side, create the 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, 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 service 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 ReplyTo Header and Asynchronous Composite to Composite Communication Through Service Bus.

  • 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 the online help provided with Service Bus.

• On the Service Bus outbound side, create the artifacts to interact with the SOA composite. This includes 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 Service Bus, create a WSDL resource based on the corresponding Oracle SOA direct binding service WSDL file.

      You can locate the SOA direct binding service WSDL file in JDeveloper using the SOA Resource Browser, as described in "Developing SOA Composite Applications with Oracle SOA Suite" in the $operation.

    • Create a new business service with a soa-direct transport type and a WSDL service type.

    • For the WSDL file, 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.

    • Set the endpoint URI, described in SOA-DIRECT Endpoint URIs.

    • 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 WS-Addressing Reference and Asynchronous Composite to Composite Communication Through Service Bus.

    • Configure the remainder of the business service. For more information, see SOA-DIRECT Transport Configuration Reference.

    • Invoke this business service from the request proxy service.

• Callback SB Proxy Service

  • Create a new proxy service with an sb transport type and a WSDL service type.

  • Browse to the WSDL file corresponding to direct binding service's WSDL file, and select the appropriate port or binding.

  • Complete the proxy service configuration. For more information, see Configuring Proxy Services to Use the SB Transport.

36.2.2.2 Asynchronous Invocation from a SOA Composite

An asynchronous SOA service component in a SOA composite can invoke external services through 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 How to Create an Outbound Direct Binding Reference in Developing SOA Applications with Oracle SOA Suite.

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

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

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

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

• In 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 with an sb transport type and a WSDL service type.

    • For the WSDL file, browse to the WSDL file you created and select the appropriate port or binding.

    • Complete proxy service configuration. For more information, see Configuring Proxy Services to Use the SB Transport.

      Since the callback is sent to a different connection, 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 ReplyTo Header and Asynchronous Composite to Composite Communication Through Service Bus.

  • Callback Business Service

    • Create a new business service with a soa-direct transport type and a WSDL service type.

    • For the WSDL file, browse to the WSDL file representing the callback interface with the direct binding reference, and select the appropriate port or binding.

    • Set the service URI to "callback," as described in SOA-DIRECT Endpoint URIs.

      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 Configuring Business Services to Use the SOA-DIRECT Transport.

• On the 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 information, see the online help provided with Service Bus.

  • 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 information, see the online help provided with Service Bus.

    For information on setting the callback addresses using WS-Addressing, see WS-Addressing Reference.

36.3 SOA-DIRECT Transport Configuration Reference

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

• SOA-DIRECT Endpoint URIs

• Configuring Business Services to Use the SOA-DIRECT Transport

• SOA-DIRECT Transport Environment Values

36.3.1 SOA-DIRECT Endpoint URIs

When specifying the endpoint URI for a SOA-DIRECT server, you need to follow a specific formatting pattern, depending on the type of role the service plays.

For SOA-DIRECT business services in the Service Callback role handling the inbound request, the actual URI is specified dynamically at runtime in the pipeline. Enter the following for the endpoint URI:

callback

Alternatively, if the callback address is always known, you can provide the exact callback address.

For all other SOA-DIRECT business service roles, use the following format. Optional elements are in brackets [].

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

where:

• protocol is the RMI or JNDI protocol to use. Use one of the following:

  • iiop / iiops: For generic, server-agnostic use.

  • t3 / t3s: For use with WebLogic Server.

  • http / https: For tunneling and use with 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 Service Bus.

• 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 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: The composite application version number. This is optional. If you do not specify a version, the current version is used.

• *label: Used with !versionNumber, this is the label hash used in the SOA service WSDL file. This is optional.

• 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 36-1. Therefore, load balancing and failover are not available for services in the Service Callback role.

36.3.1.1 Endpoint URI Format in a Cluster

When operating in a cluster, the SOA-DIRECT transport uses a different format fort the endpoint URI. Use the following 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.

36.3.1.2 Endpoint URI Examples

Following are some endpoint 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 Service Bus.

• t3://soaserver.example.com:7001/default/VacationRequest!1.0/directclient

  Points to a service deployed on a single node using a version number. This is the format in SOA binding component service WSDL files.

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

36.3.2 Configuring Business Services to Use the SOA-DIRECT Transport

Table 36-1 describes the properties you use to configure a SOA-DIRECT transport for a business service. For more information, see Creating and Configuring Business Services.

Table 36-1 SOA-DIRECT Transport Properties for Business Services

Property	Description
JNDI Service Account	Enter the static service account that defines security credentials for the JNDI lookup of the target SOA service. If you do not specify a service account, an anonymous subject is used. You can select from a list of defined service accounts. For more information, see Working with Service Accounts.
Role	Select one of the following options to identify the communication pattern the service uses: Synchronous Client (default): In this role the Callback Proxy option is disabled because there is no asynchronous callback. The WS-Addressing Version option is also disabled. Asynchronous Client: In this role you can identify a Callback Proxy, and you must select a WS-Addressing Version.Asynchronous callback is usually required. 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 an SOA service after an external service invocation. There is no load balancing or failover for Callback services.
Callback Proxy	Specify the proxy service that receives callbacks. This option is enabled only for the Asynchronous Client role. When you select a callback proxy, if no WS-Addressing is provided by the request or the proxy service pipeline, 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	Specify the default WS-Addressing version to use when no WS-Addressing is provided in the request or the proxy service pipeline. This option is enabled only for the Asynchronous Client role. WS-Addressing properties that are sent in the request or set in the 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 pipeline. For more information, see Transformation Examples.
Dispatch Policy	Select the instance of 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 with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server
Pass Caller's Subject	Select this option to have 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 Administering Security for Oracle WebLogic Server.
Invocation Service Account	Specify custom security credentials by selecting a service account for RMI invocation. You can specify any type of service account (pass through, static, or mapping). If you do not specify a service account, an anonymous subject is used. This is an alternative to the Pass caller's subject option. For more information, see Working with Service Accounts.

36.3.3 SOA-DIRECT Transport Environment Values

Table 36-2 describes the environment values supported by the SOA-DIRECT transport. The values you specify for these variables override the properties configured for specific SOA-DIRECT business services.

Table 36-2 SOA-DIRECT Transport Environment Values

Environment Value	Description
JNDI Service Account (security category)	The static service account that defines security credentials for the JNDI lookup of the target SOA service. If you do not specify a service account, an anonymous subject is used. For more information about service accounts, see Working with Service Accounts.
Pass Caller's Subject (security category)	When this is enabled, Service Bus passes the authenticated subject from the proxy service when invoking the SOA service. The Invocation Service Account variable below is an alternative to Pass Caller's Subject.
Invocation Service Account (security category)	The service account for RMI invocation using custom security credentials. You can specify any type of service account (pass through, static, or mapping). If you do not specify a service account, an anonymous subject is used. This is an alternative to Pass Caller's Subject.
Work Manager (environment category)	The instance of 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 with Service Bus "Using Work Managers to Optimize Scheduled Work" in Administering Server Environments for Oracle WebLogic Server

For information on these values, see Configuring Business Services to Use the SOA-DIRECT Transport.

36.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. It also describes ways to provide callback addresses in asynchronous communication, as described in Advanced Use Cases – Asynchronous.

See XML Messaging Examples for WS-Addressing examples.

• ReplyTo Header

• MessageID / RelatesTo Headers

36.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.

36.4.1.1 Calling a SOA Composite Asynchronously

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. Note that this header is generated only if the incoming message does not already contain a ReplyTo header.

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

36.4.1.2 Calling Back to a SOA Composite Asynchronously

When calling an external service from an Oracle SOA composite through 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 Asynchronous Invocation from a SOA Composite.

36.4.2 MessageID / RelatesTo Headers

MessageID and RelatesTo WS-Addressing headers are used to store the conversation ID in conversations between 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 that invokes a SOA-DIRECT business service.

The requirements for using MessageID and RelatesTo headers are slightly different in synchronous and asynchronous conversations, as described below:

• 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 Associating Messages with the Correct Conversation and the Conversation ID Examples.

36.5 XML Messaging Examples

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

• Conversation ID Examples

• Asynchronous Composite to Composite Communication Through Service Bus

36.5.1 Conversation ID Examples

This section provides examples of establishing a conversation ID among messages in a conversation between Service Bus and Oracle SOA composites. In Figure 36-5, a client synchronously invokes a BPEL Process component in an Oracle SOA composite. The business service (B1) uses the SOA-DIRECT transport to invoke a process. The pipeline called by the proxy service (P1) handles any necessary conversation ID mapping. The SOA composite exposes the BPEL Process as a direct binding service.

Figure 36-5 Operations in a Synchronous Exchange Through Service Bus

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

36.5.1.1 Port and Message Definitions

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

<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>

36.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 36-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.

36.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 36-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 (using 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 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 (using 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 (using a SOA-DIRECT business service)

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

36.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 36-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 (using 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 (using 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>

36.5.2 Asynchronous Composite to Composite Communication Through Service Bus

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

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

Figure 36-6 SOA Composite Invoking an SOA Composite Through Service Bus

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

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

36.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>

36.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>

36.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 Configuring Business Services to Use the SOA-DIRECT Transport. 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 Service Bus standard elements defined for WS-Addressing support.

36.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.

36.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>

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