JAX-WS RI 2.2.5 -- WS-Addressing in JAX-WS 2.1

# Java TM API for XML Web Services
(JAX-WS)
WS-Addressing in JAX-WS 2.1

Specification Version: 2.2
Implementation Version: 2.2.5

- Overview
- Provider
- AsyncProvider
- Dispatch
- Asynchronous Client
- Handler
- MTOM and Swaref
- SOAP 1.2
- WSDL Customization
- Annotations
- WS-Addressing
- Stateful Webservice
- Catalog
- Interoperability

## Contents

## 1. WS-Addressing in JAX-WS RI

Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. JAX-WS 2.2 specification requires support for W3C Core, SOAP Binding and Addressing 1.0 - Metadata specifications and defines standard API to enable/disable W3C WS-Addressing on the client and service endpoint. In addition to that, JAX-WS RI also supports Member Submission version of WS-Addressing. The member submission version is supported in an implementation specific way. For compatility with JAX-WS 2.1 behavior, JAX-WS RI 2.2.5 also supports wsdls conforming to WSDL Binding specification. The subsequent sections describe how the two WS-Addressing versions can be enabled/disabled on client and server side .

## 2. Why WS-Addressing ?

This document explains what is WS-Addressing and why it is required.

## 3. Describing WS-Addressing in WSDL

WS Addressing 1.0- Metadata defines standard ways to describe message addressing properties like Action, Destination in wsdl and also indicate the use of Addressing in wsdl. WS-Addressing Metadata specification replaces the previous Web Services Addressing 1.0 - WSDL Binding specification in candidate recommendation earlier. If you are still using wsdls conforming to WS Addressing 1.0 - WSDL Binding specification, skip to the next section. Still you may want to update your wsdls to use in standard ways defined by the W3C recommended Addressing 1.0 - Metadata specification for better interoperability. Also, There is no standard mechanism to describe Member Submission version support in the WSDL and some implementaions have used WS-Policy to indicate the support of member submission version and JAX-WS RI understands such assertion.

### 3.1. WS-Addressing 1.0 - Metadata

Addressing 1.0 - Metadata specification uses Web Services Policy Framework ( WS Policy 1.5) and Web Services Policy - Attachment [ WS Policy 1.5 - Attachment] specifications to express the support of Web Services Addressing 1.0. A new policy assertion <wsam:Addressing> is defined to express the support of Addressing. The wsam:Addressing policy assertion applies to the endpoint policy subject and may be attached to wsdl11:port or wsdl11:binding.

Indicating the requirement of WS-Addressing:
When <wsam:Addressing> is present in a Policy alternative, one is required to use WS-Addressing to communicate with the subject.

Indicating the support of WS-Addressing:
<wsam:Addressing wsp:Optional="true"> can be used to indicate support for WS-Addressing but does not require the use of it.In these cases, there are no restrictions about the use of WS-Adressing.

In certain cases, the endpoint can lay some restrictions to indicate the messages it can accept with WS-Addressing. Nested asertions can be used to restrict the use of response endpoint inside the <wsam:Addressing> assertion.

Requiring the use of Non-Anonymous response endpoints:

    <wsam:Addressing>
        <wsp:Policy>
           <wsam:NonAnonymousResponses/>
        </wsp:Policy>
    </wsam:Addressing>

can be used to indicate that the subject requires WS-Addressing and requires the use of non-anonymous response EPRs. In this case, the response endpoint in the request messages will have to use something other than the anonymous URI as the value of address. This is typically used when the response needs to be sent to a third entity other than the client and service and the response is sent to the non-anonyous URI through a new connection
Requiring the use of Anonymous response endpoints:

    <wsam:Addressing>
        <wsp:Policy>
           <wsam:AnonymousResponses/>
        </wsp:Policy>
    </wsam:Addressing>

