Using Web Services Addressing

Overview of WS-Addressing

WS-Addressing provides a transport-neutral mechanism to address web services and their associated messages. Using WS-Addressing, endpoints are uniquely and unambiguously defined in the SOAP header.

WS-Addressing provides two key components that enable transport-neutral addressing, including:

Endpoint reference (EPR)—Communicates the information required to address a web service endpoint.

Message addressing properties—Communicates end-to-end message characteristics, including addressing for source and destination endpoints and message identity, that allows uniform addressing of messages independent of the underlying transport.

Message addressing properties can include one or more of the properties defined in Table 10-1. All properties are optional except wsa:Action.

Table 10-1 WS-Addressing Message Addressing Properties

Component	Description
`wsa:To`	Destination. If not specified, the destination defaults to `http://www.w3.org/2005/08/addressing/anonymous`.
`wsa:From`	Source endpoint.
`wsa:ReplyTo`	Reply endpoint. If not specified, the reply endpoint defaults to `http://www.w3.org/2005/08/addressing/anonymous`.
`wsa:FaultTo`	Fault endpoint.
`wsa:Action`	Required action. This property is required when WS-Addressing is enabled. It can be implicitly or explicitly configured, as described in Associating WS-Addressing Action Properties.
`wsa:MessageID`	Unique ID of the message.
`wsa:RelatesTo`	Message ID to which the message relates. This element can be repeated if there are multiple related messages. You can specify `RelationshipType` as an attribute of this property, which defaults to `http://www.w3.org/2005/08/addressing/reply`.
`wsa:ReferenceParameters`	Reference parameters that need to be communicated.

Example 10-1 shows a SOAP 1.2 request message sent over HTTP 1.2 with WS-Addressing enabled. As shown in bold, WS-Addressing provides a transport-neutral mechanism for defining a unique ID for the message (wsa:MessageID), the destination (wsa:To) endpoint, the reply endpoint (wsa:ReplyTo), and the required action (wsa:Action).

A response to this message may appear as shown in Example 10-2. The RelatesTo property correlates the response message with the original request message.

WS-Addressing is used by the following advanced WebLogic JAX-WS features:

Asynchronous client transport, as described in Developing Asynchronous Clients.
WS-ReliableMessaging, as described in Using Web Services Reliable Messaging.
Callbacks, as described in Using Callbacks.

The following sections describe how to enable WS-Addressing on the web service or client, and explicitly define the action and fault properties.

A Note About WS-Addressing Standards Supported

WebLogic web services support the following standards for web service addressing:

W3C WS-Addressing, as described at: http://www.w3.org/2002/ws/addr/
Member Submission, as described at: http://www.w3.org/Submission/ws-addressing/

This chapter focuses on the use of W3C WS-Addressing only.

Example 10-1 SOAP 1.2 Message With WS-Addressing—Request Message

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" 
            xmlns:wsa="http://www.w3.org/2005/08/addressing/">  
  <S:Header>  
    <wsa:MessageID>   
      http://example.com/someuniquestring  
    </wsa:MessageID>  
    <wsa:ReplyTo
      <wsa:Address>http://example.com/Myclient</wsa:Address>
    </wsa:ReplyTo>
    <wsa:To>   
      http://example.com/fabrikam/Purchasing  
    </wsa:To>  
    <wsa:Action>   
      http://example.com/fabrikam/SubmitPO  
    </wsa:Action>  
  <S:Header>  
  <S:Body>   
    ...   
   </S:Body>   
</S:Envelope>

Example 10-2 SOAP 1.2 Message Without WS-Addressing—Response Message

<S:Envelope
  xmlns:S="http://www.w3.org/2003/05/soap-envelope" 
  xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <S:Header>
    <wsa:MessageID>http://example.com/someotheruniquestring</wsa:MessageID>
    <wsa:RelatesTo>http://example.com/someuniquestring</wsa:RelatesTo>
    <wsa:To>http://example.com/MyClient/wsa:To>
    <wsa:Action>   
      http://example.com/fabrikam/SubmitPOAck  
    </wsa:Action>  
  </S:Header>
  <S:Body>
    ...
  </S:Body>
</S:Envelope>

Parent topic: Using Web Services Addressing

Enabling WS-Addressing on the Web Service

By default, WS-Addressing is disabled on a web service endpoint, and any WS-Addressing headers received are ignored. You can enable WS-Addressing on the Web Service starting from Java or WSDL.

When you enable WS-Addressing on a web service endpoint:

