The Worldwide Web Consortium (W3C) Web Services Addressing
(WS-Addressing) specification explicitly defines the WS-Addressing
core properties for the message exchange patterns (MEPs) that are
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.
Tip: You can override these values by using the IBM proprietary
WS-Addressing system programming interfaces (SPIs).
Table 1. The WS-Addressing message addressing
properties that a client adds to the message header of a one-way WS-Addressing
input message.
Abstract WS-Addressing MAP name, using the notational
convention of the W3C XML Information Set |
Default value 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 WebSphere® Application
Server 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 Specifying and acquiring message-addressing properties by 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 you must specify a reply endpoint
or fault endpoint in the request message.
Tip: In the
2005/08 specification, an unspecified reply endpoint is valid because
it defaults to an endpoint reference that contains 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. You can
override or specify other MAPs by using the IBM proprietary WS-Addressing
SPIs.
Table 2. The message addressing properties
that are added on a Web service request that uses the WS-Addressing
protocol.
Abstract WS-Addressing MAP name, using the notational
convention of the W3C XML Information Set |
Default value 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.
Table 3. The message addressing properties that
are added on a WS-Addressing response or fault message.
Abstract WS-Addressing MAP name, using the notational
convention of the W3C XML Information Set |
Default value 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 you 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 you set the reply endpoint or the
fault endpoint, the endpoint reference that you 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, you can use reference parameters within the endpoint reference
to target the reply or fault endpoint.
For JAX-WS applications,
you 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.
You 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 that are 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 you 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, you can configure the client to send its address in
IP format, however you lose the benefits of DHCP. For more information
see
Invoking JAX-WS Web services asynchronously.
For
JAX-WS applications, you can specify an asynchronous message exchange
pattern by applying and configuring a WS-Addressing policy type. 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. You can ensure that clients
are aware of the requirement for asynchronous messaging by enabling
WS-Policy.