Rama Pulavarthi's Blog

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;
bp.setOutboundHeaders(
  // simple string value as a header, like stringValue
  Headers.create(new QName("simpleHeader"),"stringValue"),
  // create a header from JAXB object
  Headers.create(jaxbContext,myJaxbObject)
);

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:

Using @HttpSessionScope: 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.

Using @Stateful: 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 and HttpSessionscope.

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 dev@jax-ws.dev.java.net

Comments

• Rama ,

  Thanks for this fantastic and detailed blog entry. Great work and congratulations on the release of JAXWS 2.1

  Posted by: tjkincaid on February 03, 2007 at 09:36 AM

• Hi Rama, Is it possible to *set* the SOAP Header in endpoint implementation without using SoapHandler framework ?

  Posted by: yogen on April 09, 2007 at 11:15 AM

• Rama, can I set an inbound handler to intercept all incoming messages (i.e. global handler, like axis2) or handlers are service specific only?

  Posted by: massiccio_ita on October 08, 2007 at 03:05 AM

• Hi Rama, I am getting a ClassCastException while using JAX-WS RI 2.1 EA3 provided jaxws-rt.jar at the WSBindingProvider line where I am trying to set an Explicit SOAP Header by downcasting

  McAfeeX0020OrderX0020Processing impl = new McAfeeX0020OrderX0020Processing();
  
  McAfeeX0020OrderX0020ProcessingSoap soap = impl.getMcAfeeX0020OrderX0020ProcessingSoap

  //Downcast to WSBindingProvider
  WSBindingProvider bp = (WSBindingProvider)soap;

  Posted by: vatsa82 on October 16, 2007 at 03:48 PM

• Is there any way to implement a 2-way SSL call in Jax-ws? (both ws consumer and provider are WLS 10.x instances). Is there any property where an SSLAdapter impl can be registered? It used to be there one: http://e-docs.bea.com/wls/docs100/javadocs/weblogic/wsee/jaxrpc/WLStub.html#SSL_ADAPTER

  Your sincerely
  carlo
  

  Posted by: cdrcdr on March 17, 2008 at 09:22 AM

This work is licensed under a Creative Commons License.