Howto: JAX-WS service with XML Source input instead of JAXB-produced POJOs (similar to JAX-RPC with SOAPElement input)

Sometimes you may want to create a JAX-WS webservice with its input defined by a proper, structured XSD yet accessing the input as raw XML object and not as POJOs produced by JAXB, similarly as with a JAX-RPC webservice having input of the type SOAPElement. This is possible using @WebServiceProvider with javax.xml.ws.Service.Mode.PAYLOAD.



JAXB input Normally you create a JAX-WS webservice by annotating a POJO with @WebService and related annotations and use JAXB annotations on your domain classes used in input and output of the web service (or you use wsimport and the JAXB compiler to produce these from a WSDL file).

XML input But there is also an alternative way for accessing the input as XML data (not just a string containing XML!), in which case you basically bypass JAXB binding and thus you also don't need to generate any domain classes for your wsdl.

JAX-WS 2.0 specification, section 5.1 javax.xml.ws.Provider (page 77) explains the difference:

Java SEIs [JH: a native Java service endpoint interface] provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.

Implementation example

This is how you would create such a web service, accessing its input as XML data represented by javax.xml.transform.Source:

ExampleRawXmlServiceImpl.java:

package example;

import javax.xml.transform.Source;
import javax.xml.ws.Provider;

@javax.xml.ws.ServiceMode(value=javax.xml.ws.Service.Mode.PAYLOAD)
@javax.xml.ws.WebServiceProvider(wsdlLocation="WEB-INF/wsdl/learningActivity/LearningActivity.wsdl"
	, targetNamespace="http://w3.ibm.com/xmlns/ibmww/hr/learning/lms/br/la"
	, serviceName="LearningActivityHttpService"
	, portName="LearningActivityRawXml")
public class ExampleRawXmlServiceImpl implements Provider<Source> {
	@Override
	public Source invoke(final Source request) {
		// ...
		return null;
	}
}

(You perhaps don't need all the @WebServiceProvider attributes.)

The important things to notice:

• @WebServiceProvider is used instead of @WebService
• The ServiceMode is set to Payload and therefore the class has to implement Provider<javax.xml.transform.Source>. You could set it also to Message, in which case you'd get a complete SOAPMessage and thus you'd need to implement Provider<SOAPMessage>.

Working with the XML data (Source)

You will likely need to convert the input javax.xml.transform.Source to something usable. Here are few examples: Converting Source to XML string:

import java.io.StringWriter;
import import javax.xml.transform.*;
import javax.xml.transform.stream.StreamResult;
...
final StringWriter requestXmlWriter = new StringWriter();
final Transformer trans = TransformerFactory.newInstance().newTransformer();
trans.transform(request, new StreamResult(requestXmlWriter));
final String requestXml = requestXmlWriter.toString();

Converting Source to DOM (copied from [1]):

import javax.xml.transform.dom.*;
import org.w3c.dom.Node;
...
DOMResult dom = new DOMResult();
Transformer trans = TransformerFactory.newInstance().newTransformer();
trans.transform(source, dom);
Node node = dom.getNode();
// do something with it ...
DOMSource src = new DOMSource (node);

Notice there is also javax.xml.transform.sax containing SAXResult and SAXSource.

Resources

1. Article Realizing Strategies for Document-Based Web Services With JAX-WS 2.0: Part 3 in a Series by Sameer Tyagi, 2005 - section Switching Off Data Binding
2. Blog Operating at the XML Message Level in JAX-WS 2.0 by Art Frechette, 2006
3. JAX-WS 2.0 specification (JSR 224)

Tags: java api