2 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 2-1. All properties are optional except wsa:Action.

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

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

A response to this message may appear as shown in Example 2-2. The RelatesTo property correlates the response message with the original 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/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>

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

• Asynchronous client transport, as described in Chapter 4, "Invoking Web Services Asynchronously".

• WS-ReliableMessaging, as described in Chapter 6, "Using Web Services Reliable Messaging".

• Callbacks, as described in Chapter 12, "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.

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, as described in the following sections:

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

• Enabling WS-Addressing on the Web Service (Starting from 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.

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 { ... }
}

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

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.

• Explicitly Enabling WS-Addressing on the Web Service Client

• Implicitly Enabling WS-Addressing on the Web Service Client

• Disabling WS-Addressing on the Web Service Client

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

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

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

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:

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

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

• Implicitly Associating WS-Addressing Action Properties

...
@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 {
...

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

targetNamespace/portTypeName/[inputName | outputName]

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

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 2-6.

To configure anonymous WS-Addressing:

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

2. Add the wsaw:Anonymous element to the wsdl:operation within the wsdl:binding element.

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