Skip Headers
Oracle® Fusion Middleware Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server
11g Release 1 (10.3.6)

Part Number E13734-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

2 Using Web Services Addressing

This chapter describes how to use Web Services Addressing (WS-Addressing) for WebLogic Web services using Java API for XML Web Services (JAX-WS).

This chapter includes the following sections:

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:

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

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

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.

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

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

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:

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:

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

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

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

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

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:

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

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

Table 2-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 2-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 2-6 Enabling WS-Addressing on a Web Service Client on the Dispatch Instance

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

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

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 2-7 Disabling WS-Addressing on a Web Service Client

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

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

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


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

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

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

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.

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.

Table 2-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:

  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.

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

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