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:
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 |
|---|---|
|
|
Destination. If not specified, the destination defaults to |
|
|
Source endpoint. |
|
|
Reply endpoint. If not specified, the reply endpoint defaults to |
|
|
Fault endpoint. |
|
|
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. |
|
|
Unique ID of the message. |
|
|
Message ID to which the message relates. This element can be repeated if there are multiple related messages. You can specify |
|
|
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).
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:
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.
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.
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 |
|---|---|
|
|
Specifies whether WS-Addressing is enabled. Valid values include |
|
|
Specifies whether WS-Addressing rules are enforced for the inbound message. Valid values include |
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 { ... }
}
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>
...
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.
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 |
|---|---|
|
|
Specifies whether WS-Addressing is enabled for an outbound message. Valid values include |
|
|
Specifies whether WS-Addressing rules are enforced for the inbound messages. Valid values include |
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.
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).
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.
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)
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 |
|---|---|
|
|
Associates Action message addressing property for the input message of the operation. |
|
|
Associates Action message addressing property for the output message of the operation. |
|
|
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 |
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 |
|---|---|
|
|
Name of the exception class. This attribute is required. |
|
|
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).
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>
...
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.
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 |
|---|---|
|
|
The response endpoint EPR in a request message may contain an anonymous URI. |
|
|
The response endpoint EPR in a request message must contain an anonymous URL. Otherwise, an |
|
|
The response endpoint EPRs in a request message must not contain an anonymous URI. Otherwise, an |
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, thewsdl: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.
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>
...