39 Using the Direct Binding Invocation API

This chapter describes the Direct Binding Invocation API and how to invoke a SOA composite application. It describes how to create an inbound direct binding service, how to create an outbound direct binding reference, and how to set an identity for J2SE clients invoking direct binding. Samples of using the Direct Binding Invocation API are also provided.

39.1 Introduction to Direct Binding

A common way to invoke a composite is to use SOAP over HTTP. This is enabled by creating a SOAP service for your composite using web service binding. However, you can also use direct binding, which provides a tighter integration alternative. Direct binding enables Java clients to directly invoke composite services, bypassing the intermediate conversion to XML required with web service binding.

Direct binding provides two types of invocation styles:

Inbound direct binding

The direct service binding component allows an external client to send messages using the Direct Binding Invocation API, where the Direct Binding Invocation API takes the JNDI connection parameters and creates a connection object on behalf of the client.

Outbound direct binding (or direct reference binding)

The direct reference binding component provides support for sending SOA messages directly to external services over RMI. These external services must implement the SOA invocation API (the same as the direct inbound invocation API).

In the case of direct outbound binding, the connection object is created with the JNDI name of the external service bean configured for the binding.

Direct binding must be associated with the interface.wsdl, providing the interface clause and, optionally, the callbackInterface clause. The associated WSDL must be imported into the composite.

The service binding component also publishes a modified version of the WSDL that advertises the direct binding.

39.1.1 Direct Service Binding Component

A sample configuration using the direct service binding component is shown in Example 39-1.

39.2 Introduction to the Direct Binding Invocation API

The different packages used in the Direct Binding Invocation API are as follows:

oracle.soa.management.facade.Locator

The oracle.soa.management.facade.Locator interface exposes a method, createConnection, which returns a direct connection. The Locator exposes the method shown in Example 39-3 for returning the DirectConnection.

You must qualify the callback and its property elements properly with the SOA direct namespace.

The direct binding component is responsible for parsing the addressing headers set on the message instance. In this example, there are two headers: wsa:MessageID and wsa:ReplyTo. The service binding component makes the following properties available for the internal SOA components:

tracking.conversationId = D6202742-D9D9-4023-8167-EF0AB81042E

replyToAddress = sb://testserver:9001/callback

replyToReferenceParameter : element of WSA:ReferenceParameters

39.2.3 SOA Direct Address Syntax

The service paths used with the Direct Binding Invocation API follow the SOA direct address pattern:

soadirect:/CompositeDN/serviceName, where CompositeDN stands for composite distinguished name

In the SOA direct address, the CompositeDN has the following form:

domainName/compositeName[!compositeVersion[*label]]

39.2.4 SOA Transaction Propagation

Direct binding supports the SOA transaction propagation feature. You can invoke this feature from the client in the following ways:

Begin the Java transaction from the client and, after performing all the database operations, perform a commit. You should commit the database operations after a successful commit from the client side.

Begin the Java transaction from the client side. If a fault is thrown back during any operation in the SOA composite, then roll back the transaction from the client side. This rolls back all the database operations.

39.3 Invoking a SOA Composite Application with the Invocation API

The Direct Binding component in Oracle JDeveloper, as shown in Figure 39-3, provides support for exchanging SOA messages with SOA over RMI.

Select the reference target on which you want the direct binding service to operate:

Oracle SOA Composite: Creates a direct binding with a SOA composite application as a reference target.

Oracle Service Bus: Creates a direct binding with an Oracle Service Bus as a reference target.

WSDL URL

The URL location of the WSDL file. If you have an existing WSDL, then click the Find Existing WSDLs option.

Port Type

The port type of the WSDL file. You must select a port from the list.

Callback Port Type

The callback port type for asynchronous processes.

Use SSL For Callback

Select to use SSL for the callback.

Address

This field is automatically populated when you select a concrete WSDL URL and port type. However, you must manually populate this field if a nonconcrete WSDL is provided.

Provider URL

This field is automatically populated when you select a concrete WSDL URL and port type. However, you must manually populate this field if a nonconcrete WSDL is provided.

Use local JNDI Provider

Select to use the local JNDI provider.

copy wsdl and its dependent artifacts into the project

Deselect this checkbox. If you select this checkbox, the local copies of the WSDL file may result in synchronization issues if a remote WSDL is updated.

When complete, the Create Direct Binding dialog appears as shown in Figure 39-6. For more information about using the Oracle SOA Suite services with Oracle Service Bus, see the Oracle SOA Suite Transport (SOA-DIRECT) chapter in Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

39.3.4 What You May Need to Know About Invoking SOA Composites on Hosts with the Same Server and Domain Names

If one SOA composite application invokes another SOA composite application on another host through direct binding, and both composites are on hosts with the same server name and domain name, the invocation fails.

This is because the Oracle WebLogic Server transaction subsystem requires the domain names and server names to be different for transaction management to work properly. The transaction subsystem uses these names to track the location of a server related to a transaction. If the two servers in the invocation have the same name, the transaction subsystem can mistakenly confuse the two servers.

Ensure that you use hosts with separate server names and domain names.

39.4 Samples Using the Direct Binding Invocation API

Example 39-8 through Example 39-10 provide some examples of how the API is used. This section describes how the connection parameter can invoke SOA composite applications over direct binding and how message objects can be modified to invoke a direct binding invocation.

Example 39-8 Usage of a Connection Parameter

// The JNDIDirectConnectionFactory can be used to establish SOA instance
// connections for exchanging messages over the direct binding.
DirectConnectionFactory dcFactory = JNDIDirectConnectionFactory.newInstance();
// Connections are created based on the configuration, which is a map of standard
// naming properties, which will be used for the underlying connection lookup.
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(Context.INITIAL_CONTEXT_FACTORY, jndi.WLInitialContextFactory");
properties.put(Context.PROVIDER_URL, "t3://HOST:PORT");
properties.put(Context.SECURITY_PRINCIPAL, USERNAME);
propertie.put(Context.SECURITY_CREDENTIALS, PASSWORD);
DirectConnection conn =
dcFactory.createConnection("soadirect:/default/MyComposite!1.0/MyService",
properties);