JAX-WS 2.1.1 | Users Guide | Tools | JAXWS RI Extensions | Samples | JAXWS Community |
Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. JAX-WS 2.1 specification requires support for W3C
Core,
SOAP Binding and
WSDL Binding. In addition to that, JAX-WS 2.1 RI also supports
Member Submission version of WS-Addressing. This allows an application built using standard JAX-WS 2.1 APIs to enable/disable W3C WS-Addressing on the client and service endpoint. The member submission version is supported in an implementation specific way. The subsequent sections describe how the two WS-Addressing versions can be enabled/disabled on client and server side .
1.1. Why WS-Addressing ?
This
document explains what is WS-Addressing and why it is required.
1.2. WSDL Description
W3C WS-Addressing WSDL Binding defines a new standard extensibility element,
wsaw:UsingAddressing, that can be used to indicate that an endpoint conforms to the WS-Addressing specification. JAX-WS 2.1 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).
There is no standard mechanism to describe Member Submission version support in the WSDL.
1.3. 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 2.1 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 2.1 RI engages WS-Addressing based upon the presence of
wsa:Action
header. JAX-WS 2.1 RI follows same rule for Member Submission version as well.
In effect, if an endpoint advertises WS-Addressing in the WSDL with
wsdl:required="false"
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.
1.4. wsaw:Anonymous
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.
2. On the server side
This section describes how W3C and Member Submission WS-Addressing can be enabled/disabled on the server-side.
2.1. 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 ignored.
2.1.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:
wsaw:UsingAddressing
extensibility element is generated in the corresponding
wsdl:binding
section. For Member Submission, there is no standard mechanism.
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.
Annotation parameters
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.
In addition, for W3C only,
wsdl:required="true"
is generated on the extensibility element.
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 { ... }
In most common cases, an implicit Action association, as defined by
W3C WS-Addressing WSDL Binding 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,
2.1.3. Explicit Action
This section describes how an explicit Action Message Addressing Property can be associated with an operation in the SEI.
W3C WS-Addressing
WSDL Binding 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 wsaw:Action="http://example.com/input3" message="tns:addNumbers3"/> <output wsaw:Action="http://example.com/output3" message="tns:addNumbers3Response"/> <fault message="tns:AddNumbersException" name="AddNumbersException" wsaw:Action="http://example.com/fault3"/> </operation>
where
wsaw
is bound to W3C WSDL Binding namespace or Member Submission namespace depending upon the annotation used to enable Addressing.
2.2. Starting from WSDL
This section describes how WS-Addressing can be enabled/disabled if you develop an endpoint starting from a WSDL.
For W3C only, if the WSDL contains the standard extensibility element
wsaw:UsingAddressing
then that is sufficient. The only way to enable Member Submission WS-Addressing is to use the
com.sun.xml.ws.developer.MemberSubmission
annotation described above.
3. On the client side
This section describes how W3C and Member Submission WS-Addressing can be enabled/disabled on the server-side. JAX-WS 2.1 follows the standard extensibility elements 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.
3.1. Implicit behavior
As defined in Section 1.1, W3C defines a standard extensibility element,
wsaw:UsingAddressing
, to indicate that the endpoint conforms to W3C specification. If the WSDL contains this extensibility element, then JAX-WS RI:
wsaw:Action
in the
input
,
output
and
fault
elements of
wsdl:operation
to
javax.xml.ws.Action
and
javax.xml.ws.FaultAction
annotation in the generated SEI.
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.
3.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 2.1 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));