Category Archives: Web services

Using XML Validation Framework with Web Services

A good Web service has to have a well defined and enforceable contract. Typically, the contract is expressed using XML Schema language. Unfortunately, up until recently, enforcing the contact was very problematic because of the huge performance overhead associated with running schema validation. XML parsers used to load and parse the schema for every validation request, which was clearly expensive.

This has changed with the release JAXP 1.3 which comes with the schema validation framework which allows to first load and compile a schema and then reuse the compiled version for all subsequent validation requests. This may finally make it feasible to use the schema validation for Web services in production environment.

I decided to prototype the use of the validation framework for my Web services implemented in XFire (you may also want to explore a schema validation component implemented in ServiceMix ESB).

All it took is a fairly simple handler:

public class XFireSchemaValidationHandler extends AbstractHandler {
    private Schema schema = null;
    public XFireSchemaValidationHandler() throws SAXException{

        // Load the schema - note that handler is only
        // instantiated once, so we can keep the schema in 
        // an instance variable
        SchemaFactory factory = SchemaFactory
        // I'm hardcoding the path for now, but we should be able
        // to extract it from the WSDL 
        StreamSource ss = new StreamSource(
                new File("/ws/xfire/etc/person.xsd"));
        schema = factory.newSchema(ss);

	public void invoke(MessageContext ctx) throws Exception {
        InMessage message = ctx.getInMessage();
        XMLStreamReader streamReader = message.getXMLStreamReader();
        // create JDom from the stream - alternatively we can rely on
        // DOM and XFire DOM handler
        StaxBuilder builder = new StaxBuilder();
        Document doc =;
        // get to the body first
        Element body = 
        // we assume that we use "unwrapped" mode and 
        // our payload is the direct child of the body element  
        Element payload = (Element) body.getChildren().get(0);
        // dump the message for testing purposes
        XMLOutputter outputter = 
            new XMLOutputter(Format.getPrettyFormat());
        outputter.output(payload, System.out);
        // create validation handler from the pre-complied schema
        ValidatorHandler vh = schema.newValidatorHandler();
        // the handler only works with SAX events, so we create 
        // SAX from JDom 
        SAXOutputter so = new SAXOutputter(vh);
        // Validator will run as a SAX handler and throw an exception
        // if the validation fails.
        System.out.println("\nValidation passed");
        // rewind the stream reader for subsequent processing 
        message.setXMLStreamReader( new JDOMStreamReader( doc) );

Unfortunately, the validation framework does not currently support StAX, so an XML document has to be parsed using SAX or DOM (or JDom with subsequent SAX conversion which is what I chose to do since it was quicker to develop that way). I'm sure this conversion (and the validation process itself) adds some performance overhead, but I'm hoping that it won't be too bad, especially for simple schemas (and from my experience 90% of all Web services have very simple messages). JAX-RPC-compliant Web services engines should see even less of performance penalty since everything is loaded into DOM from the get-go. Perhaps I'll try to run some performance tests and see what happens.

Using XFire as a Client for WebSphere Application Server

XFire has great easy-to-use client API, which makes it an ideal candidate for developing unit tests for Web services. The best part is that it can interoperate with Web services implemented in other containers and application servers. I recently started using it with IBM WebSphere Application Server (WAS) 6.1.

So what are the benefits of using XFire as opposed to a "native" Web services client created using tools provided with your application server?

  • Many application servers/Web service containers use code generation to generate a client's "proxy". You have to remember to re-gen the client every time you change interface of your service.
  • Code generation has a number of issues. For example, a client generator will generate Java classes for parameters of a Web service. Oftentimes, it is desirable to use an existing class instead, so then the generated code must be changed.
  • Using "native" client does not test interoperability. When client and server are implemented using the same product, interoperability is almost guaranteed. Using a different client library potentially allows you to discover interoperability problems early on.
  • Finally, since XFire is open source, it can be packaged and distributed to customers and partners without requiring a license.

Invoking a Web service running in WebSphere does not require anything special:

public void testHelloService() throws Exception {
    Service serviceModel = new ObjectServiceFactory()
    XFireProxyFactory serviceFactory = new XFireProxyFactory();
    HelloService_SEI service = (HelloService_SEI) serviceFactory
        .create( serviceModel, 
    Person person = new Person();
    String s = service.helloPerson(person); 
    assertEquals("Hello John Doe", s);

It must be noted though that I have not tried using any advanced features. It would be interesting to see if, for example, XFire WS-Addressing implementation can interoperate with WAS.

By the way, if you're only going to use XFire client, you only a need few jars from its distribution. Here is the list that I use (it could probably be trimmed down even more):


Also, from my expreience SAAJ API only works with Sun JDK as opposed to JDKs provided by IBM as part of Rational development tools.

Choosing Between Axis2 and XFire

I used Axis 1.X in the past (not without some problems, but I was able to get the work done), and so when I needed an open source Web services stack, downloading Axis2 was my first impulse. Then, after playing with it for a short while, I had an afterthought and decided to look at XFire. I never looked back. Here are some things that made my decision not in Axis2 favor (there is actually a WS stack comparison on XFire site but I wanted to see for myself):

  • No JAX-WS or annotations support. I'm not even sure if Axis2 fully supports JAX-RPC for that matter, at least it was not obvious from the docs. I'm not a big fan of JAX-RPC (and who is?) but sometimes being able to use standard APIs is a plus.
  • Deployment model. Why invent a new "aar" archive type? So does it mean that now I have to run Ant (or the special AAR Eclipse plugin) to re-package my service every time I change a class? (It might be possible to put the exploded archive on the classpath but I did not try that.) How will this new component type integrate with app servers? How will the classloading work under different J2EE containers?
  • Data binding. It looks like there is some databinding support for the new AXIOM XML object model, but all examples use Axiom directly, so it was not very clear how to use it (at least not without resorting to WSDL2Java generator). Also, I don’t believe there is an ability to plug in different databinding frameworks such as Jaxb or Castor.

I'm sure Axis2 has a lot of good capabilities, its feature list seems impressive enough. But for now I will be sticking with XFire simply because it's somewhat easier to setup, its API seems more intuitive, it integrates well with different conainers/app servers and also because of its JAX-WS support.

Web Services and Publishing Schema

Good Web service design starts with a schema. Binding, port type and all these other parameters of a WSDL file usually are not interesting at all – 99.9% of all services have trivial SOAP bindings, no headers and no declared faults. Also, majority of Web services today are document-style with one “part” per message. So schemas of input and output messages are really the key to understanding what service is about. In other words, schema truly defines the contract of a service.

There is no substitution for the schema – you can’t generate a good schema from a source code or a UML class diagram since they do not convey optionality, restrictions, patterns, element model (sequence or choice) and other aspect. XML Schema is verbose and complex (and that’s a topic for another post), but it is pretty expressive as far the data typing goes.

So I usually start a service design with a well-documented schema. The question is, however, how to then publish it so other people can review it (you know, people who represent service consuming applications – these folks are kind of important). Reviewing a schema in a “raw” format is out of question, especially if business people are involved. So a nicely formatted HTML documentation which could present the schema in a readable format (ideally, translating schema lingo into plain English, such as “minOccur=0 ” could translate into “optional”) is the way to go.

I suspect that SOA registries, such as Infravio, can take care of this problem. But oftentimes there is a need to prototype a solution quickly before SOA infrastructure is put into place. Also, at this day and age, open source/free/inexpensive tools might be a requirement for many projects.

The best known Schema documentation generator is xnsdoc. It is not free, but 49 EUR seems like a reasonable price. xnsdoc has an open source XSLT-based counterpart with fewer capabilities. xnsdoc does produce nice documentation along the lines of JavaDoc format (although I’m not convinced that this is the best choice – remember, the documentation has to be suitable for non-developers), however, in my view it does not do much in terms of explaining the schema in plain English. In other words, the assumption is that users are familiar with Schema concepts. I also found that the support for groups and multi-files schemas had some problems (but keep in mind that I’d done my testing almost a year back, so please check the latest version)

A better tool that I found is Bluetetra XSDDoc (99 USD). In my view, it provides more user-friendly schema documentations. You can see some examples here. Unfortunately, it is not clear if XSDDoc is still actively supported – its website provides only minimal information and the product has not been updated in a while.

I still think that there is a need for more interactive Wiki-style schema publishing tool that would allow users reviews schemas expressed in layman terms and comment on elements and types.

REST Support in JAX-WS

I was intrigued by the REST support in JAX-WS. REST style could be very useful in certain situations, not to mention the fact that there are already many REST-style services out there.

While I don’t want to get into SOAP vs. REST debate here I still want to quickly mention one very important REST advantage, which is security.

Since each service call operation in REST is an HTTP GET URL, it makes it easy to use traditional Web authorization schemes, including Apache mod_authnz or J2EE declarative security defined in web.xml. Contrast that with SOAP, which requires looking inside the message to figure out what security policy should be applied. Another side of it is auditing and monitoring. With REST I can easily see all the details of the requests to my web service operations just by looking at the Web server’s access log and/or using one of the numerous log analysis tools. SOAP does not give me this information automatically; different application servers and ESB products may provide these capabilities, but there is no guarantee (since it is not part of any specification).

In any event, REST has its place and so it’s nice to see that JAX-WS authors recognized it.

Unfortunately, upon closer examination, it turned out that REST support in JAX-WS is pretty shallow. REST is really a second class citizen compared to SOAP. Here’s why I came to this conclusion:

  • Automatic WSDL generation (when using annotations in service implementation class) is not supported. I was expecting to see the support of HTTP GET binding defined in WSDL 1.1, but it is not there. In general, the spec does not mandate any WSDL to Java or Java to WSDL binding support for REST.
  • Object serialization/deserialization is not supported either. This is not unexpected since mapping of a complex object graph to name/value pair GET string may be non-trivial. But I don’t see a problem of doing it for simple flat objects that don’t have nesting.
  • Consequently, in order to use REST, one has to rely on dispatcher API on the client and so the query string has to be created manually. Same is happening on the server where developers have to use WebServiceContext and parse the query string manually.
In short, using REST requires some low-level programming; its support is clearly limited compared to SOAP.

What I would like to see is the ability to implement a RESTful service by simply adding @BindingType(value=HTTPBinding.HTTP_BINDING) annotation without having to make any other changes relative to a regular SOAP service (or client). Clearly, we’re not there yet.

Tags: , ,

JAX-WS and Annotations: Looking Good

Lately I’ve been playing with JAX-WS reference implementation (version EA3). JAX-WS is the next version of JAX-RPC (i.e., JAX-WS is renamed JAX-RPC 2.0) and it comes with many interesting features, including annotations, HTTP binding, MTOM, asynchronous client operation, direct access to XML stream (finally!) and others.

In this entry I will focus on annotations. Annotations allow developers to configure binding, handler chains, set names of portType, service and other WSDL parameters. This makes it possible to use “Java to WSDL” approach as the primary way for developing Web services (for the server side). Previously with JAX-RPC I was leery of this approach since it was not possible to “fine tune” generated WSDL file.

Annotations greatly simplify Web services development process. For the server side, JAX-WS only generates a wrapper class for the parameters of the service operation. If “bare” (“unwrapped”) mode is used, then no code is generated and so this step can be skipped completely (in other words, all annotations will be handled at run time). This makes it easy to do all development from IDE, for example in my case I deploy to Tomcat and I use Eclipse with Sysdeo plugin, and so I was able to change the code in my Web service class without having to restart the server.

Changing annotations themselves does require bouncing the server, but still there is no code generation involved and so there is no build file to run.

Note that code generation is still required for the client side unless dynamic API is used.

Finally, here is an example of a simple Web service that takes Person object and returns concatenated full name.

import javax.jws.WebService;
import javax.jws.soap.SOAPBinding;

    // Name maps to PortType in WSDL. Default is the name 
    // of the class which is not very intuitive
    name = "PersonService",
    // by default, the namespace is derived from the Java package 
    // name which is not always desirable
    targetNamespace = "",
    /* I use the "Endpoint" suffix as it is better convey the 
     * meaning of this parameter in WSDL and also since this 
     * will be the name of the "factory" class generated for the 
     * client side. The default is the name of the class + "Service"

 * Note that document/literal/wrapped is the default, but using  
 * "bare" as opposed to "wrapped" allows to avoid code generation.          
public class PersonServiceImpl {
    public java.lang.String produceFullName( Person person) {

        return person.getFirstName()+" "+person.getLastName();

Tags: , ,

Client Library as WSDL Alternative

I think that it‘s time for us to start learning from the successes of public Web services, such as Google maps, Ebay and Amazon. Let‘s face it, today enterprise SOA implementations are still in infancy. Most organizations are just testing waters, developing prototypes and implementing pilot projects.

At the same time, Google maps, Ebay and Amazon Web services have been tremendously successful. I know that Google maps example has already been overused by the “Web 2.0” hype, but it is indeed pretty amazing. I subscribe to Google maps mania blog and there are several new “mashup” applications being announced every day. So how do these service providers manage to keep their diverse array of clients happy?

I think that the most important distinction of a successful Web service provider is that it goes above and beyond just publishing WSDL and schema files. These service providers take time to develop detailed samples, documentation and clients libraries. For example, Ebay provides client libraries for Windows, Java, Perl and so on. Google maps is obviously JavaScript. Google search is exposed using WSLD/SOAP but there are also client libraries for Java and .NET that hide complexities of WSDL. Amazon provides entire Associate Engine application written in Perl to interface with its Web services.

This goes against the common view that WSDL /Schema of a service provides complete service definition. This view also suggests that all that a service provider needs to do is to announce its WSDL to the world (or to a community of customers/partners) and the world will immediately adopt the service. This approach shifts the responsibility of implementing the code to access a service (client library or SDK ) to the clients. And for a complex WSDL (or multiple WSDLs), this may mean a lot of effort (especially if we take testing into account). We all know how tricky it is to develop an elegant API . Code generators typically don‘t do a very good job, or they are too inflexible. Just look at code generators supplied with today‘s JAX -RPC implementations that all insist on generating Java objects from schema. Besides, letting the clients develop the code does not allow service provider to implement validations on the client side, as I pointed out in my previous entry.

I think that successful SOA implementations will rely on the clients libraries developed by service providers. These libraries will utilize features of the target language and incorporate some client-side logic. They will also ensure interoperability. These libraries could also take into account capabilities of the client‘s underlying application server or platform. For example, a client library can utilize WS-ReliableMessaging if the client’s application server supports it.

As a result, the role of WSDL will diminish greatly. WSDL has many problems, including its hard-to-comprehend name-based links, verbosity and incompleteness (for example, it does not explain if any of WS-* specs, such as WS-Security, must be used in order to be able to access a service). Client libraries can fix these problems and shield users of a service from having to deal with low-level details of WSDL and WS-* specs.

Tags: ,

Design by Contract for Web Services

Contracts are important for Web services. Design by contract (DBC) is nothing new, but, unfortunately, formal precondition and postcondition specifications have never become mainstream, at least not in the way they were presented by Bertrand Mayer in Object Oriented Software Construction.

However, with the advent of Web services, I think it‘s time to re-introduce DBC to the mainstream. Here‘s why:

  • From a client‘s prospective, testing and debugging a Web services call is much costlier than a local method call. For example, service providers may restrict the number of calls per day in test environment, so trial and error may not be an option. So it is important for a client to be able to understand exactly what is required from the clients (precondition) and what is returned by the service (postcondition).
  • Web services can be exposed to a very wide range of clients that use different technologies. So it is important for service providers to be able to unambiguously define the contract with the clients to simplify error and exception processing by potentially separating (externalizing) validation logic from the service‘s business logic.

Preconditions and postconditions for Web services must support the following capabilities:

  • Validation of input and output parameters. This is partly addressed by the Schema, but that are many types of validations that can‘t be expressed using Schema, such as cross-field or cross-parameter validations (e.g., “endDate > beginDate“). Postconditions should also be able to validate the outputs relative to the inputs, e.g., “resultFlightDate>=requestedDate“.
  • Preconditions and postconditions should be able to validate the state of the service. Classical Meyer‘s example is a stack class with “remove“ operation where the precondition states the stack must not be empty. In Web services world, oftentimes there is a need to specify dependencies (so they would be clear to the clients) between calls to different operations, e.g., operation “b“ can only be called after operation “a“ was called. BPEL can do some of it but only on a very limited scale. And BPEL is not really a validation tool.
  • Precondition and postcondition checks can run on the server or on the client. In test environment it might be beneficial to run them on the client for faster development.

So what is the solution? I‘m hoping that at some point DBC will find its way into one of the numerous WS specifications. For example, there are some “traces” of DBC in the newly announced WS-Semantics. Although at this point WS-* specifications proliferate at such speed that I doubt that anyone can keep up with them (except, of course, vendors and standard organizations who keep churning them out) so it may do more harm than good.

So the easiest solution for the time being could be for service providers to actually develop client libraries that implement preconditions (and may be even postconditions). This will allow the clients to deal with APIs (and perhaps the source code) expressed in the language that they understand instead of having to deal with bare-bone WSDL which has to be translated into the target language anyway. These libraries can even include “stubbed” versions of the services that can run entirely on the client for testing purposes. Yes, it‘s more work for service providers, but, realistically, how many different languages/platforms are we talking here? In enterprise it probably boils down to various flavors of J2EE and .NET. There are also Python, PHP , Ruby and JavaScript for AJAX clients. For a commercial service provider, the cost of developing these fairly simple client libraries will be returned many times over by the added convenience for the clients. For an example, just look at pygoogle and other Python wrappers for popular Web services. Granted, this approach does not fully address my second requirement for state validation (although it can be done using a smart client library), but I think it‘s a good start nevertheless.

Tags: , ,

To SOAP or Not To SOAP : That is The Question

SOAP gets mentioned every time people talk about Web services. SOAP is almost always considered an integral part of any “serious” Web services implementation, especially if there is also a desire to use WSDL.

But it does not have to be. WSDL 1.1 has HTTP binding support and this support will be beefed up in WSDL 2.0. Granted, the support for WSLD HTTP binding is not very good right now, for example JAX-RPC does not mandate it at all (SOAP binging and SOAP with Attachment are the only two requirements). Assuming the support for HTTP binding will improve or if using WSDL is not even a requirement (after all, a service can be described using “plain English”, as long as developers can understand this description), how should one decide whether to use SOAP?

To me, it all comes down to metadata. The main purpose of SOAP (in case of document-style services) is to provide a place where to put message metadata. This place is SOAP header. WS-Security digital signature, WS-Addressing headers or application-specific metadata all belong there. Today, many (if not most) Web services implementations don’t use SOAP headers and so for these implementations SOAP is just overhead and added complexity (just try get direct access to the InputStream of the message payload in any JAX-RPC-compliant implementaiton). Without anything in the header, SOAP does not have any advantage over good old XML over HTTP “post” (assuming that there is a schema for this XML).

One can argue that SOAP engines also provide XML mapping to the host language primitives, i.e., mapping to/from objects. I personally think that XML mapping capabilities must be de-coupled from SOAP processing. A good XML mapping framework should work with any XML source (in fact, this is exactly where JAX-WS, which is the next version of JAX-RPC is going). A developer must have a choice of receiving “raw” XML from SOAP engine or converting this XML into objects using a framework of his/her choice (e.g., what if I want to use Castor instead of JAXB), I really don’t understand why SOAP engine should make this choice for me.

Just to confirm my point that SOAP is not a requirement for a successful Web service implementation, here is the list of Internet heavyweights and their use of SOAP versus XML. Note that none of them (as far as I know) use WSDL HTTP binding, WSDL is only used when SOAP is used.

Yahoo(maps, search, Flickr, Upcoming, etc.) X
Google maps X (JavaScript)
Google searchX 
Blogger X
PayPalX X
MSN SearchX 

Of course, SOAP has some other benefits, such as solid tool support. SOAP also provides SOAP encoding (for RPC-style services), although the document style is quickly taking over. But is SOAP absolutely required to implement a “proper” Web service? I don’t think so.

Implementing Document-style Web Service with Sun’s JWSDP

I‘m currently using JWSPD to develop some prototypes and I thought it might be useful to document a few things that are not immediately clear from the documentation (at least, they were not to me).

Why use Sun’s JWSDP (JAX-RPC Standard Implementation)?

  • From my experience, it has better WSDL and document-style web services support than Axis. For example, you can read this article or my blog entry about the problems that Axis has with document/literal services (alhough these problems might be fixed in Axis2).
  • It‘s a reference implementation which should have better JAX -RPC compliance.

On the downside, JWSDP is more difficult to use than Axis, you have to use “wscomplile“ and “wsdeploy“ tools and it takes some time to set it up.

First of all, you probably want to run JWSDP under the latest version of the Jakarta/ Tomcat. JWSDP documentation says that it requires modified Tomcat 5.0 which you can download from Sun‘s website (or Sun‘s application server), but you don‘t need it. From my experience, it works with jakarta-tomcat-5.5.9 just fine. You just need to pull all JWSDP jars under “WEB-INF/lib”. Here is the list (I may have some extras there, I did not try to figure out which ones are not needed):


You need to read this article first to understand the difference between wrapped and unwrapped mode.

I‘m assuming that you‘ll be generating Java classes from WSDL , not the other way around.

  • If you‘re implementing document/literal service with wrapper (JAX-RPC style):
    This is the default in JWSDP . From my experience, JWSDP uses this style even if operation name does not match the outer element name in the schema as prescribed by JAX -RPC.
  • If you‘re implementing document/literal non-wrapper (WS-I style):
    You need to use “-f:wsi“ to switch to this mode. Note that in this case you must use model file (“-model“). Model file is used to pass the information to “wsdeploy“ utility. “wsdeploy“ calls “wscompile“ under the covers, but you can‘t directly set “wscompile“ options on “wsdeploy“ command line. Model file is what‘s used to pass these options to “wsdeploy“. Also, don‘t forget to use “-f:wsi“ for the client‘s stub generation (“-gen:client”) option.

Finally, a sample build file is available here.

Tags: , , ,

Are Web Services Suitable for SOA?

SOA may mean different things to different people (to me, SOA is just an architectural style), but one thing is certain – SOA is being touted as the next generation enterprise integration technology and architecture. And yes, SOA is not all about Web services; however, Web services (SOAP and WSDL specifically) are immediately brought into conversation when SOA is mentioned.

But do Web services today provide necessary enterprise-level capabilities?

Take transaction support. Ideally, we should be able to wrap any access to a remote resource in a transaction since remote resources are prone to failing. In J2EE , this is certainly supported for JMS , JDBC and RMI . Yes, two-phase commit comes at a price, but it‘s nice to have it available when it‘s needed. Now, SOA is all about remote calls (synchronous or asynchronous, does not matter). So where is the transaction support? Well, there is WS-AtomicTransaction specification that in theory should provide it. But where are the products that support it today? Also, this specification is not currently part of any WS-I profile, so interoperability is a big question.

WS-ReliableMessaging is in the similar situation, and so the rule of thumb today is that Web services should conform to WS-I basic profile, which does not include any of the advanced specifications.

In theory, one could use SOAP over JMS supported by many J2EE vendors today which immediately makes SOA implementation more robust. But this approach is hardly interoperable with non-Java technologies and what is it really buying for J2EE applications? JMS is already an abstraction of the messaging middleware, so why do we need another abstraction on the top of it?

I concede that describing JMS destinations using WSDL might be useful for some environments, but in many cases it is simply overkill (if you must use BPEL , use the BPELJ variant which directly supports JMS ).

Using JAX-RPC or WSIF to communicate with JMS does not sound like a good idea either. These APIs are not JMS -aware, so, for example, how do I get/set messageID or correlationID?

I do realize that developing true enterprise-level integration technologies takes time, and so perhaps in a couple years most Web services products will provide WS-Transaction and WS-ReliableMessaging support out of the box. But are Web services really ready to take on the enterprise today?

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.