Skip to main content

Support for WS-Addressing in JAX-WS 2.1 RI EA1

Posted by ramapulavarthi on September 26, 2006 at 2:29 PM PDT

JAX-WS is undergoing a maintenance release (JAX-WS 2.1) to address some issues based on the feedback from the developer community. One of the new features added in JAX-WS 2.1 is the support for WS-Addressing. Web Services Addressing specification 1.0 [WS-Addressing] defines a mechanism to address Web Services and messages independent of the transport being used.

The proposal is to support WS-Addressing in JAX-WS with a simplified programming model. In most cases, the user does n't need to do anything apart from enabling addressing. I like the idea behind this, as a real Web Service developer would want to work on his business logic than worry about dealing with various addressing headers that are sent in each interaction. I will go over the new annotations that are introduced in JAX-WS 2.1 to enable addressing briefly.

To get your hands on the WS-Addressing implementation in JAXWS 2.1 RI get the EA1 release from here. In the EA1 bundle there are samples fromjava-wsaddressing and fromwsdl-wsaddressing showcasing the use of WS-Addressing with JAX-WS.

For a sample operation in a SEI like this

@WebMethod
public int addNumbers(int number1, int number2) throws AddNumbersException {
        return impl(number1, number2);
}

With addressing, this is how a SOAP request and response would look like.

SOAP Request:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Header>
        <To xmlns="http://www.w3.org/2005/08/addressing">http://localhost:8080/jaxws-fromjava-wsaddressing/addnumbers</To>
        <MessageID xmlns="http://www.w3.org/2005/08/addressing">uuid:6d9d4c99-95c4-41c2-bfb6-17f3f1267644</MessageID>
        <ns1:ReplyTo xmlns:ns1="http://www.w3.org/2005/08/addressing">
        <ns1:Address>http://www.w3.org/2005/08/addressing/anonymous</ns1:Address></ns1:ReplyTo>
       <Action xmlns="http://www.w3.org/2005/08/addressing">http://server.fromjava_wsaddressing/AddNumbersImpl/addNumbersRequest</Action>
     </S:Header>
    <S:Body><ns2:addNumbers xmlns:ns2="http://server.fromjava_wsaddressing/"><arg0>10</arg0><arg1>10</arg1></ns2:addNumbers></S:Body>
</S:Envelope>

SOAP Response:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
    <S:Header>
        <To xmlns="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing/anonymous</To>
        <Action xmlns="http://www.w3.org/2005/08/addressing">http://server.fromjava_wsaddressing/AddNumbersImpl/addNumbersResponse</Action>
        <RelatesTo xmlns="http://www.w3.org/2005/08/addressing" RelatesTo="http://www.w3.org/2005/08/addressing/reply">uuid:6d9d4c99-95c4-41c2-bfb6-17f3f1267644</RelatesTo>
    </S:Header>
    <S:Body><ns2:addNumbersResponse xmlns:ns2="http://server.fromjava_wsaddressing/"><return>20</return></ns2:addNumbersResponse></S:Body>
</S:Envelope>

Don't be scared seeing all those extra headers. You don't need to generate/consume these addressing headers. The job is done by the JAX-WS runtime. So let's see how we can make JAX-WS implementation do it for us.

Starting from WSDL:

If the wsdl uses addressing, the user does n't need to do anything. JAX-WS runtime identifies the <wsaw:UsingAddressing/> in the binding section of the wsdl:definitions and figures out that the Web Service uses WS-Addressing 1.0 as per Web Services Addressing 1.0 - WSDL Binding[WS-Addressing WSDL Binding]. JAX-WS runtime will take care of sending various addressing headers as defined by the Web Services Addressing 1.0 - SOAP Binding[WS-Addressing SOAP Binding].

Starting from Java:

To use addressing from Java, One has to enable the AddressingFeature. JAX-WS 2.1 introduces some new annotations to specify this.

