JAX-WS RI 2.2.5 -- Why WS-Addressing ?

# Java TM API for XML Web Services
(JAX-WS)
Why WS-Addressing ?

Specification Version: 2.2
Implementation Version: 2.2.5

## Contents

## 1. What is WS-Addressing ?

Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. The transport-neutrality is achieved by normalizing the information typically shared between transport protocols and messaging systems. To serve this purpose, WS-Addressing defines two new constructs, Message Addressing Properties (MAPs) and Endpoint Reference (EPR), that normalize the information independent of any particular transport or messaging system. MAPs convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity that allows uniform addressing of messages independent of the underlying transport. EPR convey the information needed to address a Web service endpoint.

The subsequent sections explain the different use cases served by WS-Addressing.

### 1.1. Transport Neutrality

This section describes how a message can be sent to a Web service endpoint in transport neutral manner.

A SOAP 1.2 message, without WS-Addressing, sent over HTTP transport looks like:

`` | ``
`(001)` | `POST /fabrikam/Purchasing HTTP 1.1/POST`
`(002)` | `Host: example.com`
`(003)` | `SOAPAction: http://example.com/fabrikam/SubmitPO`
`(004)` |
`(005)` | `<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wombat="http://wombat.org/">`
`(006)` | `<S:Header>`
`(007)` | `<wombat:MessageID>`
`(008)` | `uuid:e197db59-0982-4c9c-9702-4234d204f7f4`
`(009)` | `</wombat:MessageID>`
`(010)` | `<S:Header>`
`(011)` | `<S:Body>`
`(012)` | `...`
`(013)` | `</S:Body>`
`(014)` | `</S:Envelope>`

Line (001) - (003) shows the HTTP transport headers. Line (005) - (014) shows the SOAP message in HTTP body.

