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.
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> |
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" |
(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.
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 2.1 RI enables stateful Web services to be annotated with com.sun.xml.ws.developer.Stateful
annotation.
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:
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.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.reply endpoint
and fault
endpoint
MAP, a different transport/address can be specified for
receiving normal and fault responses respectively.(001) |
<s11:Envelope |
(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 |
(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 |
(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.
There are two prominent versions of WS-Addressing that are commonly used:
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 2.1 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.