46 Using the Direct Binding Invocation API

This chapter describes the direct binding invocation API and how it can invoke SOA composite applications.

This chapter includes the following sections:

46.1 Introduction to the Direct Binding Invocation API

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 the Web Service binding. However, you can also use the direct binding that provides a tighter integration alternative. The direct binding enables Java clients to directly invoke composite services, bypassing the intermediate conversion to XML required with the web service binding.

The different packages used in the invocation API are as follows:

  • oracle.soa.management.facade.Locator

    The oracle.soa.management.facade.Locator interface exposes a method, createConnection, which returns direct connection. The Locator exposes the following method for returning the DirectConnection:

    import java.util.Map;
public interface DirectConnectionFactory {
    DirectConnection createDirectConnection(CompositeDN compositeDN,
 String serviceName) throws Exception;

    You can use the LocatorFactory implementation to get the DirectConnection as follows:

    Hashtable jndiProps = new Hashtable();
jndiProps.put(Context.PROVIDER_URL, "t3://" + hostname + ':' + portname + "/soa-infra");
jndiProps.put(Context.INITIAL_CONTEXT_FACTORY,"weblogic.jndi.WLInitialContextFactory");
jndiProps.put(Context.SECURITY_PRINCIPAL,"weblogic");
jndiProps.put(Context.SECURITY_CREDENTIALS,"welcome1");
jndiProps.put("dedicated.connection","true");
Locator locator = LocatorFactory.createLocator(jndiProps);
CompositeDN compositedn = new CompositeDN(domainName, compositename, version);
String serviceName = "HelloEntry";
return locator.createDirectConnection(compositedn, serviceName);

  • oracle.soa.api.invocation.DirectConnection

    The DirectConnection interface is used to invoke a composite service using the direct binding.

    The DirectConnection.java is as follows:

    import oracle.soa.api.message.Message;
public interface DirectConnection {
    <T> Message<T> request(String operationName, Message<T> message) throws
 InvocationException, FaultException;
    <T> void post(String operationName, Message<T> message) throws
 InvocationException;
    void close();}

  • oracle.soa.api.message.Message

    The Message interface encapsulates the data exchanged.

    The Message interface.java is as follows:

    import java.util.List;
import java.util.Map;
import org.w3c.dom.Element;
public interface Message<T> {
    // Instance-tracking property names
    final static String FLOW_ID;
    final static String CONVERSATION_ID;
    final static String PARENT_ID;
    void setPayload(Payload<T> payload);
    Payload<T> getPayload();
    void addAttachment(Attachment attachment);
    List<Attachment> getAttachments();
    void addHeader(Element header);
    void setHeaders(List<Element> headers);
    List<Element> getHeaders();
    void setProperties(Map<String, Object> properties);
    void setProperty(String name, Object value);
    Map<String, Object> getProperties();
    Object getProperty(String name);
}

This section also contains the following topics:

46.1.1 Synchronous Direct Binding Invocation

Direct binding also supports the Synchronous Direct Invocation with the usage of the method:

<T> Message<T> request(String operationName, Message<T> message) throws InvocationException, FaultException

46.1.2 Asynchronous Direct Binding Invocation

Asynchronous invocation relies on the WS-Addressing headers set on the message instance. All headers must adhere to WS-Addressing specification.

The direct binding invocation API allows the clients to specify the WS-Addressing ReplyTo SOAP header to communicate a destination by which they can receive responses.

Note:

The supported addressing version includes:

An example of the WS-Addressing header used for asynchronous invocation is as follows:

<wsa:MessageID>D6202742-D9D9-4023-8167-EF0AB81042EC</wsa:MessageID>
<wsa:ReplyTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>sb://testserver:9001/callback</wsa:Address>
<wsa:ReferenceParameters>
<soa:callback xmlns:soa="http://xmlns.oracle.com/soa/direct"
connection-factory="mytest.MyDirectionConnectionFactory">
<soa:property name="oracle.soa.api.invocation.direct.bean"
 value="myTest.MyDirectConnectionBean"/>
<soa:property name="java.naming.provider.url" value="t3://test:8001"/>
<soa:property name="java.naming.factory.initial"
 value="weblogic.jndi.WLInitialContextFactory"/>
</soa:callback>
</wsa:ReferenceParameters>
</wsa:ReplyTo>

Note:

You must qualify the callback and its property elements properly with 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

46.1.3 SOA Direct Address Syntax

The service paths used with the SOA 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]]