can be used to indicate that the subject requires WS-Addressing and requires the use of anonymous responses. In this case, the endpoint requires request messages to use response endpoint EPRs that contain the anonymous URI ("http://www.w3.org/2005/08/addressing/anonymous") or None URI ("http://www.w3.org/2005/08/addressing/none") as the value of address.

### 3.2. WS-Addressing WSDL Binding

W3C WS-Addressing WSDL Binding defines an extensibility element, wsaw:UsingAddressing, that can be used to indicate that an endpoint conforms to the WS-Addressing specification. JAX-WS RI generates this extension element in the WSDL if W3C WS-Addressing is enabled on the server-side. On the client side, the RI recognizes this extension element and enforce the rules defined by the W3C specification. This extensibility element may be augmented with `wsdl:required` attribute to indicate whether WS-Addressing is required (true) or not (false).

W3C WS-Addressing WSDL Binding defines `wsaw:Anonymous` element which when used in conjunction with `wsaw:UsingAddressing` define assertions regarding a requirement or a constraint in the use of anonymous URI in EPRs sent to the endpoint. The WSDL Binding defines three distinct values: `optional`, `required` and `prohibited` to express the assertion. The default value of `wsaw:Anonymous` (equivalent to not present) is `optional`. An operation with `required` `wsaw:Anonymous` value is shown below:

    <wsaw:UsingAddressing wsdl:required="true"/>
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
      <operation name="addNumbers">
        <soap:operation soapAction=""/>
        ...
        <wsaw:Anonymous>required</wsaw:Anonymous>
      </operation>
    <soap:binding>

In this case, a message received at the endpoint, for this operation, with a non-anonymous ReplyTo or FaultTo EPR will result in a fault message returned back to the client with `wsa:OnlyAnonymousAddressSupported` fault code.
There is no such equivalent feature in Member Submission WS-Addressing.

## 4. Configuring Addressing on Endpoint

This section describes how W3C and Member Submission WS-Addressing can be enabled/disabled on the server-side.

### 4.1. Starting from WSDL

Starting from WSDL, If the wsdl contains the above described metadata to indicate use addressing at endpoint scope, Addressing is enabled on the server-side. See Describing WS-Addressing in WSDL section for more details.

### 4.2. Starting from Java

This section describes how WS-Addressing can be enabled/disabled if you develop an endpoint starting from a Java SEI.

By default, WS-Addressing is disabled on an endpoint starting from Java. If that is the expected behavior, then nothing else needs to be done. In that case any WS-Addressing headers received at the endpoint are treated like SOAP headers targeted for the appliaction and are ignored.

#### 4.2.1. Addressing annotations

If WS-Addressing support needs to be enabled on an endpoint, then along with `javax.jws.WebService` annotation, `javax.xml.ws.soap.Addressing` annotation need to be specified for enabling W3C WS-Addressing. If Member Submission WS-Addressing needs to be enabled then `com.sun.xml.ws.developer.MemberSubmissionAddressing` annotation needs to be specified on the service endpoint. For example, the service endpoint in `fromjava-wsaddressing` sample looks like:

    @javax.xml.ws.soap.Addressing
    @javax.jws.WebService
    public class AddNumbersImpl {
    ...
    }

To enable, Member Submission WS-Addressing, the SEI definition needs to be changed to:

    @com.sun.xml.ws.developer.MemberSubmissionAddressing
    @javax.jws.WebService
    public class AddNumbersImpl {
    ...
    }

Once WS-Addressing support is enabled on a service endpoint, then:

- In the generated WSDL, corresponding metadata as described in section Describing Addressing in WSDL is generated.
- All WS-Addressing headers are understood, i.e. if any WS-Addressing header is received with a `mustUnderstand="1"`, then a mustUnderstand fault is not thrown back.
- All WS-Addressing headers received at the endpoint are checked for correct syntax, for example an error is returned back if `wsa:ReplyTo` header does not match the infoset defined in the corresponding specification.
- If any WS-Addressing header received at the endpoint is not of correct cardinality, then an error is returned back to the client.
- If `wsa:Action` header value does not match with that expected for that operation, then an error is returned back to the client.
- Any response message sent back to the client contains the required WS-Addressing headers.