All WS-Addressing headers are understood by the endpoint. That is, if any WS-Addressing header is received with mustUnderstand enabled, then no fault is thrown.
WS-Addressing headers received are validated to ensure:
- Correct syntax
- Correct number of elements
- wsa:Action header in the SOAP header matches what is required by the operation
Response messages returned to the client contain the required WS-Addressing headers.

Parent topic: Using Web Services Addressing

Enabling WS-Addressing on the Web Service (Starting From Java)

To enable WS-Addressing on the web service starting from Java, use the java.xml.ws.soap.Addressing annotation on the web service class. Optionally, you can pass one or more of the Boolean attributes defined in Table 10-2.

Table 10-2 Attributes of the @Addressing Annotation

Attribute	Description
`enabled`	Specifies whether WS-Addressing is enabled. Valid values include `true` (enabled) and `false` (disabled). This attribute defaults to `true`.
`required`	Specifies whether WS-Addressing rules are enforced for the inbound message. Valid values include `true` (enforced) and `false` (not enforced). If set to `false`, the inbound message is checked to see if WS-Addressing is enabled, and, if so, the rules are enforced. This attribute defaults to `false`.

Once enabled, the wsaw:UsingAddressing element is generated in the corresponding wsdl:binding element. For more information, see Enabling WS-Addressing on the Web Service (Starting from WSDL).

The following provides an example of how to enable WS-Addressing starting from Java. In this example, WS-Addressing is enforced on the endpoint (required is set to true).

Example 10-3 Enabling WS-Addressing on the Web Service (Starting From Java)

package examples;
import javax.jws.WebService;
import javax.xml.ws.soap.Addressing;
 
@WebService(name="HelloWorld", serviceName="HelloWorldService")
@Addressing(enabled=true, required=false)
 
public class HelloWorld {
   public String sayHelloWorld(String message) throws MissingName { ... }
}

Parent topic: Enabling WS-Addressing on the Web Service

Enabling WS-Addressing on the Web Service (Starting from WSDL)

To enable WS-Addressing on the web service starting from WSDL, add the wsaw:UsingAddressing element to the corresponding wsdl:binding element. Optionally, you can add the wsdl:required Boolean attribute to specify whether WS-Addressing rules are enforced for the inbound message. By default, this attribute is false.

The following provides an example of how to enable WS-Addressing starting from WSDL. In this example, WS-Addressing is enforced on the endpoint (wsdl:required is set to true).

Example 10-4 Enabling WS-Addressing on the Web Service (Starting From WSDL)

...
  <binding name="HelloWorldPortBinding" type="tns:HelloWorld">
    <wsaw:UsingAddressing wsdl:required="true" />
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
      style="document"/>
    <operation name="sayHelloWorld">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="MissingName">
        <soap:fault name="MissingName" use="literal"/>
      </fault>
    </operation>
  </binding>
...

Parent topic: Enabling WS-Addressing on the Web Service

Enabling WS-Addressing on the Web Service Client

WS-Addressing can be enabled on the web service client implicitly or explicitly. Once enabled on the client:

All WS-Addressing headers received on the client are understood. That is, if any WS-Addressing header is received with mustUnderstand enabled, then no fault is thrown.
The JAX-WS runtime:
- Maps all wsaw:Action elements, including input, output, and fault elements in the wsdl:operation to javax.xml.ws.Action and javax.xml.ws.FaultAction annotations in the generated service endpoint interface (SEI).
- Generates Action, To, MessageID, and anonymous ReplyTo headers on the outbound request.

The following sections describe how to enable WS-Addressing on the web service client explicitly and implicitly, and how to disable WS-Addressing explicitly.

Parent topic: Using Web Services Addressing

Explicitly Enabling WS-Addressing on the Web Service Client

The web service client can enable WS-Addressing explicitly by passing javax.xml.ws.soap.AddressingFeature as an argument to the getPort or createDispatch methods on the javax.xml.ws.Service object. Optionally, you can pass one or more of the Boolean parameters defined in Table 10-3.

Table 10-3 Parameters of the AddressingFeature Feature

Parameter	Description
`enabled`	Specifies whether WS-Addressing is enabled for an outbound message. Valid values include `true` (enabled) and `false` (disabled). This attribute defaults to `true`.
`required`	Specifies whether WS-Addressing rules are enforced for the inbound messages. Valid values include `true` (enforced) and `false` (not enforced). If set to `false`, the inbound message is checked to see if WS-Addressing is enabled, and, if so, the rules are enforced. This attribute defaults to `false`.

The following shows an example of enabling WS-Addressing on a web service client when creating a web service proxy, by passing the AddressingFeature to the getPort method.

Example 10-5 Enabling WS-Addressing on a Web Service Client on the Web Service Proxy

