37 Using the Direct Binding Invocation API

37.2.1 Synchronous Direct Binding Invocation

Direct binding also supports the Synchronous Direct Invocation with the usage of the method shown in Example 37-7.

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

37.2.2 Asynchronous Direct Binding Invocation

Asynchronous invocation relies on the WS-Addressing headers set on the message instance. All headers must adhere to the 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.

An example of the WS-Addressing header used for asynchronous invocation is shown in Example 37-8.

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

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

37.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]]

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

37.3.1 How to Create an Inbound Direct Binding Service

You can invoke a SOA composite application using the Direct Binding option in Oracle JDeveloper.

To create an inbound direct binding service:

1. Open Oracle JDeveloper.

2. From the Component Palette, select SOA.

3. From the Service Adapters list, drag the Direct Binding component into the Exposed Services swimlane. The Create Direct Binding dialog appears.

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

   Table 37-1 Direct Binding Service Dialog Fields and Values

   Field	Value
   Name	Enter a name.
   Type	Select Service from the list.
   Reference Target	This field is disabled when defining this service in the Exposed Services swimlane.
   WSDL URL	The URL location of the WSDL file. If you have an existing WSDL, then click the Find Existing WSDLs option. Otherwise, click Generate WSDL from schema(s).
   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 the WSDL is concrete and it has at least one binding that is direct.
   Provider URL	This field is automatically populated when the WSDL is concrete and it has at least one binding that is direct.
   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 37-4.

   Figure 37-4 Create Direct Binding Dialog

   
   Description of "Figure 37-4 Create Direct Binding Dialog"
   
   

5. Click OK.

   The direct binding service displays in the SOA Composite Editor shown in Figure 37-5. The single arrow in a circle indicates that this is a synchronous, one-way, direct binding component.

   Figure 37-5 Direct Binding Service

   
   Description of "Figure 37-5 Direct Binding Service"
   
   

37.3.2 How to Create an Outbound Direct Binding Reference

You can create an outbound direct binding reference, using the Direct Binding option in Oracle JDeveloper, to either invoke a composite application or an Oracle Service Bus.

To create an outbound direct binding reference:

1. Open Oracle JDeveloper.

2. From the Component Palette, select SOA.

3. From the Service Adapters list, drag the Direct Binding component into the External References swimlane. The Create Direct Binding dialog appears.

4. Enter the details shown in Table 37-2.

   Table 37-2 Direct Binding Service Dialog Fields and Values

   Field	Value
   Name	Enter a name.
   Type	Select Reference from the list.
   Reference Target	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 37-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.

   Figure 37-6 Create Direct Binding Dialog

   
   Description of "Figure 37-6 Create Direct Binding Dialog"
   
   

5. Click OK.

   The direct binding reference displays in the designer shown in Figure 37-7. The single arrow in a circle indicates that this is a synchronous, one-way direct binding reference component.

   Figure 37-7 Direct Binding Reference

   
   Description of "Figure 37-7 Direct Binding Reference"
   
   

37.3.3 How to Set an Identity for J2SE Clients Invoking Direct Binding

J2SE clients can set an identity while invoking direct binding, as shown in Example 37-9.

public static void main(String[] args) throws Exception {
       Invoker invoker = new Invoker();
       String payloadXML="<ns1:process
xmlns:ns1=\"http://xmlns.oracle.com/DirectBinding_jws/EchoBPEL/BPELProcess1\">
" +"\n" +
             "<ns1:input>wew</ns1:input>" + "\n"+
              "</ns1:process>" ;

     String serviceAddress = "soadirect:/default/EchoBPEL!1.0/DService1";
    System.out.println("***** test Sync ****");
     DirectConnectionFactory factory =
JNDIDirectConnectionFactory.newInstance();

     Message<Element> m = getAsyncRequest(payloadXML);
     Map<String, Object> props = new HashMap<String, Object>();
     props.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
     props.put(Context.PROVIDER_URL, "t3://" + hostname + ':' + portname);
    props.put(Context.SECURITY_PRINCIPAL,"xtest-soa1-user");
 props.put(Context.SECURITY_CREDENTIALS,"welcome1");

     DirectConnection conn = factory.createConnection(serviceAddress,
props);

     DirectConnection conn = getConnection(serviceAddress);
     Document doc = DirectBindingXMLUtil.getDocumentFromString(payloadXML);
            Element element = doc.getDocumentElement();
            Map<String, Element> payload = new HashMap<String, Element>();
            payload.put("payload", element);

     Message<Element> m =
XMLMessageFactory.getInstance().createMessage(payload);
     List<Element> headers =
createWSAHeaders("payload:BPELSyncTest:msgID:1234567");
     for( Element e : headers)
         m.addHeader(e);

try {
               ctx = new InitialContext(props);
               conn.request("process", m);
           }
           finally
           {
               if (null != ctx) ctx.close();
           }

    //System.out.println(ret);

   } 

The key points in the above example are as follows:

• The creation of an InitialContext with the security principal/principal credentials before invoking the direct connection; this achieves a login.

• The close of the InitialContext; this achieves the log out.

  try {
                 ctx = new InitialContext(props);
                 conn.request("process", m);
             }
             finally
             {
                 if (null != ctx) ctx.close();
             } 
  

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