Loosely typed interfaces – The Normalizer Pattern and Oracle SOA Suite

When getting two or more systems working together, the making a connection part is generally the easiest, identity propagation is a bit trickier, but many times, the syntax and semantics of one system is at odds with another one. Over the decades this has been manifest in many ways and thankfully there are tools and techniques to work through them. A collation of such techniques is Enterprise Integration Patterns. The book, along with the associated website, is worthy of a dedicated article or two, and is not the real subject of this article. One message transformation pattern the book describes is the Normalizer Pattern where different formats for essentially the same object are catered for.
An example where this form of message translation becomes necessary is when using a service with a loosely typed interface. This can often happen when an existing system or utility (such as a batch / command processor) gets exposed as a web service. The request / response payload is little more than a collection of key / value pairs. There are a couple of ways to cater for this using Oracle SOA Suite 11g which I will outline in this article. One has full tool support. The other, a solution using XSLT, is not fully supported, but has an advantage in that the XSLT can be used both with the BPEL and Mediator components.

Troublesome Payloads
The challenge is to get something that is strongly typed into something that is loosely typed

  Furniture
  Pam Beech
  50000
  20000
  47000

       NAME
       Furniture


       MANAGER
       Pam Beech


       BUDGET
       50000


       SPENT
       20000


       COMMITTED
       47000

Now this is quite a simple example and the real world has a lot more complicated cases out there. Ones that would involve number formatting, character encoding, attribute concatenation, and so on. For the purposes of this exercise however, it is ideal to illustrate the point. All the files in this example are free and available for you to use, modify or incorporate into your own solution as you see fit. The example was produced and tested using Oracle Fusion Middleware 11.1.1.2.0. That is JDeveloper Studio 11.1.1.2.0 and WebLogic Server 11gR1. To reduce the number of files and dependencies involved, the example is a simple service (BPELProcessExample.wsdl) that takes a strongly typed request payload and returns a loosely typed response payload. The SOA composite project contains two BPEL processes that provide slightly different implementations for this same WSDL.

Figure 1. Using BPEL assign to construct a new payload.

BPEL assign with copy and insertAfter
You can cater for the key / value pair structure by repeatedly appending a new ‘property’ element and then, using an XPATH predicate to specify which ‘property’ element is the target, copying the desired values. In the BPEL process this can all be done in a single ‘assign’ command, using the insertAfter instruction from the Oracle BPEL extension library. The BPEL designer supports this approach, and it is used extensively in production systems around the globe. It can get difficult to maintain and hard to read if the payload is large though. If dealing with a large payload see if you can split the copy / insertAfter instructions into two or more ‘assign’ commands. Ideally, you would give these ‘assign’ commands logical names such as ‘assign_part_1_admin_details’ and ‘assign_part_2_finance_details’. What is a large payload in this case then? Well, I would say that if you have more than 10 key value pairs you should be seriously thinking about splitting them up and if you have more than 20, you should be definitely splitting them up. Remember, you might be familiar with the structure and understand how it is constructed, but what about the college graduate brought in by the consulting firm in a months time, or even you having to come back to this in 6 months time? Go on, make the maintenance a bit easier for everyone and break that assign behemoth into manageable chunks!

Figure 2. Using XSL to transform the payload.

BPEL transform with XSLT
If experienced in dealing with XML documents then this approach will probably be very familiar to you. Extensible Stylesheet Language Transformations is used to convert XML data into some other format, which may also be XML data. In this case the stylesheet explicitly describes the target XML structure, making it somewhat easier to read than the BPEL assign approach described earlier. For example…

 
  MANAGER
 
 
  
  
 

The ‘client’ is a namespace prefix for the schema and in this SOA composite example the request and response happen to be defined in the same schema. This is easier to read, even if one is not all that familiar with XSL. For large payloads it is not necessary to split up the transformation as one might consider for the BPEL assign, but it could be done. The single transformation file could have a whole set of templates. However, the XSL Mapper does not support this approach yet, so if using this approach you will have to work in the Source editor, not the Design mode. Since this is using XSLT, the same XSL file can be used by the Mediator too, so it is not only a BPEL solution.

Which one is right for me?
As one can see from the diagrams there is not much difference in the BPEL designer between the two examples and the decision on which technique to use would be based on factors which are different from company to company, but clearly use of the XSL mapper is an important factor.
The complete example application with SOA composite is available at http://sites.google.com/site/soastation/soastation_looselytyped_normalizer.zip