SOA Tips

Talking about SOA means talking about messages flowing all around the systems in the whole enterprise. Heterogeous systems exchange messages through the messaging infraestructure in place with local and/or external networks (when consuming external services, providing services to the internet, etcetera). In this situation P2P (point to point) security techniques like SSL are no more able to meet the security needs. So, how can those messages flow securely from consumer to provider and vice-versa?? That's what security techniques like XML encryption and XML digital signature have been created for.

One of the facts that the digital signature provides you with is data integrity. So, in case you have to use it you need to ensure the message is being transfered EXACTLY "as is" all way long. By default, this does not happen when using Oracle ESB as a mediator but this behaviour can now be changed using the 10.1.3.4.0 MLR#3 patchset.

In order to achieve the later, a new property has been defined for routing services: the "passthrough" property. Setting this property to true makes the ESB to send exactly the same message it has received thus making it happen. For more information take a look at bug #6811827 in Metalink.

Usually, WSM custom steps reflecting your own policy can lead to faults (as per the request not being compliant with the implemented policy). In those cases a custom SOAP fault will make sense in order to provide the invoker with details of the reason for the failure. The following code shows up how to generate such custom SOAP faults when creating WSM custom steps.


package ....;

  private Fault createFault(MessageContext msgCtxt, String faultCodeQualifier, String faultString, String[][] values) {
    try {
      SOAPFactory factory = SOAPFactoryImpl.newInstance();
      SOAPFault sf = msgCtxt.getRequest().getAxisMessage().getSOAPPart().getEnvelope().getBody().addFault();
      Detail detail = sf.addDetail();
      for (int i = 0; i < values.length; i++) {
        DetailEntry de = detail.addDetailEntry(factory.createName(values[i][0] , CUSTOM_DETAIL_PREFIX, CUSTOM_DETAIL_NS));
        de.addTextNode(values[i][1]);
      }
      return new Fault(CUSTOM_FAULT_NS, faultCodeQualifier, faultString, null, detail);
    } catch (SOAPException soape) {
      return new Fault(soape);
    }
  }
}







The result obtained because of the execution of the former code looks like this:


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode xmlns:p="http://my.custom.fault/ns">p:Client.customCodeA</faultcode>
      <faultstring>error A description</faultstring>
      <detail>
        <cd:CustomDetailA1 xmlns:cd="http://my.custom.detail/ns">detailValue1</cd:CustomDetailA1>
        <cd:CustomDetailA2 xmlns:cd="http://my.custom.detail/ns">detailValue2</cd:CustomDetailA2>
      </detail>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


• Introduction
• Asynchronous model implementations
• BPEL asynchronous model
• JAX-WS asynchronous model
• Adapting a JAX-WS WSDL for BPEL
• Adapting the portType definition
• Adapting the binding definition
• Adapting the service definition
• WS-Addressing
• Sending http://www.w3.org/2005/08/addressing WS-Addresing headers
• Receiving http://www.w3.org/2005/08/addressing WS-Addresing header in Oracle BPEL PM

Introduction

In the Web Services world an asynchonous call means sending a message to a remote service and then wait for it to send the response back to the caller

(a.k.a. callback). Talking in HTTP terms this means two different HTTP connections: one from the client to the service provider and the other from the

provider to the client. As the same client can call several times to an asynchonous service the incoming callbacks must be correlated with the invocations.
WS-Addressing [WSA] is the standard used for this correlation. This standard defines a set of SOAP headers needed to achieve

correlation. The most important ones are:

	Fig. 1 - Asynchonous invocation message interchange

Asynchronous model implementations

Each SOAP stack provides it's own implementation of the asynchonous model and problems may occurr when the client and the provider use different SOAP stack.

This document describes the specific case of invoking a JAX-WS asynchronous service from Oracle BPEL 10.1.3.1. Let's take a look to both models to see the

difference.

BPEL asynchronous model

In BPEL the asynchonous model is implemented via two Web Services. An asynchronous BPEL service exposes two services in it's WSDL as shown in the following

pictures:

Fig. 2 - BPEL process asynchronous WSDL (request highlighted)

Fig. 3 - BPEL process asynchronous WSDL (response highlighted)

The former is to be implemented by the service itself to receive the invocation. The later is to be implemented by the client in order to receive the

callback.

JAX-WS asynchronous model

As you can see in the picture below a JAX-WS asynchonous service does only expose one service. The asynchrony affects only to the implementation and not to

the service description itself. The runtime behaviour is the same as in the BPEL case. The only difference is in the way they service is described.

	Fig. 4 - JAX-WS asynchronous WSDL

Adapting a JAX-WS WSDL for BPEL

The target is to create a WSDL equivalent to the JAX-WS one but adapted to the BPEL style so the runtime behaviours get equal.

Adapting the portType definition

As we saw previously as there's only one portType in the JAX-WS WSDL it has to be broken down into two. The output of the original portType has to be removed

from it. The new portType has the original one's output as input as it's going to be used for callback.

	Fig. 5 - JAX-WS sample portType tag
	Fig. 6 - JAX-WS sample portType tag (Modified)

Adapting the binding definition

We have to act the same way with the binding. It has to be broken down into two bindings following the same rules used for the portType. First, the output

must be removed from the original binding. Then a binding has to be created for the callback portType. Again, the ouput from the original one becomes the

input of this one.

	Fig. 7 - JAX-WS sample binding tag
	Fig. 8 - JAX-WS sample binding tag (Modified)

Adapting the service definition

Finally, a new service has to created. It has to be associated to the recently created portType and binding. The location needs not to have a existing URL as

the WS-Addresing headers will tell the remote service where to send the callback message.

	Fig. 9 - JAX-WS sample service tag
	Fig. 10 - JAX-WS sample service tag (Modified)

WS-Addressing

There are several addresing headers and all of them are valid. Oracle BPEL PM 10.1.3.1 uses the ones in the

http://schemas.xmlsoap.org/ws/2003/03/addressing namespace. In order to use different addressing headers (E.g. the ones in the

http://www.w3.org/2005/08/addressing namespace) the following has to be done:

Sending http://www.w3.org/2005/08/addressing WS-Addresing headers

Some messages have to be defined to send out the theese addressing headers. One for each header we want to be included.

	Fig. 11 - http://www.w3.org/2005/08/addressing messages

The bindings have also to be modified to indicate the headers we want to be sent and received. Each header declaration points to the correspondent message

from the described above.

	Fig. 12 - Bindings including headers

Receiving http://www.w3.org/2005/08/addressing WS-Addresing header in Oracle BPEL PM

As, by default, Oracle BPEL PM searchs only for the http://schemas.xmlsoap.org/ws/2003/03/addressing headers for correlation a specific handler has to be

deployed. The code shown here is a header handler. It looks for the addressing header and in case it finds it sets the conversation ID (the attribute used

for correlation) with the header's value.

In order to develop a BPEL header handler the com.collaxa.cube.engine.handlers.IMessageHandler interface has to be implemented. To compile it the Jar files

located at the Oracle BPEL PM library folder have to be in the classpath.

	Fig. 13 - http://www.w3.org/2005/08/addressing header handler source code

To deploy it to the Oracle BPEL PM engine just copy the class (with the required folder structure) to the $BPEL_HOME/system/classes folder. Then, edit the

message-handlers.xml file located at $BPEL_HOME/domains//config folder. Include a new message-handler tag for the handler and include it in the

inbound-flow tag. After restarting BPEL the handler will start working.

	Fig. 14 - Message handler configuration

Additional Resources

[WSA] W3C WS-Addressing Core

[JAX-WS] JAX-WS at Java.net