Use WSIF Java Binding with OraBPEL

Background

OraBPEL's java binding implementation is based on apache WSIF package's java binding. Java binding enables a BPEL process to invoke user defined java classes.

Internally all data used in a BPEL processes are of w3c DOM Element. So data marshalling needs to be performed between BPEL process and and the user defined java classes. OraBPEL's java binding implementation curretly supports java classes that uses the following three data types:

XML simple type.
XML complex type using OraBPEL's facade data type.
DOM element.

Sample of the document can be found in OraBPEL's cvs repository under collaxa/qa/src/bpel/misc/javaBinding. Or download from here.

Using java binding

Java binding service using XML simple type

Most XML simple types can be mapped to java types, and vise versa. The data mapping can be defined in WSDL using format extension. For a java method defined as


  public float getQuote (String symbol) throws Exception;

The format:typeMap definitions should look like:

<binding name="JavaBinding" type="tns:StockquotePT">
  <java:binding/>
  <format:typeMapping encoding="Java" style="Java">
    <format:typeMap typeName="xsd:string" formatType="java.lang.String" />
    <format:typeMap typeName="xsd:float" formatType="java.lang.float" />
  </format:typeMapping>
  <operation name="getQuote">
    <java:operation methodName="getQuote"/>
    <input/>
    <output/>
  </operation>
</binding>

This usage can be found in the sample that comes with the release under orabpel/samples/demos/IBMSamples/simple.

Java binding service using OraBPEL XML facade

XML facade is a OraBPEL technology that provides a java bean like interface on top of XML DOM element. Given the XML schemas, facade classes can be generated by using the OraBPEL schemac tool. Please refer to OraBPEL developement document for more info about XML facade. In the attached example, the HelperService classes uses XML facade classes in the method:


    public CommentsType addComment(CommentsType payload, CommentType comment)
        throws JavaBindingException;

The WSDL java binding looks like:

  <binding name="JavaBinding" type="tns:HelperService">
    <java:binding/>
    <format:typeMapping encoding="Java" style="Java">
      <format:typeMap typeName="tns:commentType" formatType="com.otn.services.CommentType" />
      <format:typeMap typeName="tns:commentsType" formatType="com.otn.services.CommentsType" />
    </format:typeMapping>
    <operation name="addComment">
      <java:operation methodName="addComment"/>
      <input/>
      <output/>
      <fault name="CommentException"/>
    </operation>
    <operation name="testFault">
      <java:operation methodName="testFault"/>
      <input/>
      <output/>
      <fault name="CommentException"/>
    </operation>
  </binding>

The java types CommentType and CommentsType are XML facade classes.

Java binding service using XML DOM element

Since OraBPEL internally uses XML DOM element. If a java binding class uses XML DOM elements, then there is no need to do data marshalling. For example in HelperService2.java of the attached sample, the addComment() method is defined as:


    public Element addComment(Element payload, Element comment)
        throws JavaBindingException;

Then the java binding of the WSDL looks like:

  <binding name="JavaBinding2" type="tns:HelperService2">
    <java:binding/>
    <format:typeMapping encoding="Java" style="Java">
      <format:typeMap typeName="tns:commentType" formatType="org.w3c.dom.Element"/>
      <format:typeMap typeName="tns:commentsType" formatType="org.w3c.dom.Element"/>
    </format:typeMapping>
    <operation name="addComment">
      <java:operation methodName="addComment"/>
      <input/>
      <output/>
      <fault name="CommentException"/>
    </operation>
    <operation name="testFault">
      <java:operation methodName="testFault"/>
      <input/>
      <output/>
      <fault name="CommentException"/>
    </operation>
  </binding>

With java class using DOM element type, java binding can supports any XML data type.

Throw WSDL fault from java binding

As a web service, a java binding can throw fault. The fault can be defined in WSDL just as a normal web service.

  <message name="CommentFaultMessage">
      <part name="payload" type="tns:commentType"/>
  </message>

  <portType name="HelperService2">
    <operation name="testFault">
      <input message="tns:TestFaultRequestMessage"/>
      <output message="tns:TestFaultResponseMessage"/>
      <fault name="CommentException" message="tns:CommentFaultMessage" />
    </operation>
  </portType>

  <binding name="JavaBinding2" type="tns:HelperService2">
...
    <operation name="testFault">
      <java:operation methodName="testFault"/>
      <input/>
      <output/>
      <fault name="CommentException"/>
    </operation>
  </binding>

To be able to throw a WebService fault, the java class has to do something special. It has to be declare to throw a predefined fault type com.collaxa.cube.ws.wsif.providers.java.JavaBindingException or its subclass.

In the attached sample, HelperService1.java has a function that throws such an exception:

    public CommentType testFault(CommentType payload)
        throws JavaBindingException
    {
        System.out.println("testFault : " + payload);
        if (payload != null) {
            JavaBindingException ex = new JavaBindingException();
            ex.setFaultName("CommentException");
            ex.setPart("payload", payload);
            System.out.println(" throwing exception " + ex);
            throw ex;
        } else {
            return payload;
        }
    }

In HelperService2.java we have the similar function:

    public Element testFault(Element payload)
        throws JavaBindingException
    {
        System.out.println("testFault2: " + payload);
        if (payload != null) {
            JavaBindingException ex = new JavaBindingException();
            ex.setFaultName("CommentException");
            ex.setPart("payload", payload);
            System.out.println("   throwing exception " + ex);
            throw ex;
        } else {
            return payload;
        }
    }

If such an exception is actually thrown from the java binding class, BPEL WSIF layer will convert it into a WebService exception which can be caught by the BPEL source like:

  <variables>
    ......
    <variable name="fault" messageType="services:CommentFaultMessage"/>
  </variables>
  ......
      <faultHandlers>
        <catch faultName="services:CommentException" faultVariable="fault">
          <assign>
            <copy>
              <from expression="string('CommentException')"/>
              <to variable="output" part="payload" query="/types:comments/types:
item[1]/types:message"/>
            </copy>
          </assign>
        </catch>
        <catchAll>
          <empty/>
        </catchAll>
      </faultHandlers>