Useful Goodies for Web Service Developers in JAX-WS 2.1 RI
JAXWS 2.1 RI comes with bunch of goodies for the ease of use/development of Web Services. Some of these are configurable through system-wide properties, features and annotations in the com.sun.xml.ws.developer package, which means they are proprietary and will not work with other implementations. Who knows, some of these might end up in future versions of the Spec, if you find them useful as we think.
Accessing Inbound SOAP Headers:
To access all the headers (including headers that are not bound to parameters) in the endpoint implementation, one has to write a handler to access those from the SOAPMessage. Instead on can use the read-only property JAXWSProperties.INBOUND_HEADER_LIST_PROPERTY from WebServiceContext directly.
Adding Outbound SOAP Headers:
Sometimes, one may need to send some additional headers that are not defined in the wsdl or bound to parameters. Instead of writing a SOAP Handler and doing the dirty work one can easily do this by downcasting the proxy to WSBindingProvider and set the Outbound headers.
HelloPort port = helloService.getHelloPort();
WSBindingProvider bp = (WSBindingProvider)port;
// simple string value as a header, like
// create a header from JAXB object
As you see Headers are created using com.sun.xml.ws.api.message.Headers class, which provides factory methods to create headers in different wasy easily. More information on using this feature can found in Kohsuke's blog Adding SOAP headers
Creating Stateful Web Services:
One way to bring state to Web Services is to use Http Session cookies. Storing the state and accessing it from the HttpSession (from WebServiceContext) for each request takes multiple steps and does n't fit well with the OO way of accessing/storing it with instance fields.
One can use @com.sun.xml.ws.developer.servlet.HttpSessionScope annotation tells the JAX-WS RI to create one instance of Hello per each HTTP session. As you see this approach still relies on Http cookies but makes it easier to access state from the context just like normal instance variables.
JAX-WS also provides a transport neutral mechanism to do this and makes use of the WS-Addressing standard. It introduces @com.sun.xml.ws.developer.Stateful to take care of maintaining all the state and the user can access it using instance variables. All the user needs to do is to add @Stateful and @Addressing to Web Service implementation. As you see, this is requires support for Addressing.
More information about using this feature can be found from stateful sample in the JAX-WS 2.1 bundle and in Kohsuke blogs Stateful web services with JAX-WS RI
Logging of SOAP Messages:
Web Services developers generally need to see SOAP Messages that are transferred between client and service for debugging. There are couple of SOAP Monitors for this job, but you need modify the client or server code to use those tools. JAX-WS provides logging of SOAP messages by using a System property com.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true on client-side. My blog about Monitoring SOAP Messages talks more about it. If you are using Glassfish, it provides nice GUI tools to montior SOAP messages for Web Service. Unfortunately this works only with 109 based Web Services. For Servlet based WebServices, you can use com.sun.xml.ws.transport.http.HttpAdapter.dump system property to dump the SOAP traffic.
Propagation of Server-side Stacktrace:
This is a very useful feature while developing Web Services. Often the soap fault messages does n't convey enough information about the problem. JAX-WS relieves you from digging out the server logs to find out the stacktrace. Now the whole stacktrace (including nested exceptions) is propagated in the SOAP Fault and the complete exception stacktrace is visible to the client. Propation of Stacktrace is on by default, If you think its not safe for your Web Service Application to send the complete stacktrace, you can turn off this functionality by setting the System property com.sun.xml.ws.fault.SOAPFaultBuilder.disableCaptureStackTrace.
Support for MemberSubmission Addressing:
One can use @com.sun.xml.ws.developer.MemberSubmissionAddressing or com.sun.xml.ws.developer.MemberSubmissionAddressingFeature to use member submission version of Addressing. You can follow the fromjava-wsaddressing sample in JAX-WS 2.1 bundle except that @MemberSubmissionAddressing and MemberSubmissionAddressingFeature is used instead if @Addressing and AddressingFeature.
Most interesting part, all of these features are done using extensions points provided by the JAXWS RI. You can develop similar features using JAXWS pluggability architecture and more on this can be found in my blog Extending JAX-WS With Annotations.
We hope these developer properties and features are useful and make using Web Services a bit easier. Do provide your valuable feedback to firstname.lastname@example.org