#### 4.2.2. Is Addressing Optional or Required ?

Both `javax.xml.ws.soap.Addressing` and `com.sun.xml.ws.developer.MemberSubmissionAddressing` annotations take two optional Boolean parameters, `enabled` (default true) and `required` (default false). If `required` is specified true, then WS-Addressing rules are enforced. Otherwise the inbound message is inspected to find out if WS-A is engaged and then the rules are enforced. See When is WS-Addressing engaged? section for more details on enforcement furing runtime.

For example, to enforce Member Submission WS-Addressing rules on the server side, the above code sample will change to:

    @com.sun.xml.ws.developer.MemberSubmissionAddressing(enabled=true, required=true)
    @javax.jws.WebService
    public class AddNumbersImpl {
    ...
    }

## 5. On the client side

This section describes how WS-Addressing can be enabled/disabled on the client-side. JAX-WS RI follows the standard extensibility elements in WSDL to enable WS-Addressing support on the client side. In addition, it also allows the client to instruct JAX-WS RI to disable WS-Addressing processing. The assumption is that in this case the client has it's own WS-Addressing processing module. For example, a Dispatch-based client in MESSAGE mode may be used to perform non-anonymous ReplyTo/FaultTo processing.

### 5.1. Implicit behavior

As defined in Describing WS-Addressing in WSDL, If the WSDL contains metadata about the support or requirement of WS-Addressing, JAX-WS RI runtime enables Addressing feature on the client-side.

- Generates `Action`, `To`, `MessageID` and anonymous `ReplyTo` headers on the outbound request.
- Any WS-Addressing headers received on the client are processed.

There is no standard extensibility element for Member Submission WS-Addressing and so there is no implicit behavior defined. It can only be explicitly enabled as described in the next section.

### 5.2. Explicit enabling

If a WSDL does not contain WS-Addressing standard extensibility element, then either W3C WS-Addressing or Member Submission WS-Addressing can be explicitly enabled using `createDispatch` and `getPort` methods on `javax.xml.ws.Service`. The following new APIs are added in JAX-WS 2.1:

- `<T> Dispatch<T> createDispatch(javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)`
- `Dispatch<java.lang.Object> createDispatch(javax.xml.namespace.QName portName, javax.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features)`
- `<T> T getPort(java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)`
- `<T> T getPort(javax.xml.namespace.QName portName, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)`

Each method is a variation of an already existing method in JAX-WS 2.0. The only addition is an extra var-arg `javax.xml.ws.WebServiceFeature` parameter. A `WebServiceFeature` is a new class introduced in JAX-WS 2.1 specification used to represent a feature that can be enabled or disabled for a Web service.

The JAX-WS 2.1 specification defines `javax.xml.ws.soap.AddressingFeature` to enable W3C WS-Addressing on the client side. In addition, the JAX-WS RI also defines `com.sun.xml.ws.developer.MemberSubmissionAddressingFeature` to enable Member Submission WS-Addressing on the client side.

For example in `fromjava-wsaddressing` example, in order to enable W3C WS-Addressing on a proxy, `wsimport` is used to generate the `AddNumbersImplService` class. Then a port can be obtained using the `getAddNumbersImplPort` method and passing an instance of `javax.xml.ws.AddressingFeature`. The code looks like:

`new AddNumbersImplService().getAddNumbersImplPort(new javax.xml.ws.AddressingFeature());`

Similarly, a Dispatch instance with Member Submission WS-Addressing can be created as:

`new AddNumbersImplService().createDispatch(
new QName("http://server.fromjava_wsaddressing/", "AddNumbersImplPort"),
SOAPMessage.class,
Service.Mode.MESSAGE,
new com.sun.xml.ws.developer.MemberSubmissionAddressingFeature());`

Feature Parameters

