Over a million developers have joined DZone.

Using JAXB and JAX-WS for service with custom headers

· Java Zone

Thrive in the application economy with an APM model that is strategic. Be E.P.I.C. with CA APM.  Brought to you in partnership with CA Technologies.

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.

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 

Navigate the Maze of the End-User Experience and pick up this APM Essential guide, brought to you in partnership with CA Technologies

Topics:

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}