Enable Web Services Addressing support for JAX-WS applications

Enable 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, we can enable WS-Addressing support in several different ways, such as configuring policy sets or using annotations in code.

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 we do not have to undertake any actions to enable support. However, we 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, we 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. We 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 using the Addressing or SubmissionAddressing annotations in the service code. Within each annotation we 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 we do provide our own WSDL document, instead of relying on the JAX-WS runtime environment to generate one, and the 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 we 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 we 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 we add Addressing annotations to the 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.

Client settings Provider policy settings Provider WSDL settings (UsingAddressing required attribute)
WS-Addressing is optional WS-Addressing is mandatory¹
Synchronous and asynchronous Synchronous only Asynchronous only Synchronous and asynchronous Synchronous only Asynchronous only false (WS-Addressing is optional) 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

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).

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

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 creating or modifying policy sets on either the service provider or client, see the topic: Enable 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: Enable 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: Enable WS-Addressing for JAX-WS applications.

To enable WS-Addressing support programmatically on the client by creating an instance of an addressing feature class, see the topic: Enable 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: Enable 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.

Subtopics

Enable Web Services Addressing support for JAX-WS applications using policy sets
For JAX-WS applications, we can enable WS-Addressing support after you deploy an application to the server, by creating or modifying policy sets, and attaching those policy sets to either a service or client application.

Enable Web Services Addressing support for JAX-WS applications using deployment descriptors
For JAX-WS applications, we can enable WS-Addressing support during the packaging of either a service or client application, by editing the deployment descriptor for that application.

Enable WS-Addressing for JAX-WS applications
For JAX-WS applications, we can enable WS-Addressing support during development of a service application, by using addressing annotations in the code. We can also use this method in a client application that uses an injected web service proxy reference.

Enable Web Services Addressing support for JAX-WS applications using addressing features
For JAX-WS applications, we can enable WS-Addressing support during development of a client application, by using addressing features in the code.

Enable Web Services Addressing support for JAX-WS applications using WS-Policy
For JAX-WS applications, we can enable WS-Addressing support during the development of a client or service application by adding WS-Policy assertions into the WSDL document.

Web Services Addressing annotations
The WS-Addressing specification provides transport-neutral mechanisms to address web services and to facilitate end-to-end addressing. If we have a JAX-WS application we can use Java annotations in our code to specify WS-Addressing behavior at run time.

Web Services Addressing security
It is essential that communications that use Web Services Addressing (WS-Addressing) are adequately secured and that a sufficient level of trust is established between the communicating parties. We can achieve secure communications through the signing of WS-Addressing message-addressing properties and the encryption of endpoint references.

Invoking JAX-WS web services asynchronously
JAX-WS provides support for invoking web services using an asynchronous client invocation. JAX-WS provides support for both a callback and polling model when calling web services asynchronously. Both the callback model and the polling model are available on the Dispatch client and the Dynamic Proxy client.

Related concepts

IBM proprietary Web Services Addressing SPIs

Related tasks

Enable Web Services Addressing support for JAX-RPC applications
Manage policy sets using the administrative console
Configure the WS-Addressing policy
Attaching a policy set to a service artifact
Configure a service provider to share its policy configuration
Configure the client policy to use a service provider policy
Invoking JAX-WS web services asynchronously
Disable Web Services Addressing support

Client settings	Provider policy settings	Provider WSDL settings (UsingAddressing required attribute)
WS-Addressing is optional	WS-Addressing is mandatory¹
Synchronous and asynchronous	Synchronous only	Asynchronous only	Synchronous and asynchronous	Synchronous only	Asynchronous only	false (WS-Addressing is optional)	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

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