Both `javax.xml.ws.soap.AddressingFeature` and `com.sun.xml.ws.developer.MemberSubmissionAddressingFeature` take two optional Boolean parameters, `enabled` (default true) and `required` (default false). If enabled, all WS-Addressing headers are generated for an outbound message. If `required` is specified true, then WS-Addressing rules are enforced for inbound message. Otherwise the inbound message is inspected to find out if WS-A is engaged and then the rules are enforced.

For example, to enforce Member Submission WS-Addressing rules on the client side, the above code sample will change to:

    new AddNumbersImplService().getAddNumbersImplPort(new com.sun.xml.ws.developer.MemberSubmissionAddressingFeature(true, true));

### 5.3. Explicit disabling

A client may like to instruct JAX-WS RI to disable WS-Addressing processing. The assumption is that in this case the client has it's own WS-Addressing processing module. For example, a Dispatch-based client in MESSAGE mode may be used to perform non-anonymous ReplyTo/FaultTo processing.

WS-Addressing processing can be explicitly disabled using one of new methods added to JAX-WS 2.1 specification as defined in Section 3.2. For example, W3C WS-Addressing processing can be disabled using the following code:

`new AddNumbersImplService().getAddNumbersImplPort(new javax.xml.ws.AddressingFeature(false));`

## 6. When is WS-Addressing engaged?

W3C WS-Addressing SOAP Binding defines that if a receiver processes a message containing a `wsa:Action` header, then SOAP Binding is engaged, and the rules of the specification are enforced. In JAX-WS RI, if WS-Addressing is explicitly disabled then the RI does not follow the rules of engagement. However if WS-Addressing is either implicitly or explicitly enabled then JAX-WS RI engages WS-Addressing based upon the presence of `wsa:Action` header. JAX-WS RI follows same rule for Member Submission version as well.

In effect, if an endpoint advertises WS-Addressing is required in the WSDL and a client does not send any WS-Addressing header then no WS-Addressing fault is returned back to the client. However if the client send `wsa:Action` header then the endpoint will enforce all the rules of the specification. For example, if the `wsa:MessageID` header is missing for a request/response MEP then a fault with appropriate code and sub-code is thrown back to the client.

## 7. Associating Action with an operation

### 7.1. Implicit Action

In most common cases, an implicit Action association, as defined by W3C WS-Addressing 1.0 - Metadata and Member Submission, will be sufficient. For such cases, only using the correct annotation to enable Addressing is required. The client looking at such a WSDL will send the implicit `wsa:Action` header. If only Addressing is enabled by using the appropriate annotation at the SEI,

### 7.2. Explicit Action

This section describes how an explicit Action Message Addressing Property can be associated with an operation in the SEI.

W3C WS-Addressing W3C WS-Addressing 1.0 - Metadata and Member Submission WS-Addressing define mechanisms to associate Action Message Addressing Property with an operation. JAX-WS 2.1 defines `javax.xml.ws.Action` and `javax.xml.ws.FaultAction` annotations to explicitly associate an Action with `input`, `output`, and `fault` messages of the mapped WSDL operation. For example, one of the methods in the `fromjava-wsaddressing` sample looks like:

    @Action(
      input = "http://example.com/input3",
      output = "http://example.com/output3",
      fault = {
        @FaultAction(className = AddNumbersException.class, value = "http://example.com/fault3")
      })
    public int addNumbers3(int number1, int number2) throws AddNumbersException {
    ...
    }

The generated WSDL fragment looks like:

    <operation name="addNumbers3">
      <input wsam:Action="http://example.com/input3" message="tns:addNumbers3"/>
      <output wsam:Action="http://example.com/output3" message="tns:addNumbers3Response"/>
      <fault message="tns:AddNumbersException" name="AddNumbersException" wsam:Action="http://example.com/fault3"/>
    </operation>

where `wsam` is bound to W3C WS-Addressing 1.0 - Metadata namespace or Member Submission namespace depending upon the annotation used to enable Addressing.