Hurdles with Document-Style Web Service

Lat week I spent some time prototyping a simple document-style web service. Basically, I wanted to figure out how to pass an XML document with several nested repeating groups to a web service. Apache Axis was the obvious choice for a SOAP engine-I did not want to install anything heavy.

I totally expected it to be a half an hour deal at most — after all, SOAP is already XML, so wrapping my XML message in SOAP envelope should not be a big deal, right?

In reality though, I immediately ran into issues. My first approach was to try to pass an object graph (a la order with line items). Turned out, Axis does not know how to serialize objects in case of “document literal“ service; serialization only works for “soap encoded“. I can understand that-since this is custom XML, rules for serialization are not defined. Although it could‘ve generated some default names based on reflection (I wish we could use annotations for that, but that would have to wait until JAXB 2.0).

Then I tried passing XML as a string (still with “document literal“ in wsdl). Axis had some problems recognizing the name of the operation (basically, the name of the parameter had to match the name of the operation) and then it escaped the XML string (using entities such as “& lt;“). This was not acceptable-I could not count on all clients uniformly escaping their XML before calling the service

So I ended up using DOM and special “message“ style web service that Axis supports-in this case the signature of the service would be “public Document process( Document message )”. This works fine, although I still had to mess with SOAPElement on the client and I could not pass the XML string directly. I actually ended up writing a simple utility class to convert XML string to SOAPElement. Unfortunately, this approach is not portable-WebSphere, for instance, does not support it. So much for JAX-RPC spec support.

This article explains how it should work by the spec but it is obvious that support for at least this part of the spec varies among different implementations.

Morale of the story? “document literal“ web service style is touted everywhere as the “right” way to implement the service but its support leaves a lot to be desired.