46.1.4 SOA Transaction Propagation

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

  • Begin the java transaction from the client and after performing all the database operations, do a commit. You should commit the database operations after the successful commit from the client side.

  • Begin the java transaction from the client side. In case a fault is thrown back during any operation in the SOA composite, then roll back the transaction from the client side. This should roll back all the database operations.

46.2 Invoking a SOA Composite Application with the Invocation API

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

Figure 46-1 Direct Binding Service Option

Description of Figure 46-1 follows
Description of "Figure 46-1 Direct Binding Service Option"

Oracle JDeveloper supports creating a direct service binding, as shown in Figure 46-1. The direct service binding component allows an external client to send messages using the SOA Direct Binding Invocation API, where the SOA Direct Binding Invocation API takes the JNDI connection parameters and creates a connection object on behalf of the client.

For more information about SOA Direct Binding Invocation API, refer to Section 46.1, "Introduction to the Direct Binding Invocation API."

The direct binding components support both synchronous and asynchronous invocation patterns. Figure 46-2 describes a sample synchronous invocation pattern and Figure 46-3 describes a sample asynchronous invocation pattern.

Figure 46-2 Sample Synchronous Invocation Patterns

Description of Figure 46-2 follows
Description of "Figure 46-2 Sample Synchronous Invocation Patterns"

Figure 46-3 Sample Asynchronous Invocation Pattern

Description of Figure 46-3 follows
Description of "Figure 46-3 Sample Asynchronous Invocation Pattern"

To invoke a SOA composite application using the Direct Binding Service option:

  1. Open Oracle JDeveloper.

  2. From the Component Palette, select SOA.

  3. From the Service Components list, drag a Direct Binding Service into the designer. The Direct Binding Service dialog appears.

  4. Enter the details shown in Table 46-1.

    Table 46-1 Direct Binding Service Dialog Fields and Values

    Field Value

    Name

    Enter a name (for this example, SayHello is entered).

    Type

    Select Service from the list.

    WSDL URL

    The URL location of the WSDL file. If you have an existing WSDL, then click the Find Existing WSDLs option, else click Generate WSDL from schema(s).

    Port Type

    The value execute_ptt appears in this field, by default.

    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 remote WSDL is updated.

    When complete, the Direct Binding Service dialog appears as shown in Figure 46-4.

    Figure 46-4 Direct Binding Service Dialog

    Description of Figure 46-4 follows
    Description of "Figure 46-4 Direct Binding Service Dialog"

  5. Click OK.

    The Direct Binding Service displays in the designer shown in Figure 46-5. The single arrow in a circle indicates that this is a synchronous, one-way direct binding service component.

    Figure 46-5 Direct Binding Service

    Description of Figure 46-5 follows
    Description of "Figure 46-5 Direct Binding Service"

46.3 Samples Using the Invocation API

This section includes some examples of how the API is used. This section describes how the connection parameter can invoke SOA composite applications over the direct binding and how message objects can be modified to invoke a direct binding invocation.

Example 46-1 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,
 "weblogic.jndi.WLInitialContextFactory");
properties.put(Context.PROVIDER_URL, "t3://HOST:PORT");
DirectConnection conn =
    dcFactory.createConnection("soadirect:/default/MyComposite!1.0/MyService",
 properties);

Example 46-2 Usage of Messages

//Messages are created using the MessageFactory 
Message<Element> request = XMLMessageFactory.getInstance().createMessage();

//Message objects are then modified to be used for an invocation 
Map<String, Element> partData; // Define a Map of WSDL part names to matching XML
 Element objects
Payload<Element> payload = PayloadFactory.createXMLPayload(partData);
request.setPayload(payload);
// One-way invocation
conn.post("onewayoperation", request);
// Request-reply invocation
Message<Element> response = conn.request("requestreplyoperation", request);

Example 46-3 Usage of LocatorFactory

Hashtable jndiProps = new Hashtable();
jndiProps.put(Context.PROVIDER_URL, "t3://" + hostname + ':' + portname +
 "/soa-infra");
jndiProps.put(Context.INITIAL_CONTEXT
-FACTORY,"weblogic.jndi.WLInitialContextFactory");
jndiProps.put(Context.SECURITY_PRINCIPAL,"weblogic"); 
jndiProps.put(Context.SECURITY_CREDENTIALS,"welcome1");
jndiProps.put("dedicated.connection","true");
Locator locator = LocatorFactory.createLocator(jndiProps);
CompositeDN compositedn = new CompositeDN(domainName, compositename, version);
String serviceName = "HelloEntry";
return locator.createDirectConnection(compositedn, serviceName);