package examples.client;
 
import javax.xml.namespace.QName;
import java.net.MalformedURLException;
import java.net.URL;
import examples.client.MissingName_Exception;
import javax.xml.ws.soap.AddressingFeature;

public class Main {
  public static void main(String[] args) throws MissingName_Exception {
    HelloWorldService service;
 
    try {
      service = new HelloWorldService(new URL(args[0] + "?WSDL"), 
                new QName("http://examples/", "HelloWorldService") );
    } catch (MalformedURLException murl) { throw new RuntimeException(murl); }
      
      HelloWorld port = service.getHelloWorldPort(
        new AddressingFeature(true, true));
...
  }
}

The following shows an example of enabling WS-Addressing on a web service client when creating a Dispatch instance, by passing the AddressingFeature to the createDispatch method.

Example 10-6 Enabling WS-Addressing on a Web Service Client on the Dispatch Instance

...
      HelloWorld port = service.getHelloWorldPort(new AddressingFeature(true));
...

Parent topic: Enabling WS-Addressing on the Web Service Client

Implicitly Enabling WS-Addressing on the Web Service Client

WS-Addressing is enabled implicitly if the wsaw:UsingAddressing extensibility element exists in the WSDL For more information, see Enabling WS-Addressing on the Web Service (Starting from WSDL).

Parent topic: Enabling WS-Addressing on the Web Service Client

Disabling WS-Addressing on the Web Service Client

A web service client may need to disable WS-Addressing processing explicitly, for example, if it has its own WS-Addressing processing module. For example, a Dispatch client in MESSAGE mode may be used to perform non-anonymous ReplyTo and FaultTo processing.

The following shows an example of how to disable explicitly WS-Addressing on a web service client when creating a web service proxy. In this example, the AddressingFeature feature is called with enabled set to false.

Example 10-7 Disabling WS-Addressing on a Web Service Client

...
new AddNumbersImplService().getAddNumbersImplPort(new javax.xml.ws.AddressingFeature(false));
...

Parent topic: Enabling WS-Addressing on the Web Service Client

Associating WS-Addressing Action Properties

WS-Addressing defines an attribute, wsaw:Action, that can be used to explicitly associate WS-Addressing action message addressing properties with the web service. By default, an implicit action association is made when WS-Addressing is enabled and no action is explicitly associated with the web service.

The following sections describe how to associate WS-Addressing Action properties either explicitly or implicitly:

Parent topic: Using Web Services Addressing

Explicitly Associating WS-Addressing Action Properties (Starting from Java)

To explicitly associate WS-Addressing action properties with the web service starting from Java, use the javax.xml.ws.Action and javax.xml.ws.FaultAction annotations.

Optionally, you can pass to the @Action annotation one or more of the attributes defined in Table 10-4.

Table 10-4 Attributes of the @Action Annotation

Attribute	Description
`input`	Associates Action message addressing property for the input message of the operation.
`output`	Associates Action message addressing property for the output message of the operation.
`fault`	Associates Action message addressing property for the fault message of the operation. Each exception that is mapped to a SOAP fault and requires explicit association must be specified using the `@FaultAction` annotation, as described in Table 10-5.

You can pass to the @FaultAction annotation one or more of the attributes defined in Table 10-4.

Table 10-5 Attributes of the @FaultAction Annotation

Attribute	Description
`className`	Name of the exception class. This attribute is required.
`value`	Value of the WS-Addressing Action message addressing property for the exception.

Once you explicitly associate the WS-Addressing action properties, the wsaw:Action attribute is generated in the corresponding input, output, and fault elements in the wsdl:portType element. For more information, see Enabling WS-Addressing on the Web Service (Starting from WSDL).

The following provides an example of how to explicitly associate the WS-Addressing action message addressing properties for the input, output, and fault messages on the sayHelloWorld method, using the @Action and @FaultAction annotations.

Example 10-8 Example of Explicitly Associating an Action (Starting from Java)