@BindingType:
@BindingType annotation is updated. In JAX-WS 2.0, @BindingType takes a URI identifying the binding, for example "http://schemas.xmlsoap.org/wsdl/soap/http" for SOAP 1.1 over HTTP binding etc. With the updated API, BindingType also takes an array of features (capabilities or extensions) that should be enabled/disabled on the Binding. JAX-WS 2.1 supports Addressing and MTOM feature of SOAP binding. To specify this, @Feature annotation should be used. For any feature, there might be some behaviors that may be configurable as per the User's preference. For this, there is @FeatureParameter to pass such feature configurations.

Here is a sample use of the BindingType annotation that specifies the use of AddressingFeature. It uses the default SOAP1.1/HTTP binding.

   @WebService
   @BindingType(features={@Feature(AddressingFeature.ID)})
   public class MyWebService { ... }

The wsdl generated for this endpoint will have <wsaw:UsingAddressing/> in the wsdl binding definition to indicate that the Web Service uses WS-Addressing 1.0 as per Web Services Addressing 1.0 - WSDL Binding[WS-Addressing WSDL Binding]. This also conveys that the use of addressing is not mandatory, as wsdl:required="false" by default.

Here in the following sample, BindingType annotation enables the AddressingFeature with a feature parameter.

   @WebService
   @BindingType(features={@Feature(value=AddressingFeature.ID, parameters=
	{@FeatureParameter(name=AddressingFeature.IS_REQUIRED, value="true")}) })
   public class MyWebService { ... }

The wsdl generated for this endpoint will have <wsaw:UsingAddressing wsdl:required="true"/> in the wsdl binding definition, which translates to saying that the client/server must use addressing and the endpoint cannot understand SOAP messages without addressing headers.

If you are an experienced Web Service developer and has some other mechanism to handle addressing yourself, you can even disable the feature by setting enabled=false in the Feature annotation.

   @WebService
   @BindingType(features={
                @Feature(value=AddressingFeature.ID, enabled=false)})
   public class MyWebService { ... }

JAX-WS Runtime in the above case leaves it to the user for generating/processing any addressing headers.

@Action and @FaultAction:
These annotations can be used to specify explicit actions attributes for input, output and fault messages. The good thing is in most of the cases, the user does n't need to specify these. Runtime will figure out these action values from the wsdl operation name. Then you may wonder what the real use of this annotation and the corresponding action attribute in the wsdl is. The value specifed in wsaw:Action can be used for the dispatching of requests in transport independent fashion. Action based dispatching is not yet supported in EA, but this will be available soon.

For example, one can use these annotations like this,

  @javax.jws.WebService
  public class AddNumbersImpl {
      @javax.xml.ws.Action(
          input="http://example.com/inputAction",
          output="http://example.com/outputAction",
          fault = {
              @javax.xml.ws.FaultAction(className=AddNumbersException.class, value="http://example.com/faultAction")
          })
      public int addNumbers(int number1, int number2)
          throws AddNumbersException {
          return number1 + number2;
      }
  }
  

The generated WSDL looks like:

    <definitions targetNamespace="http://example.com/numbers" ...>
    ...
      <portType name="AddNumbersPortType">
        <operation name="AddNumbers">
          <input message="tns:AddNumbersInput" name="Parameters"
            wsaw:Action="http://example.com/inputAction"/>
         <output message="tns:AddNumbersOutput" name="Result"
           wsaw:Action="http://example.com/outputAction"/>
         <fault message="tns:AddNumbersException" name="AddNumbersException"
           wsaw:Action="http://example.com/faultAction"/>
        </operation>
      <portType>
    ...
    <definitions>

Refer to JAX-WS 2.1 EA1 Users Guide for more information on the usage of these annotations. Similar to Addressing Feature, MTOM can be enabled using MTOMFeature. JAX-WS 2.1 Specification also proposes programmatic configuration of these features on the client-side. Keep looking for the support for Action based dispatching, MTOM Feature and other new stuff in JAX-WS 2.1

Related Topics >>