Enable Web Services Addressing support for JAX-WS applications

 

+

Search Tips   |   Advanced Search

New feature: WAS v7.0 allows you to use JAX-WS 2.1 annotations to enable WS-Addressing from either the server or the client.

We can specify whether WS-Addressing is enabled and whether to use synchronous and/or asynchronous.

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 perform 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. Settings set using this method override those set using 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 we 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 we provide our own WSDL document instead of relying on the JAX-WS runtime environment to generate one, include the UsingAddressing element theself, if required.

For service clients, WS-Addressing support is disabled by default. Use one of the following methods to enable WS-Addressing support:

• Specify the UsingAddressing element in the WSDL document for the service.

  If the service uses the Addressing annotation and the WSDL document is generated from the code, the UsingAddressing element will already exist.

• Use addressing features in the client code.

  Settings set using this method override those set in the WSDL document for the service.

• Set the property...

  com.ibm.websphere.webservices.use.async.mep property

  ...on the client request context.

  We can also use any option available to JAX-RPC applications, such as manually adding the UsingAddressing element to the WSDL document, or using the IBM proprietary WS-Addressing SPI to add message-addressing properties to the message request context.

The behavior of the WS-Addressing support is summarized in the following paragraphs. WAS clients add WS-Addressing headers to messages in the following situations:

• A policy set containing a WS-Addressing policy is attached to a client artifact, and one or both of the following statements are true:

  • The WS-Addressing policy for the client specifies that WS-Addressing is mandatory.

  • The client artifact has provider and client policies applied, policy sharing is enabled on the server, and the policy configuration for the server requires WS-Addressing.

• The client application code uses a WS-Addressing feature class to specify that WS-Addressing is enabled.

• The WSDL document for the service contains the UsingAddressing element, for example if the document was generated from service application code that contains the Addressing annotation.

  The value of the required parameter is irrelevant.

  This statement does not apply to Dispatch clients, because these clients do not use the WSDL document.

• Message-addressing properties are set on the client.

• The com.ibm.websphere.webservices.use.async.mep property is set on the client request context.

If a client does not include WS-Addressing headers in messages, the server generates a fault message in the following situations:

• A policy set containing a WS-Addressing policy is attached to a server artifact, and the WS-Addressing policy specifies that WS-Addressing is mandatory.

• The server application code uses the Addressing or SubmissionAddressing annotation to specify that WS-Addressing is required.

 

Procedure

• To modify the behavior of the WS-Addressing support using policy sets...
  1. Ensure that we have a policy set that contains the WS-Adressing policy type.
  2. Set the WS-Addressing policy type

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

  3. Attach the policy set to a Web service provider or client artifact.

  4. Configure policy sharing or set the client policy using 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 to use the 2005/08 WS-Addressing spec

  • SubmissionAddressing - Use this annotation 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 javax.xml.ws.soap.Addressing;
  
  @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 spec in inbound SOAP messages. If we 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 spec 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 we use the Addressing annotation and generate a WSDL document from the code, a UsingAddressing element, with parameters that match those of the annotation, is created in the WSDL document. Clients using 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 spec and the 2004/08 specification, so to generate a WSDL document from code that contains a SubmissionAddressing annotation, we can do so by using both the Addressing and SubmissionAddressing annotations together.

  Use the Addressing annotation only with a SOAP (1.1 or 1.2) over HTTP binding. If we 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 we create the WSDL document manually rather than generating it from the code.

  If we 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. WAS ND v7.0 supports both prefixes, but if we 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 to send messages that include WS-Addressing headers that conform to the 2005/08 WS-Addressing spec

  • SubmissionAddressingFeature - use this class 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 spec should be used...

  AddressingFeature feat = new AddressingFeature(true, required);

  To specify that WS-Addressing is disabled for the 2004/08 specification...

  SubmissionAddressingFeature feat = new SubmissionAddressingFeature(false);

  If we specify that WS-Addressing is enabled, the client includes WS-Addressing headers in SOAP messages. The required property is ignored, but could be used by the application to check that the client has created the correct headers. The headers conform to the WS-Addressing spec 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.

• Use the addressing feature classes only with a SOAP (1.1 or 1.2) over HTTP binding.

  If we 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 we use both feature classes, the spec used depends on the type of endpoint reference that you also specify.

  For example, if we specify a W3CEndpointReference object, the spec used is the 2005/08 specification. If we do not specify an endpoint reference, the default spec is the 2005/08 specification. If we 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 WAS clients, we can also enable WS-Addressing support by setting the property...

com.ibm.websphere.webservices.use.async.mep

...on the client request context.

 

Results

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

 

Related tasks

Enable Web Services Addressing support for JAX-RPC applications
Manage policy sets
Set the WS-Addressing policy
Attach a policy set to a service artifact
Set a service provider to share its policy configuration
Set the client.policy using a service provider policy
Invoking JAX-WS Web services asynchronously
Develop applications that use Web Services Addressing

 

Related

IBM proprietary Web Services Addressing SPIs