Using JAXB and JAX-WS for service with custom headers

Since the introduction of the JAX-WS in Java EE building SOAP web-services have never been easier (as compared to i.e. Spring WS). Just a few annotations and you are up and running. Disadvantage of this all is that it always goes from a Contract first or Java first approach. While in a lot of environments this is the case, situations are there when its a mixed case.

Just recently I ran into the mixed case. Needed to replace an existing service that did not have any WSDL’s but the XSD’s for the payload was there. The following are the steps I executed to implement the new service from the existing XSD’s and included inbound and outbound headers.

Generating the ObjectFactories from the supplied XSD’s is simple in maven just add the following snippet to the your maven pom file:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>jaxb2-maven-plugin</artifactId>
  <version>1.6</version>
  <executions>
    <execution>
      <id>xjc</id>
      <goals>
        <goal>xjc</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <bindingFiles>
      bindings.xjb
    </bindingFiles>
  </configuration>
</plugin>

That is all to have the JAXB files generated. The bindings file I specified was allows you to customize the generated classes. I tend to convert the xsd:DateTime to JodaTime, but that is just me.

Next the definition of the JAX-WS services. On the Internet there are a lot of guides available to get started with JAX-WS. No point in getting into that. I found that information on dealing with headers is mixed.

• https://metro.java.net/nonav/1.2/guide/SOAP_headers.html
  Solution depends on the com.sun.xml.ws.developer classes. Not where I want to go.
  
• http://www-01.ibm.com/support/knowledgecenter/SS7K4U_8.5.5/com.ibm.websphere.nd.multiplatform.doc/ae/twbs_cookiejaxws.html
  Suggests a solution where the headers are set separately. Does not even answer how to do  inbound headers.
• http://stackoverflow.com/questions/830691/how-do-i-add-a-soap-header-using-java-jax-ws
  Just a sample of the answers that are available on stackoverflow. The solution provided here is the most common.

All the solutions provided will do the trick to get headers in the message. What you do not find a lot is a solution that uses the @WebParam annotation in the argument list of the web service. The annotation has a two important fields for header support; header and mode.

Setting  the header field to true, will add this to the header part of the soap message. the mode flag allows the following values:

• IN
  Inbound
• OUT
  Outbound
• INOUT
  In and Outbound.

The first two are easy to use. the last, INOUT has a bit more to it.

When using the WebParam.Mode.INOUT value changes are high that the container you are running is not able to generate the WSDL and XSD files. The error you get is ambiguous. End result your WSDL is not generated hence the service is not available.  The key when using the INOUT mode is the generic class javax.xml.ws.Holder<T>. When the parameter is placed inside this type. The WSDL is generated correctly.

Resulting @WebMethod method:

 @WebMethod(
        action = "ServiceName",
        operationName = "operation"
    )
    public MyResponse operation(
        @WebParam(mode = WebParam.Mode.INOUT, header = true, name = "JaxbHeader",
                  targetNamespace = "http://www.elucidator.nl/header/v1.0")
        final Holder headerHolder,
        @WebParam(mode = WebParam.Mode.IN, name = "data") final JaxbPayload payload)
        throws MyServiceException
  {
    //SNIP
    if (headerHolder.value.flag) {
       headerHolder.value.field = "SomeValue";
    return responseObject;
  }

Access to the values in the header object is straight forward. when you modify the values the response contains the modified values. With this solution there is no need to write custom  SOAPHandler implementations for headers.

The generated WSDL will be:

<definitions xmlns:ns1="..." xmlns:tns="..." 
     xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
     xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata" 
     name="MyService" 
     targetNamespace="..." 
     xmlns="http://schemas.xmlsoap.org/wsdl/">
    <types>
       //SNIP
    </types>
    <message name="operation">
        <part name="parameters" element="tns:operation"/>
        <part name="jaxbHeader" element="ns1:JaxbHeader"/>
    </message>
    <message name="operationResponse">
        <part name="result" element="tns:operationResponse"/>
        <part name="JaxbHeader" element="ns1:JaxbHeader"/>
    </message>
    <portType name="ServiceName">
        <operation name="insert" parameterOrder="parameters JaxbHeader">
            <input message="tns:operation" wsam:Action="operation"/>
            <output message="tns:operationResponse" wsam:Action="http://www.elucidator.nl/ws/v1.0/operationResponse"/>
        </operation>
    </portType>
    <binding name="ServiceNameBinding" type="tns:ServiceName">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="insert">
            <soap:operation soapAction="operation"/>
            <input>
                <soap:body parts="parameters" use="literal"/>
                <soap:header message="tns:operation" part="JaxbHeader" use="literal"/>
            </input>
            <output>
                <soap:body parts="result" use="literal"/>
                <soap:header message="tns:operationResponse" part="JaxbHeader" use="literal"/>
            </output>
        </operation>
    </binding>
    <service name="ServiceName">
        <port name="ServiceNamePort" binding="tns:ServicePortBinding">
            <soap:address location="http://localhost:9081/Service"/>
        </port>
    </service>
</definitions>

As you can see a nicely generated WSDL that contains information about the headers that are expected and returned.

There is however 1 minor disadvantage with this solution. When an exception is thrown you do not have access to the headers anymore.  I have a solution for this, implementation of a Handler that intercepts the request, stores the header and modifies the fault response in the handleFault method. But that is a subject for an other post.

 

Original can be found on: Elucidator