The host ( `example.com`), the dispatch method ( `POST`) and the URL to dispatch to ( `/fabrikam/Purchasing`) are in the HTTP transport headers. The actual message and implied meaning (for example payload's `QName` or `SOAPAction`) is defined by the messaging system (SOAP) or transport protocol (HTTP). If the message is to be sent over an alternate transport, such as SMTP, then the information conveyed in HTTP transport headers need to be mapped to SMTP specific headers. On the server side, to dispatch successfully, a Web service stack has to gather the information from the SMTP (as opposed to HTTP) headers and the SOAP message.

Also in the above message, there is no standard header to establish the identity of a message. In this case, `MessageID` header defined in the namespace URI bound to `wombat` prefix is used but is application specific and is thus not re-usable.

WS-Addressing introduce Message Addressing Properties that collectively augment a message to normalize this information. A SOAP 1.2 message, with WS-Addressing, sent over HTTP transport looks like:

`` | ``
`(001)` | `POST /fabrikam/Purchasing HTTP 1.1/POST`
`(002)` | `Host: example.com`
`(003)` | `SOAPAction: http://example.com/fabrikam/SubmitPO`
`(004)` |
`(005)` | `<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing/">`
`(006)` | `<S:Header>`
`(007)` | `<wsa:MessageID>`
`(008)` | `uuid:e197db59-0982-4c9c-9702-4234d204f7f4`
`(009)` | `</wsa:MessageID>`
`(010)` | `<wsa:To>`
`(011)` | `http://example.com/fabrikam/Purchasing`
`(012)` | `</wsa:To>`
`(013)` | `<wsa:Action>`
`(014)` | `http://example.com/fabrikam/SubmitPO`
`(015)` | `</wsa:Action>`
`(016)` | `<S:Header>`
`(017)` | `<S:Body>`
`(018)` | `...`
`(019)` | `</S:Body>`
`(020)` | `</S:Envelope>`

In this message, Line (001) - (003) shows the HTTP transport headers. Line (005) - (020) shows the SOAP message in HTTP body. Line (007) - (015) shows a binding of Message Addressing Properties to SOAP 1.2 message. For example, `wsa:MessageID` is a binding of an abstract property that defines an absolute URI that uniquely identifies the message, `wsa:To` is binding of an abstract absolute URI representing the address of the intended receiver of this message and `wsa:Action` is binding of an abstract absolute IRI that uniquely identifies the semantics implied by this message. All the information earlier shared between transport protocols and messaging systems is now normalized into a uniform format that can be processed independent of transport or application.

If the exactly same message is to be sent/received using a different transport, for example asynchronously over SMTP, then the value of `wsa:To` header could be changed to `mailto:purchasing@example.com`. The updated `wsa:To` header looks like:

`` | ``
`(010)` | `<wsa:To>`
`(011)` | `mailto:purchasing@example.com`
`(012)` | `</wsa:To>`

On the server side, Web services stack can gather all the information from the SOAP message and then dispatch it correctly.

### 1.2. Stateful Web service

Web services are usually stateless, i.e. the service endpoint receives a request and responds back without saving any processing state in between different requests. However making Web services stateful enables to share multiple instances of service endpoints. For example, consider a stateful Bank Web service. The client (say bank customer) can obtain a bank EPR, with relevant state information stored as reference parameters, and invoke a method on that EPR to do a series of banking operations. On the service endpoint, whenever a request is received, the reference parameters from the EPR are available as first-class SOAP headers allowing the endpoint to restore the state.

JAX-WS RI 2.2.5 enables stateful Web services to be annotated with `com.sun.xml.ws.developer.Stateful` annotation.

### 1.3. Simple and Complex MEPs

WS-Addressing defines standard Message Addressing Properties (MAPs) to support simple and complex message patterns. The SOAP Binding defines a mapping of these MAPs to SOAP headers and convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity. For example `destination` MAP represents an absolute IRI representing the address of the intended receiver of the message and is mapped to a SOAP header with `wsa:To` element name. `reply endpoint` represents an endpoint reference for the intended receiver for replies to this message and is mapped to a SOAP header with `wsa:ReplyTo` element name. In addition, WSDL Binding, also defines requirement on the presence of these MAPs for standard Message Exchange Patterns (MEPs) such as request/response and one-way.

Using these MAPs, complex MEPs can be created. For example:

1. Asynchronous MEP: Using `reply endpoint` MAP, an asynchronous transport may be specified for a synchronous request. For example, a client application might send a request over HTTP and ask to receive the response through SMTP.
2. Conversation MEP: Using `relationship` MAP, that defines the relationship between two messages, a conversational MEP can be defined by correlating multiple request/response MEPs. For example a client sending a request to service endpoint receives a response with `wsa:RelatesTo` MAP. The service endpoint may optionally include `wsa:MessageID` in the response. This MAP can then be included by the client in `wsa:RelatesTo` MAP in next request to the service endpoint there by starting a conversation.
3. Distributed MEP: Using `reply endpoint` and `fault endpoint` MAP, a different transport/address can be specified for receiving normal and fault responses respectively.

### 1.4. Composability with other WS-* specifications

There are several Web services specification (commonly known as WS-* specs) that make use of the abstract properties defined by WS-Addressing. For example WS-Metadata Exchange define a bootstrap mechanism for retrieving metadata before the business message exchange can take place. This mechanism involve sending a WS-Transfer request for the retrieval of a resource's representation. A typical request message looks like:

`(001)` | `<s11:Envelope xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">`
`(002)` | `<s11:Header>`
`(003)` | `<wsa:Action>`
`(004)` | `http://schemas.xmlsoap.org/ws/2004/09/transfer/Get`
`(005)` | `</wsa:Action>`
`(006)` | `<wsa:To>http://example.org/metadata</wsa10:To>`
`(007)` | `<wsa:ReplyTo>`
`(008)` | `<wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa10:Address>`
`(009)` | `</wsa:ReplyTo>`
`(010)` | `<wsa:MessageID>`
`(011)` | `uuid:` `68da6b24-7fa1-4da2-8a06-e615bfa3d2d0`
`(012)` | `</wsa:MessageID>`
`(013)` | `</s11:Header>`
`(014)` | `<s11:Body />`
`(015)` | `</s11:Envelope>`

In this message, Line (001) - (015) shows the SOAP request message to retrieve metadata about a Web service endpoint. Line (001) shows the WS-Addressing namespace URI bound to "wsa" prefix. Line (003) - (012) shows the standard WS-Addressing MAPs used to convey the semantics ( `wsa:Action`), receiver ( `wsa:To`) of the message, intended receiver of reply ( `wsa:ReplyTo`) message and identity ( `wsa:MessageID`) information of the message. This message has an empty SOAP Body and relies completely upon standard MAPs to convey all the information. Similarly, a WS-Metadata Exchange response message with metadata looks like:

`(001)` | `<s11:Envelope xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">`
`(002)` | `<s11:Header>`
`(003)` | `<wsa:Action>`
`(004)` | `http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse`
`(005)` | `</wsa:Action>`
`(006)` | `<wsa:RelatesTo>`
`(007)` | `uuid:` `68da6b24-7fa1-4da2-8a06-e615bfa3d2d0`
`(008)` | `</wsa:RelatesTo>`
`(009)` | `</s11:Header>`
`(010)` | `<s11:Body />`
`(011)` | `...`
`(012)` | `<s11:Body />`
`(013)` | `</s11:Envelope>`

In this message, Line (003) - (008) shows the standard WS-Addressing MAPs used to convey the semantics ( `wsa:Action`) of the response message and relationship ( `wsa:RelatesTo`) to the request message. Line (010) - (012) shows abbreviated SOAP Body for simplicity which otherwise would contain the MEX response.

WS-Reliable Messaging describes a protocol that allows messages to be delivered reliably between distributed applications in the presence of software component, system or network failures. This specification defines protocol messages that must be exchanged between client and service endpoint, before the business message exchange, in order to deliver the messages reliably. For example, RM Source sends `<CreateSequence>` request message to RM Destination to create an outbound sequence. The message looks like:

`(001)` | `<s11:Envelope xmlns:s11="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa=" http://www.w3.org/2005/08/addressing" xmlns:wsrm=" http://schemas.xmlsoap.org/ws/2005/02/rm">`
`(002)` | `<s11:Body>`
`(003)` | `<wsrm:CreateSequence>`
`(004)` | `<wsrm:AcksTo>`
`(005)` | `<wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address>`
`(006)` | `</wsrm:AcksTo>`
`(007)` | `</wsrm:CreateSequence>`
`(008)` | `</s11:Body>`
`(009)` | `</s11:Envelope>`

Line (002) - (008) is SOAP Body of the request message. The Body contains an element, `wsrm:AcksTo` (of the type Endpoint Reference), that specifies the endpoint reference to which `<SequenceAcknowledgement>` messages and faults related to sequence creation are sent.

WS-Secure Conversation, WS-Trust, WS-Policy and other similar specifications use the constructs defined by WS-Addressing as building blocks.

## 2. WS-Addressing Versions

There are two prominent versions of WS-Addressing that are commonly used:

- W3C WS-Addressing
- Member Submission WS-Addressing

Sun, IBM, BEA, Microsoft and SAP co-authored and submitted a WS-Addressing specification to W3C in August 2004. W3C chartered a new Working Group with a mission to produce a W3C Recommendation for WS-Addressing by refining the submitted specification. The original specification submitted to W3C is referred as "Member Submission WS-Addressing" or "Submission WS-Addressing". The term Member Submission is defined by W3C.

The WG was chartered to deliver a W3C Recommendation for WS-Addressing Core, SOAP Binding (mapping abstract properties defined in Core to SOAP 1.1 and 1.2) and WSDL Binding (mechanisms to define property values in WSDL 1.1 and WSDL 2.0 service descriptions) specification. This separate between Core/Bindings is common methodology where Core is relevant to application developers and Binding (both SOAP and WSDL) is relevant for Web service stack implementers. This collective set of specifications is referred as "W3C WS-Addressing".

JAX-WS RI supports both versions out-of-the-box. Check Users Guide on how to enable either of the versions on a service endpoint starting from Java or starting from WSDL.