IIB service development, pitfalls to avoid for new JAX-WS migrants.

DISCLAIMER : The following article discusses the behaviour of IIB 9.x , WMB 8.xx and prior releases, future IIB versions may (and most likely will) alter this behaviour. These are my personal views and do not represent IBM official position.

Introduction 

The more I work with IIB (and WMB), the more I feel it is the best ESB solution available from IBM and arguably from any provider (my bias notwithstanding), Developers moving from WESB to IIB will be pleased with the powerful range of features available and with the speed and ease of development.

However, a deeper understanding that the roots of IIB in MQ does make it a different environment than WESB which was a J2EE implementation, once you take that into consideration, migrating projects from WESB to IIB should be a much easier task.

The following blog entry should help you avoid some of the most common pitfalls and make your journey into WS development in IIB a lot more friendly.

You can find a quick tutorial on how to build IIB web services in my Worklight to IIB series here 

Use ESQL SET  with caution.

The order of elements in an XSD is important for XSD validation, breaking the order will lead to 'invalid xml'.

Take a look at this XSD and note the order of the elements.

When using the ESQL content assist you will see what you expect , the XSD is now part of the SOAP and XMLNC parsers.

The first thing to notice here is that content assist does not display elements in the same order as the XSD (this is a sign of things to come !).

In the code snippet above you also see the use of 'REFERENCE' which is a common technique to write neater source  ( and arguably faster  running code ).

Now we run the code and examine the resulting XML.

 

Now you get the picture, follow both the green arrows and the blue arrows and you will discover that the order of the XML output actually DEPENDS on the order of your code execution.

 That SOAP message that the code above generates is INVALID.

Conclusion.

• Your code must be written in the same order as the Original XSD.
• As you seen earlier the content assist is not in the right order so do not be fooled by that.
• If you plan to populate an XSD model through multiple steps (by using Environment or LocalEnvironment), you must make sure that all your code pieces execute in the same order every time.
• To guard against such mistakes and for peace of mind, I do highly recommend using a 'validate' node before you return your code (performance implications not withstanding).

Avoid the namespace mayhem.

"Mayhem : A state or situation of great confusion, disorder, trouble or destruction; chaos. " Wiktionary.

It is common for a single WSDL or even a single web service operation to have multiple namespaces in the sample I have here have two name spaces

• Service elements : "http://KLFSamples.ESB.WL/service/"
• Data elements     : "http://www.example.org/DB_Data"

Now look at this simple ESQL code that sets the SOAP response body to fixed values.

NOTE : The use of 'Reference' is highly recommended but you can not use a 'REFERENCE' until an element is created so a 'set' to an element in 'Person' object has to happen before I can reference it.  Personally I think it is one of those bugs that became a 'feature' as time went on. but I digress.

This previous code looks straight forward, but the XML generated in the SOAP message would carry a real "interesting" surprise to those used to  JAX-RPC and JAX-WS.

It seems that IIB 9.0 (Have not tested IIB10 yet) and Previous versions of WMB  have their own peculiar  way of adding and duplicating the same name space in multiple places.

The problem gets worse as the same 'NSx' could be defined with two different values in different places in the same SOAP message but within different hierarchical structures. 

So far, this is just an 'Ugly' message but not 'invalid'. But the problem will compound if you are actually writing into the input of a SOAPRequest node, and if that node is making a call into another IIB (or WMB) service those unexpected namespaces become impeded in the elements as they travel through the IIB engine, the reply from that SOAPRequest node will for sure carry an invalid XML and will probably break your flow. (do not ask me how I know ).

Solution 

Thanks to my friend and WMB Guru in ISSW Scott Rippley, the answer lies in the developer enumerating manually all Namespaces in their SOAP message, and inserting them all manually into the XMLNC or SOAP domain, thus forcing the parsers to use them and cleaning up output.

 The resulting SOAP message now will look like what you would have expected originally.

Technical Summary

• Keep track of all the name spaces used in your code abbreviated  by  NSxx as you use the ESQL content assist.
• Keep in mind those namespaces may span multiple files.
• Insert all of them using your own naming convention (NSyy) at the top of your SOAP message using the NamespaceDecl 
• Feel free to read more about it in the Infocenter topic here
• Remember to declare all your namespaces at the top of your code because .. well.. Order is important ! right ?.