+

Search Tips   |   Advanced Search

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 your code to specify WS-Addressing behavior at run time.

Use WS-Addressing annotations to enable WS-Addressing support, to specify whether WS-Addressing information is required in incoming messages, to control the message exchange pattern the service supports, and to specify actions to be associated with a web service operation or fault response.

The following WS-Addressing annotations are supported in WebSphere Application Server. These annotations are defined in the JAX-WS 2.2 specification unless otherwise stated. The JAX-WS 2.2 specification supersedes and includes functions within the JAX-WS 2.1 specification. See the Java API for XML-Based Web Services 2.2 specification for full details.

javax.xml.ws.Action

Specifies the action associated with a web service operation.

  • When following a bottom-up approach to developing JAX-WS web services, we can generate a WSDL document from Java application code using the wsgen command-line tool. However, for this attribute to be added to the WSDL operation, we must also specify the @Addressing annotation on the implementation class. The result in the generated WSDL document is that the Action annotations will have the wsam:Action attribute on the input message and output message elements of the wsdl:operation. Alternatively, if we do not want to use the @Addressing annotation we can supply our own WSDL document with the Action attribute already defined.

  • When following a top-down approach to developing JAX-WS web services, we can generate Java application code from an existing WSDL document using the wsimport command-line tool. In such cases, the resulting Java code will contain the correct Action and FaultAction annotations.

If this action is not specified in either code annotations or in the WSDL document, the default action pattern as defined in the Web Services Addressing 1.0 Metadata specification is used. Refer to this specification for full details.

Whilst the WAS runtime environment supports the deprecated wsaw:Action attribute, if we try to generate Java code from an old WSDL document containing the deprecated wsaw:Action attribute, this attribute will be ignored.

javax.xml.ws.FaultAction

Action that is added to a fault response. When we use this annotation with a particular method, the WS-Addressing FaultAction extension attribute is added to the fault element of the WSDL operation that corresponds to that method. For this attribute to be added to the WSDL operation, we must also specify the Addressing annotation on the implementation class. If we do not want to use the Addressing annotation we can supply our own WSDL document with the Action attribute already defined. This annotation must be contained within an Action annotation.

WSDL documents generated from Java application code containing the WS-Addressing FaultAction annotation will have the wsam:Action attribute on the fault message element of the wsdl:operation.

To ensure any custom Exception classes you write are successfully mapped to the generated WSDL document, extend the java.lang.Exception class instead of the java.lang.RuntimeException class.

javax.xml.ws.soap.Addressing

Specifies that this service is to enable WS-Addressing support. Use this annotation only on the service implementation bean; we cannot use it on the service endpoint interface.

com.ibm.websphere.wsaddressing.jaxws21.SubmissionAddressing

This annotation is part of the IBM implementation of the JAX-WS specification. This annotation specifies that this service is to enable WS-Addressing support for the 2004/08 WS-Addressing specification. Use this annotation only on the service implementation bean; we cannot use it on the service endpoint interface.

For more information about the Addressing and SubmissionAddressing annotations, including code examples, see Enable Web Services Addressing support for JAX-WS applications using addressing annotations.

The following example code uses the Action annotation to define the invoke operation to be invoked (input), and the action that is added to the response message (output). The example also uses the FaultAction annotation to specify the action that is added to a response message if a fault occurs: 

@WebService(name = "Calculator")
public interface Calculator {
   ...
  	 @Action(
      input="http://calculator.com/inputAction",
      output="http://calculator.com/outputAction",
      fault = { @FaultAction(className=AddNumbersException.class, 
                value="http://calculator.com/faultAction") 
      }
   )
   public int add(int value1, int value2) throws AddNumbersException {
      return value1 + value2;
   }
}
If we use a tool to generate service artifacts from code, the WSDL tags generated from the preceding example are as follows: 
<definitions targetNamespace="http://example.com/numbers" ...>
   ...
   <portType name="AddPortType">
      <operation name="Add">
         <input message="tns:AddInput" name="Parameters"
                         wsam:Action="http://calculator.com/inputAction"/>
         <output message="tns:AddOutput" name="Result"
           	               wsam:Action="http://calculator.com/outputAction"/>
         <fault message="tns:AddNumbersException" name="AddNumbersException"
           	              wsam:Action="http://calculator.com/faultAction"/>
      </operation>
    <portType>
    ...
<definitions>

  • Create a JAX-WS web service application that uses Web Services Addressing
  • Enable Web Services Addressing support for JAX-WS applications using addressing annotations
  • Enable Web Services Addressing support for JAX-RPC applications
  • JAX-WS annotations
  • wsgen command for JAX-WS applications
  • wsimport command for JAX-WS applications
  • Java API for XML-Based Web Services 2.2 specification
  • Web Services Addressing 1.0 Metadata specification