Web Services Addressing message exchange patterns
The World Wide Web Consortium (W3C) Web Services Addressing (WS-Addressing) specification explicitly defines the WS-Addressing core properties for the message exchange patterns (MEPs) defined by WSDL 1.0. These MEPs are summarized in this topic, illustrating the mandatory WS-Addressing properties for each pattern.
One-way MEP
This straightforward one-way message is defined in WSDL 1.0 as an input-only operation. The WSDL fragment for this operation has the following form:
<operation name="myOperation"> <input message="tns:myInputMessage"/> </operation>
The following WS-Addressing message addressing properties (MAPs) are automatically added to the message header of a one-way WS-Addressing input message by the client application server run time, to ensure compliance with the WS-Addressing specification.
We can override these values using the IBM proprietary WS-Addressing system programming interfaces (SPIs).
| Abstract WS-Addressing MAP name, using the notational convention of the W3C XML Information Set | Description for a one-way input message |
|---|---|
| [action] | The WS-Addressing action that is generated in accordance with the version of the WS-Addressing specification that is in use. |
| [reply endpoint] | The WS-Addressing reply endpoint indicating that no replies are expected to this input message. The value of this MAP depends on the version of the WS-Addressing specification that is in use. |
| [message id] | A uniquely generated message identifier. Although not mandated by the specification, the WAS run time automatically sets this value. |
Although the WSDL operation for this message exchange does not specify any responses, related messages can be sent as part of other message exchanges. In particular, applications can use the WS-Addressing reply endpoint or fault endpoint MAPs to indicate to the target of a one-way message where to send related messages. To propagate a reply endpoint or fault endpoint, associate the appropriate property with the request context for the JAX-WS BindingProvider object, or with the JAX-RPC Stub or Call object, as described in Specify and acquiring message-addressing properties using the IBM proprietary Web Services Addressing SPIs, to override the defaults.
Two-way request-response
This is a request-response MEP as defined in WSDL 1.1. The response part of the operation might be defined as an output message, or a fault message, or both. The following WSDL code extracts show the various forms of definition for such an operation:
<operation name="myOperation"> <input message="tns:myInputMessage"/> <output message="tns:myOutputMessage"/> <fault="tns:myFaultMessage"/> </operation>
<operation name="myOperation"> <input message="tns:myInputMessage"/> <output message="tns:myOutputMessage"/> </operation>
<operation name="myOperation"> <input message="tns:myInputMessage"/> <fault="tns:myFaultMessage"/> </operation>
The application server client run time ensures that the SOAP header of the outgoing request message contains the relevant WS-Addressing message information headers. The calling application does not have to set the WS-Addressing headers. A response is expected, therefore specify a reply endpoint or fault endpoint in the request message.
In the 2005/08 specification, an unspecified reply endpoint is valid because it defaults to an endpoint reference containing the anonymous URI.
The following table summarizes the MAPs that the product sets by default on a web service request that uses WS-Addressing protocol. We can override or specify other MAPs using the IBM proprietary WS-Addressing SPIs.
| Abstract WS-Addressing MAP name, using the notational convention of the W3C XML Information Set | Description for the input message of a request-response operation |
|---|---|
| [action] | The WS-Addressing action that is generated in accordance with the version of the WS-Addressing specification that is in use. |
| [message id] | A uniquely generated message identifier. |
The following table summarizes the MAPs that are set by default by the product on a WS-Addressing response or fault message.
| Abstract WS-Addressing MAP name, using the notational convention of the W3C XML Information Set | Description for the input message of a request-response operation |
|---|---|
| [action] | The WS-Addressing action that is generated in accordance with the version of the WS-Addressing specification that is in use. |
| [relationship] | A relationship set containing a reply relationship to the message id that is passed in the request message. |
| [message id] | A uniquely generated message identifier; although not mandated by the specification, the application server run time automatically sets this property. |
Synchronous request-response
By default, if we do not use the IBM proprietary WS-Addressing SPI to set the reply endpoint or fault endpoint, the response part of a two-way message is returned according to the underlying protocol in use. In particular, for an HTTP request, the response is returned synchronously in the HTTP response.
For JAX-WS synchronous invocations, if set the reply endpoint or the fault endpoint, the endpoint reference set must use the anonymous URI. If the endpoint reference does not use the anonymous URI, a javax.xml.ws.WebServiceException exception is thrown. Although the endpoint reference uses the anonymous URI, we can use reference parameters within the endpoint reference to target the reply or fault endpoint.
For JAX-WS applications, we can specify a synchronous message exchange pattern by applying and configuring a WS-Addressing policy type. This exchange pattern is particularly useful in the following scenarios:
- You do not have WS-Security enabled, or have not used an assembly tool to specify that the ReplyTo and FaultTo elements of the SOAP
message should be signed. In this situation, it is possible for a JAX-WS endpoint to be used to send messages to a third party, potentially
taking part in a Denial of Service attack. To prevent such attacks, specify the synchronous message exchange pattern, and enable WS-Policy
so that clients are aware of this requirement.
- A JAX-WS client is communicating through a NAT device. URIs in the ReplyTo or FaultTo elements of the SOAP message cannot be routed through such a device. In this situation, the client must use the anonymous URI defined by the WS-Addressing specification, and a synchronous message exchange pattern. To ensure that the client conforms to these requirements even if the server uses WS-Policy to request a non-anonymous URI in the ReplyTo element, specify the synchronous message exchange pattern on the client.
We can ensure that servers or clients are aware of the requirement for synchronous messaging by enabling WS-Policy.
Asynchronous request-response
The JAX-RPC 1.0 programming model does not allow for asynchronous replies or faults to a two-way request-response operation.
Responses to, or faults generated from, requests directed at endpoints hosted on WebSphere Application Server are targeted at the reply endpoint or fault endpoint, in accordance with the WS-Addressing specification. The connection with the requesting client will be closed with an HTTP 202 response.
For JAX-WS asynchronous invocations, the reply endpoint is generated automatically for use by the JAX-WS implementation. If we attempt to set either a reply endpoint or a fault endpoint, a javax.xml.ws.WebServiceException exception is thrown.
Note: On Windows operating systems, the local host name that is sent by the client must be resolvable by the target service, otherwise replies do not reach the client application. Alternatively, we can configure the client to send its address in IP format, however you lose the benefits of DHCP. For more information see the Invoking JAX-WS web services asynchronously topic.
For JAX-WS applications, we can specify an asynchronous message exchange pattern in several different ways.
- By applying and configuring a WS-Addressing policy set. See the Configuring
the WS-Addressing policy topic.
- By setting the com.ibm.websphere.webservices.use.async.mep property on the client request context. See the Invoking
JAX-WS web services asynchronously topic.
- Through the use of deployment descriptor elements, @Addressing annotations, addressing features, or by adding WS-Policy assertions into the WSDL document. See the Enable Web Services Addressing support for JAX-WS applications topic and its child topics.
This exchange pattern is particularly useful if a JAX-WS endpoint has a long-running invocation time. Client and server resources are used to keep the connection open, but this use of resource might be impractical if the service takes a long time to respond.
The message exchange pattern configuration is expressed in WS-Policy attachments in the WSDL document. Clients will be able to access this message exchange pattern configuration information if any of the following conditions are true:
- WS-Policy sharing is enabled.
- WS-Policy
sharing is not enabled, but:
- the packaged WSDL (as retrived
by an HTTP GET request) contains the relevant policy information.
- @Addressing annotations have been used in the code. In this case, the server runtime generates a WSDL document containing the WS-Policy attachments.
- the packaged WSDL (as retrived
by an HTTP GET request) contains the relevant policy information.
See the Web service providers and policy configuration sharing topic for further details.
Related concepts
Related tasks
Related information:
W3C
XML Information Set: http://www.w3.org/TR/xml-infoset/