JAX-WS RI 2.2.3 | Users Guide | Tools | JAX-WS RI Extensions | Samples | JAX-WS Community |
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>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
<wsp:Policy>
<wsam:NonAnonymousResponses/>
</wsp:Policy>
</wsam:Addressing>
<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.
<wsp:Policy>
<wsam:AnonymousResponses/>
</wsp:Policy>
</wsam:Addressing>
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:
mustUnderstand="1"
,
then a mustUnderstand fault is not thrown back.
wsa:ReplyTo
header does not match the infoset defined in the corresponding
specification.
wsa:Action
header value does not match with that
expected for that operation, then an error is returned back to the
client.
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 {
...
}
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.
Action
,
To
,
MessageID
and anonymous
ReplyTo
headers on the outbound request.
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));
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.