Enabling Web Services Addressing support for JAX-WS applications

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

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.

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.
Use deployment descriptor elements within a port-component element.
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 WS-Addressing is enabled on the server, whether the server requires WS-Addressing information in incoming messages and the message exchange pattern the server will use. The presence of the Addressing annotation in the code adds a UsingAddressing element and a WS-Policy assertion to any WSDL document that is generated for the service.
Modify the behavior of the WS-Addressing support during development of the service by either adding UsingAddressing elements or WS-Policy assertions into the WSDL document. If you do provide your own WSDL document, instead of relying on the JAX-WS runtime environment to generate one, and your WSDL document is being consumed by non JAX-WS 2.2 clients, you may wish to include the UsingAddressing element as such clients will not process WS-Policy assertions.

For service clients, WS-Addressing support is disabled by default. Use one of the following methods to enable WS-Addressing support. The following list is in descending order of precedence, because you can apply multiple methods. For example the deployment descriptor method overrides the use of annotations or features, but is itself overridden by the use of policy sets.

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.
Set the com.ibm.websphere.webservices.use.async.mep property on the client request context.
Use the IBM® proprietary WS-Addressing SPI to add message-addressing properties to the message request context.
Use deployment descriptor elements within a port-component-ref element.
Use the Addressing annotation in combination with the WebServiceRef annotation in the client code (when you are using an injected Web services proxy reference).
Use addressing features in the client code. Properties set by using this method override those set in the WSDL document for the service.
Use WS-Policy assertions in the WSDL document to specify WS-Addressing support. If you add Addressing annotations to your client application code, the generated WSDL document will contain WS-Policy assertions.
Specify the UsingAddressing element in the WSDL document for the service. If the service uses the Addressing annotation and you generate the WSDL document from the code, the UsingAddressing element already exists.

The following tables summarize the behavior of the WS-Addressing support. Use this table to determine whether a request message is accepted for client settings that do not involve policy configuration.

This is a complex table containing spanned column headings. There is a header column entitled "Client settings" which specifies whether WS-Addressing support is enabled on the client and also which messaging style is configured. The second main column shows the policy settings on the provider, with two sub-columns for whether WS-Addressing is optional or mandatory. Both of these sub-columns are further sub-divided into three sub-columns for messaging style (synchronous, asynchronous, or both). The third main column shows the WSDL settings on the provider, with two sub-columns for whether WS-Addressing is optional or mandatory.

Table 1. How client and provider policy settings interact to determine whether a request message is accepted . The preceding paragraph describes this table.
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 optional and messaging style synchronous and asynchronous	Message accepted	Message accepted	Message accepted	Message accepted	Message accepted	Message accepted
WS-Addressing optional and messaging style synchronous only	Message accepted	Message accepted	Message accepted¹	Message accepted	Message accepted	Fault
WS-Addressing optional and messaging style asynchronous only²	Fault	Fault	Fault	Message accepted	Fault	Message accepted
WS-Addressing mandatory and messaging style synchronous and asynchronous	Message accepted	Message accepted	Message accepted	Message accepted	Message accepted	Message accepted
WS-Addressing mandatory and messaging style synchronous only	Message accepted	Message accepted	Fault	Message accepted	Message accepted	Fault
WS-Addressing mandatory and messaging style asynchronous only	Message accepted	Fault	Message accepted	Message accepted	Fault	Message accepted

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.

This is a complex table containing spanned column headings. There is a header column entitled "Client settings" which specifies whether WS-Addressing support is optional or mandatory on the client and also which messaging style is configured. The second main column shows the policy settings on the provider, with two sub-columns for whether WS-Addressing is optional or mandatory. Both of these sub-columns are further sub-divided into three sub-columns for messaging style (synchronous and asynchronous, synchronous only, or asynchronous only).

Table 2. How client and provider settings interact to determine whether a request message is accepted . The preceding paragraph describes this table.
Client settings	Provider policy settings, WS-Addressing is optional: Synchronous and asynchronous	Provider policy settings, WS-Addressing is optional: Synchronous only	Provider policy settings, WS-Addressing is optional: Asynchronous only	Provider policy settings, WS-Addressing is mandatory¹: Synchronous and asynchronous	Provider policy settings, WS-Addressing is mandatory¹: Synchronous only	Provider policy settings, WS-Addressing is mandatory¹: Asynchronous only	Provider WSDL settings (UsingAddressing `required` attribute): `false` (WS-Addressing is optional)	Provider WSDL settings (UsingAddressing `required` attribute): `true` (WS-Addressing is mandatory¹)
WS-Addressing support enabled and messaging style synchronous	Message accepted	Message accepted	Fault	Message accepted	Message accepted	Fault	Message accepted	Message accepted
WS-Addressing support enabled and messaging style asynchronous	Message accepted	Fault	Message accepted	Message accepted	Fault	Message accepted	Message accepted	Message accepted
WS-Addressing support not enabled and messaging style synchronous	Message accepted	Message accepted	Message accepted²	Fault	Fault	Fault	Message accepted	Fault
WS-Addressing support not enabled and messaging style asynchronous³	Fault	Fault	Fault	Fault	Fault	Fault	Fault	Fault

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.

Procedure

To modify the behavior of the WS-Addressing support by creating or modifying policy sets on either the service provider or client, see the topic: Enabling Web Services Addressing support for JAX-WS applications using policy sets.
Set the com.ibm.websphere.webservices.use.async.mep property on the client request context when using WebSphere® Application Server clients to enable WS-Addressing support.
See the topic: Invoking JAX-WS web services asynchronously for more information.
To modify the behavior of the WS-Addressing support by using the deployment descriptor of the service or client application, see the topic: Enabling Web Services Addressing support for JAX-WS applications using deployment descriptors.
To modify the behavior of the WS-Addressing support programmatically by using addressing annotations in the service application, or on the client with an injected web service proxy reference, see the topic: Enabling Web Services Addressing support for JAX-WS applications using addressing annotations.
To enable WS-Addressing support programmatically on the client by creating an instance of an addressing feature class, see the topic: Enabling Web Services Addressing support for JAX-WS applications using addressing features.
To modify the behavior of the WS-Addressing support during the development of a client or service application by adding WS-Policy assertions into the WSDL file, see the topic: Enabling Web Services Addressing support for JAX-WS applications using WS-Policy.

Results

WS-Addressing properties are now included in the SOAP message header, and are processed by the server on receipt of the message.