Ever since I have been working in the web services space, I have had discussions about the service "style". That is, how do I craft a WSDL contract to make it easy to implement, easy to handle by the SOAP engine and interoperable between different vendor platforms. And even though it is not as much discussed anymore as it used to be, the subject still comes up every now and then. Today, we typically simply state that "wrapped document/literal" style should be applied for all Web services when possible. And usually I have pointed to a developerWorks article written by Russ Butek
that gives an excellent explanation of the topic.
I just stumbled over a further - and formal, i.e. standardized - definition of this style in the JAX-WS specification. It defines a "Wrapper Style" and a "Non-wrapper Style". The wrapper style is defined with the following rules:
A WSDL operation qualifies for wrapper style mapping only if the following criteria are met:
- The operation’s input and output messages (if present) each contain only a single part
- The input message part refers to a global element declaration whose localname is equal to the operation name
- The output message (if present) part refers to a global element declaration
- The elements referred to by the input and output message (if present) parts (henceforth referred to as wrapper elements) are both complex types defined using the xsd:sequence compositor
- The wrapper elements only contain child elements, they MUST not contain other structures such as wildcards (element or attribute), xsd:choice, substitution groups (element references are not permitted) or attributes; furthermore, they MUST not be nillable.
This definition is exactly what we have been using before, so it simply confirms what we used as a best practice and turns it into a standard. The very last rule, saying that there cannot be any wildcards in the wrapper, is interesting. I have come across some examples where so-called extension elements were placed in there, using xsd:any, to preserve a place for future schema extensions. This rule basically requires that such extension elements be placed in yet another wrapper element. and that's probably a good idea anyway. (I have many more thoughts on the use of xsd:any in Web services contracts, but I'll save those for a future entry.)
As a result of this discussion, I decided that I need to do more with JAX-WS. It will quickly become the default way of developing Web services in Java, and this wrapper style is obviously just one out of many interesting and new (well, new to me who is still working predominantly with JAX-RPC)features that I want to explore.