The Web Services Addressing (WS-Addressing) support provides
mechanisms to address Web services and provide addressing information
in messages. For JAX-WS applications, you can enable WS-Addressing
support in several different ways, such as configuring policy sets
or using annotations in code.
About this task
New feature: This release introduces
a new way to enable WS-Addressing. You can now use JAX-WS 2.1 annotations
and feature classes to enable WS-Addressing from either the server
or the client. You also have more control over the behavior of WS-Addressing
when using policy sets; you can specify whether WS-Addressing is enabled
and whether to use synchronous, asynchronous, or both messaging patterns.
newfeat
Perform
this task to enable the WS-Addressing support, either as a service
provider or as a client of a service provided by another party. This
task also describes how to disable the WS-Addressing support, which
can improve performance for those applications that do not use WS-Addressing
or any protocol that depends on the WS-Addressing support.
For
service providers, WS-Addressing support is enabled by default, so
you do not have to undertake any actions to enable support. However,
you can use the enabling mechanisms to modify other WS-Addressing
behavior for the service, such as whether WS-Addressing information
is required, and what is included in the generated WSDL document.
- Modify the behavior of the WS-Addressing support after the application
is deployed by attaching a policy set to the application. Within the
policy set, you can configure the WS-Addressing policy type to specify
whether WS-Addressing information is required in incoming messages,
and whether to use synchronous or asynchronous messaging. You can
communicate the WS-Addressing policy configuration to other servers
and clients that support WS-Policy, by enabling policy sharing on
the server, and by applying the provider policy on the client. This
method overrides other methods.
- Modify the behavior of the WS-Addressing support during development
of the service by using the Addressing or SubmissionAddressing annotations
in the service code. Within each annotation you can specify whether
the server requires WS-Addressing information in incoming messages.
The presence of the Addressing annotation in the
code also adds a UsingAddressing element to any
WSDL document that is generated for the service. If you provide your
own WSDL document instead of relying on the JAX-WS runtime environment
to generate one, you must include the UsingAddressing element
yourself, if required.
For service clients, WS-Addressing support is disabled
by default. Use one of the following methods to enable WS-Addressing
support:
- Attach a policy set to the client artifact and perform one of
the following actions:
- Specify in the policy that WS-Addressing is mandatory.
- Apply both client and provider policies. In this situation, WS-Addressing
support is enabled on the client only if policy sharing is enabled
on the service provider and the policy configuration for the provider
specifies that WS-Addressing is mandatory.
This method overrides other methods.
- Use addressing features in the client code. Settings set by using
this method override those set in the WSDL document for the service.
- Set the com.ibm.websphere.webservices.use.async.mep property
on the client request context.
- Use any option available to JAX-RPC applications:
The following tables summarize the behavior of the WS-Addressing
support.
Use the following table to determine whether a request
message is accepted for client settings that do not involve policy
configuration.
Table 1. How client and provider
settings interact to determine whether a request message is accepted.
Client settings |
Provider
policy settings |
Provider WSDL settings
(UsingAddressing required attribute) |
WS-Addressing is optional |
WS-Addressing is mandatory1 |
WS-Addressing support enabled |
Messaging style |
Synchronous and asynchronous |
Synchronous only |
Asynchronous only |
Synchronous and asynchronous |
Synchronous only |
Asynchronous only |
false (WS-Addressing
is optional) |
true (WS-Addressing
is mandatory1) |
Yes (WS-Addressing headers are present) |
Synchronous |
Message accepted |
Message accepted |
Fault |
Message accepted |
Message accepted |
Fault |
Message accepted |
Message accepted |
Asynchronous |
Message accepted |
Fault |
Message accepted |
Message accepted |
Fault |
Message accepted |
Message accepted |
Message accepted |
No (WS-Addressing headers are absent) |
Synchronous |
Message accepted |
Message accepted |
Message accepted2 |
Fault |
Fault |
Fault |
Message accepted |
Fault |
Asynchronous3 |
Fault |
Fault |
Fault |
Fault |
Fault |
Fault |
Fault |
Fault |
Notes:
- If WS-Addressing is mandatory, all requests without WS-Addressing
headers are rejected.
- The messaging style is only enforced if WS-Addressing headers
are present in the request.
- Asynchronous messaging is not possible without WS-Addressing headers.
Use the following table to determine whether a
request message is accepted when the client and provider both have
a WS-Addressing policy configuration, the client has provider and
client policies applied, and policy sharing is enabled on the server.
Table 2. How client and provider policy settings
interact to determine whether a request message is accepted.
Client policy settings |
Provider
policy settings |
WS-Addressing
is optional |
WS-Addressing
is mandatory |
Synchronous and asynchronous |
Synchronous only |
Asynchronous only |
Synchronous and asynchronous |
Synchronous only |
Asynchronous only |
WS-Addressing is optional |
Synchronous and asynchronous |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Synchronous only |
Message accepted |
Message accepted |
Message accepted1 |
Message accepted |
Message accepted |
Fault |
Asynchronous only2 |
Fault |
Fault |
Fault |
Message accepted |
Fault |
Message accepted |
WS-Addressing is mandatory |
Synchronous and asynchronous |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Message accepted |
Synchronous only |
Message accepted |
Message accepted |
Fault |
Message accepted |
Message accepted |
Fault |
Asynchronous only |
Message accepted |
Fault |
Message accepted |
Message accepted |
Fault |
Message accepted |
Notes:
- The messaging style is only enforced if WS-Addressing headers
are present in the request.
- Asynchronous messaging is not possible without WS-Addressing headers.
If the provider and client policies are not shared, the
client does not send WS-Addressing headers (unless you enable WS-Addressing
on the client by another method). In this situation, if the provider
policy specifies that WS-Addressing is mandatory, the server generates
a fault regardless of the messaging style.
- To modify the behavior of the WS-Addressing support by
using policy sets on either the service provider or client, complete
the following steps:
- Ensure that you have a policy set that contains the
WS-Adressing policy type. If you have to create a new policy
set, or add the WS-Addressing policy to an existing policy set, refer
to Managing policy sets using the administrative console for instructions.
- Configure the WS-Addressing policy type according to
the instructions in Configuring the WS-Addressing policy.
You can specify whether WS-Addressing is mandatory, and whether
to use a synchronous or asynchronous message exchange pattern. The
default settings are that WS-Addressing is not mandatory, and both
synchronous and asynchronous messaging patterns are used.
- Attach the policy set to a Web service provider or client
artifact, according to the instructions in Attaching a policy set to a service artifact.
- Optional: If you want to communicate the
WS-Addressing policy settings to other servers and clients, configure
policy sharing as described in Configuring a service provider to share its policy configuration or Configuring the client policy to use a service provider policy.
If policy sharing is enabled and the server and client cannot
agree a policy, normal WS-Policy behavior applies (a policy error
is produced).
- To modify the behavior of the WS-Addressing support programmatically
in the service application, use one of the following addressing annotations
with up to two optional parameters, which specify whether WS-Addressing
is enabled and whether WS-Addressing is required. The default
settings are that WS-Addressing is enabled but not required.
- Addressing - use this annotation if you want
to use the 2005/08 WS-Addressing specification
- SubmissionAddressing - use this annotation
if you want to use the 2004/08 WS-Addressing specification.
In the following example, the Addressing annotation
is used with no parameters, so the default settings apply.import javax.xml.ws.soap.Addressing;
@Addressing
@WebService(endpointInterface =
"org.apache.axis2.jaxws.calculator.Calculator",
serviceName = "CalculatorService",
portName = "CalculatorServicePort",
targetNamespace = "http://calculator.jaxws.axis2.apache.org")
In
the following example, the SubmissionAddressing annotation
is used with parameters that specify that WS-Addressing is enabled
and required.import com.ibm.websphere.wsaddressing.jaxws21.SubmissionAddressing;
@SubmissionAddressing(enabled="true", required="true")
@WebService(endpointInterface =
"org.apache.axis2.jaxws.calculator.Calculator",
serviceName = "CalculatorService",
portName = "CalculatorServicePort",
targetNamespace = "http://calculator.jaxws.axis2.apache.org")
The server processes any WS-Addressing headers that
conform to this relevant specification in inbound SOAP messages. If
you specify that WS-Addressing is required, and an inbound SOAP message
does not include any WS-Addressing headers, or includes WS-Addressing
headers that do not conform to the specification indicated by the
annotation, the server returns a fault message. For example, if a
client sends a message that includes 2004/08 WS-Addressing headers,
and the server requires 2005/08 headers, the server returns a fault
message.
If you use the Addressing annotation and generate a
WSDL document from the code, a UsingAddressing element
is created in the WSDL document. Clients that use this WSDL document
will include WS-Addressing information in their messages. The SubmissionAddressing annotation
is not understood by current WSDL generation tools. However, the WSDL
document does not distinguish between the 2005/08 specification and
the 2004/08 specification, so if you want to generate a WSDL document
from code that contains a SubmissionAddressing annotation,
use both the Addressing and SubmissionAddressing annotations
together.
Notes:
- You can use the Addressing annotation only
with a SOAP (1.1 or 1.2) over HTTP binding. If you use the class with
another binding, such as XML over HTTP, an exception is thrown on
clients, and on servers the Web service fails to deploy.
- Annotation settings override settings in the WSDL document. Annotation
settings might differ from WSDL settings if you create the WSDL document
manually rather than generating it from the code.
- If you generate a WSDL document from this code, the UsingAddressing element
generated currently has a namespace prefix of wsaw,
rather than wsam as specified by the WS-Addressing
Metadata specification. This result is because the existing WSDL generation
tools are not aware of this new specification. The product supports
both prefixes, but if you require the wsam prefix,
edit the WSDL document manually.
- To enable WS-Addressing support programmatically on the
client by using features, create an instance of one of the following
addressing feature classes, with up to two optional parameters, which
specify whether WS-Addressing is enabled and whether WS-Addressing
is required. The default settings are that WS-Addressing
is enabled but not required, however the required property is not
used by the client.
- AddressingFeature - use this class if you want
to send messages that include WS-Addressing headers that conform to
the 2005/08 WS-Addressing specification
- SubmissionAddressingFeature - use this class
if you want to send messages that include WS-Addressing headers that
conform to the 2004/08 WS-Addressing specification
For example, to specify that WS-Addressing is
enabled and required, and that the 2005/08 specification should be
used, use the following code: AddressingFeature feat = new AddressingFeature(true, required);
To
specify that WS-Addressing is disabled for the 2004/08 specification,
use the following code: SubmissionAddressingFeature feat = new SubmissionAddressingFeature(false);
If you specify that WS-Addressing is enabled, the client
includes WS-Addressing headers in SOAP messages. The required property
is ignored, but might be used by the application to check that the
client has created the correct headers. The headers conform to the
WS-Addressing specification indicated by the type of feature class
used. If the server does not use annotations, or uses policy sets
to enable WS-Addressing, the server accepts both the 2005/08 and 2004/08
specifications.
Notes:
- You can use the addressing feature classes only with a SOAP (1.1
or 1.2) over HTTP binding. If you use the class with another binding,
such as XML over HTTP, an exception is thrown on clients, and on servers
the Web service fails to deploy.
- If you use both feature classes, the specification that is used
depends on the type of endpoint reference that you also specify. For
example, if you specify a W3CEndpointReference object,
the specification that is used is the 2005/08 specification. If you
do not specify an endpoint reference, the default specification is
the 2005/08 specification. If you specify an endpoint reference whose
type conflicts with that indicated by the feature class, for example
a W3CEndpointReference object with a SubmissionAddressingFeature instance,
an error is thrown.
- On WebSphere® Application Server clients, you
can also enable WS-Addressing support by setting the com.ibm.websphere.webservices.use.async.mep property
on the client request context. For more information, see Invoking JAX-WS Web services asynchronously.