...
@Action(
   input = "http://examples/HelloWorld/sayHelloWorldRequest",
   output = "http://examples/HelloWorld/sayHelloWorldResponse",
   fault = { @FaultAction(className = MissingName.class,
                value = "http://examples/MissingNameFault")})
 
   public String sayHelloWorld(String message) throws MissingName {
...

Once defined, the wsaw:Action element is generated in the corresponding input, output, and fault elements of the wsdl:operation element for the endpoint. For more information about these elements, see Explicitly Associating WS-Addressing Action Properties (Starting from WSDL).

Parent topic: Associating WS-Addressing Action Properties

Explicitly Associating WS-Addressing Action Properties (Starting from WSDL)

To explicitly associate WS-Addressing action properties with the web service starting from WSDL, add the wsaw:Action element to the corresponding wsdl:binding element. Optionally, you can add the wsdl:required Boolean attribute to specify whether WS-Addressing rules are enforced for the inbound message. By default, this attribute is false.

The following provides an example of how to, within the WSDL file, explicitly associate the WS-Addressing action message addressing properties for the input, output, and fault messages on the sayHelloWorld method of the HelloWorld endpoint.

Example 10-9 Example of Explicitly Associating an Action (Starting from WSDL)

...
  <portType name="HelloWorld">
    <operation name="sayHelloWorld">
      <input wsaw:Action="http://examples/HelloWorld/sayHelloWorldRequest"
       message="tns:sayHelloWorld"/>
      <output wsaw:Action="http://examples/HelloWorld/sayHelloWorldResponse" 
       message="tns:sayHelloWorldResponse"/>
      <fault message="tns:MissingName" name="MissingName" 
       wsaw:Action="http://examples/MissingNameFault"/>
    </operation>
  </portType>
...

Parent topic: Associating WS-Addressing Action Properties

Implicitly Associating WS-Addressing Action Properties

When WS-Addressing is enabled, if no explicit action is defined in the WSDL, the client sends an implicit wsa:Action header using the following formats:

Input message action: targetNamespace/portTypeName/inputName
Output message action: targetNamespace/portTypeName/outputName
Fault message action: targetNamespace/portTypeName/operationName/Fault/FaultName

targetNamespace/portTypeName/[inputName | outputName]

For example, for the following WSDL excerpt:

<definitions targetNamespace="http://examples/"...>
...
  <portType name="HelloWorld">
    <operation name="sayHelloWorld">
      <input message="tns:sayHelloWorld" name="sayHelloRequest"/>
      <output message="tns:sayHelloWorldResponse" name="sayHelloResponse"/>
      <fault message="tns:MissingName" name="MissingName" />
    </operation>
  </portType>
...
</definitions>

The default input and output actions would be defined as follows:

Input message action: http://examples/HelloWorld/sayHelloRequest
Output message action: http://examples/HelloWorld/sayHelloResponse
Fault message action: http://examples/HelloWorld/sayHelloWorld/Fault/MissingName

If the input or output message name is not specified in the WSDL, the operation name is used with Request or Response appended, respectively. For example: sayHelloWorldRequest or sayHelloWorldResponse.

Parent topic: Associating WS-Addressing Action Properties

Configuring Anonymous WS-Addressing

In some cases, the network technologies used in an environment (such as, firewalls, Dynamic Host Configuration Protocol (DHCP), and so on) may prohibit the use of globally addressed URI for a given endpoint. To enable non-addressable endpoints to exchange messages, the WS-Addressing specification supports "anonymous" endpoints using the wsaw:Anonymous element.

The wsaw:Anonymous element can be set to one of the values defined in Table 10-6.

Table 10-6 Valid Values for the wsaw:Anonymous Element

Value	Description
`optional`	The response endpoint EPR in a request message may contain an anonymous URI.
`required`	The response endpoint EPR in a request message must contain an anonymous URL. Otherwise, an `InvalidAddressingHeader` fault is returned.
`prohibited`	The response endpoint EPRs in a request message must not contain an anonymous URI. Otherwise, an `InvalidAddressingHeader` fault is returned.

To configure anonymous WS-Addressing:

Enable WS-Addressing on the web service, add the wsaw:UsingAddressing element to the corresponding wsdl:binding element. For more information, see Enabling WS-Addressing on the Web Service (Starting from WSDL).

Note:

When anonymous WS-Addressing is enabled, the wsdl:required attribute must not be enabled in the wsaw:UsingAddressing element.
Add the wsaw:Anonymous element to the wsdl:operation within the wsdl:binding element.

Example 10-10 Enabling Anonymous WS-Addressing on the Web Service

The following provides an example of how to enable anonymous WS-Addressing in the WSDL file. In this example, anonymous addressing is required.

...
  <binding name="HelloWorldPortBinding" type="tns:HelloWorld">
    <wsaw:UsingAddressing wsdl:required="true" />
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
      style="document"/>
    <operation name="sayHelloWorld">
      <soap:operation soapAction=""/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
      <fault name="MissingName">
        <soap:fault name="MissingName" use="literal"/>
      </fault>
    </operation>
    <wsaw:Anonymous>required</wsaw:Anonymous>
  </binding>
...

Parent topic: Using Web Services Addressing