Table of Contents
This chapter describes transport-independent web services addressing with some examples.
Web services addressing is used to define an address for a web service message in a transport-independent way. Since a web service is basically exchanging of stateless messages, web services addressing enables the support for stateful web services. Web services addressing is a basic technology included in many WS-* specifications, including WS-RM, WS-Security, WS-secure Conversation, and WS-Trust, which will be discussed in the following chapters.
Web services addressing works with either of the transport methods, HTTP or SMTP. The following shows how web services addressing works at the message level. If a user tries to add information to a message from the application level without setting the web services addressing configuration, the message will look like the following example.
POST /AddNumbers/addnumbers HTTP 1.1/POST
Host: tmaxsoft.com
SOAPAction: http://tmaxsoft.com/AddNumbers/addnumbers
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
xmlns:tmax="http://tmaxsoft.com/">
<S:Header>
<tmax:MessageID>
uuid:e197db59-0982-4c9c-9702-4234d204f7f4
</tmax:MessageID>
</S:Header>
<S:Body>
...
</S:Body>
</S:Envelope>
As shown in the previous example, the message ID given by the application is used only at the application level, and cannot be used in other applications. In addition, if the transport method is converted from HTTP to SMTP, this creates more difficulties, such as the need to convert the information in the transport header using the mapping rule. To resolve these difficulties, W3C specifies the binding to a SOAP message or WSDL document by defining MAP(Message Addressing Properties) for web services addressing.
The following shows a web services addressing enabled message that includes the MAP information at the message level.
POST /AddNumbers/addnumbers HTTP 1.1/POST
Host: tmaxsoft.com
SOAPAction: http://tmaxsoft.com/AddNumbers/addnumbers
<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>
uuid:e197db59-0982-4c9c-9702-4234d204f7f4
</wsa:MessageID>
<wsa:To>
http://tmaxsoft.com/AddNumbers/addnumbers
</wsa:To>
<wsa:Action>
http://tmaxsoft.com/AddNumbers/addnumbers
</wsa:Action>
</S:Header>
<S:Body>
...
</S:Body>
</S:Envelope>
A web services addressing enabled SOAP message contains web services addressing related elements such as <wsa:MessageID>, <wsa:To>, and <wsa:Action>. They are bound to a SOAP message that contains the MAP(Message Addressing Property) information.
The following describes each element.
| element | Description |
|---|---|
| <wsa:MessageID> | Absolute URI that uniquely identifies the message. |
| <wsa:To> | Absolute URI that shows the receiver's address. |
| <wsa:Action> | Absolute URI that shows what the message means. |
Such a web services addressing enabled message has a specific format that enables the processing of all contents in the message in a transport-independent and application-independent way. For instance, to transmit such a message through a transport method, besides HTTP, like SMTP, the only thing that needs to be done is to modify the wsa:To header value to a value like "mailto:purchasing@example.com".
This section describes how to configure web services addressing and execution method with examples.
Web services addressing can be configured from either a Java class or WSDL. This section describes each method.
To configure web services addressing from a Java class, simply add the javax.xml.ws.soap.Addressing and java x.jws.WebService annotations.
[Example 14.1] << AddnumbersImpl.java >>
@Addressing
@WebService
public class AddNumbersImpl {
...
}
The following steps are performed by the service endpoint when web services addressing is configured through the javax.xml.ws.soap.Addressing annotation as shown in the previous example.
Creates the standard <wsaw:UsingAddressing> element inside the <wsdl:binding> element of the created WSDL document.
Interprets and examines all web services addressing headers of the message for correct grammar.
Transmits an error message if the grammar is incorrect.
Transmits an error message if the <wsa:Action> header value is not identical to the expected value for the operation.
All transmitted messages contain web services addressing header related information.
Through web services addressing, a user can set an Action MAP(Message Addressing Property) for a service endpoint interface method (the operation element in WSDL document) as in the following example.
[Example 14.2] << AddnumbersImpl.java >>
@Addressing
@WebService
public class AddNumbersImpl {
@Action(
input = "http://tmaxsoft.com/input",
output = "http://tmaxsoft.com/output",
fault = {
@FaultAction(className = AddNumbersException.class,
value = "http://tmaxsoft.com/fault")
}
)
public int addNumbers(int number1, int number2)
throws AddNumbersException {
...
}
}
When converted to WSDL, the method is bound to the operation element in the following WSDL document.
[Example 14.3] << Addnumbers.wsdl >>
...
<operation name="addNumbers">
<input wsaw:Action="http://tmaxsoft.com/input"
message="tns:addNumbers"/>
<output wsaw:Action="http://tmaxsoft.com/output"
message="tns:addNumbersResponse"/>
<fault wsaw:Action="http://tmaxsoft.com/fault"
message="tns:AddNumbersException"
name="AddNumbersException"/>
</operation>
...
<binding name="AddNumbersImplPortBinding" type="tns:AddNumbersImpl">
<wsaw:UsingAddressing />
<soap:binding transport="http://schemas.xmlsoap.org/soap/http"
style="document" />
<operation name="addNumbers">
<soap:operation soapAction="" />
<input>
<soap:body use="literal" />
</input>
<output>
<soap:body use="literal" />
</output>
</operation>
<operation name="addNumbers2">
<soap:operation soapAction="" />
<input>
<soap:body use="literal" />
</input>
<output>
<soap:body use="literal" />
</output>
</operation>
</binding>
...
The wsimport tool automatically determines the addressing setting of the client web service depending on whether the <wsaw:UsingAddressing> element is included in the WSDL document, which is referenced when creating a client.
Sometimes, the web services addressing function may not be executed when creating a client from the service if the client is separately executing the function at the application level.
The following code disables web services addressing from running on the client.
new AddNumbersImplService().getAddNumbersImplPort(
new javax.xml.ws.AddressingFeature(false));
As shown in the previous example, if javax.xml.ws.AddressingFeature is set to false when obtaining a proxy (endpoint interface) from a client, the client can transmit a message without running the web services addressing defined in WSDL.
When WSDL of the service does not include 'wsaw:UsingAddressing' that enables addressing, portable artifacts obtained through the wsimport tool can only perform web service functions. To enable web services addressing separately on the client, use methods supported by the javax.xml.ws.Service class, or use the javax.xml.ws.soap.AddressingFeature class.
<T> Dispatch<T> createDispatch(javax.xml.namespace.QName,
java.lang.Class<T>, Service.Mode, WebServiceFeature...)
Dispatch<java.lang.Object> createDispatch(javax.xml.namespace.QName,
javax.xml.bind.JAXBContext, Service.Mode, WebServiceFeature...)
<T> T getPort(java.lang.Class<T>, WebServiceFeature...)
<T> T getPort(javax.xml.namespace.QName, java.lang.Class<T>,
WebServiceFeature...)
new AddNumbersImplService().getAddNumbersImplPort(
new javax.xml.ws.AddressingFeature());
The following is an example of the service endpoint implementation class.
[Example 14.4] << AddNumbersImpl.java >>
@Addressing @WebService public class AddNumbersImpl { @Resource WebServiceContext wsc; @Action(input = "http://tmaxsoft.com/input", output = "http://tmaxsoft.com/output") public int addNumbers(int number1, int number2) { return number1 + number2; } public int addNumbers2(int number1, int number2) { return number1 + number2; } }
As shown in the previous example, web services addressing is configured by using the 'action' annotation, which will be bound to the 'addressing' annotation and the 'operation' element in the WSDL document.
The following example shows how to create a web service by using addressing enabled endpoint classes and other configuration files, and deploy it to JEUS 7.
$ ant deploy
Once the service is successfully deployed, execute the client.
The client and server consoles will display the result that the message has been successfully transmitted.
$ ant run
...
run:
[java] ################################################
[java] ### JAX-WS Webservices examples - addressing ###
[java] ################################################
[java] basic name mapping result: 20
[java] default name mapping result: 20
BUILD SUCCESSFUL
...
...
---[HTTP request]---
Host: localhost:8088
Content-length: 626
Content-type: text/xml; charset=utf-8
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg,
*; q=.2, */*; q=.2
Connection: keep-alive
Soapaction: "http://tmaxsoft.com/input"
User-agent: JAX-WS RI 2.2 - JEUS 7
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<S:Header>
<wsa:To>http://localhost:8088/AddNumbers/addnumbers</wsa:To>
<wsa:Action>http://tmaxsoft.com/input</wsa:Action>
<wsa:ReplyTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>
http://www.w3.org/2005/08/addressing/anonymous
</wsa:Address>
</wsa:ReplyTo>
<wsa:MessageID>uuid:880f3891-d07b-4ad1-bbc1-8dce8f1aedef</wsa:MessageID>
</S:Header>
<S:Body>
<ns2:addNumbers xmlns:ns2="http://server.wsaddressing/">
<arg0>10</arg0><arg1>10</arg1>
</ns2:addNumbers>
</S:Body>
</S:Envelope>
---[HTTP response 200]---
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<S:Header>
<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
<wsa:Action>http://tmaxsoft.com/output</wsa:Action>
<wsa:MessageID>uuid:815cb296-a2f3-45df-80c5-5a2c1ca836ca</wsa:MessageID>
<wsa:RelatesTo>uuid:880f3891-d07b-4ad1-bbc1-8dce8f1aedef</wsa:RelatesTo>
</S:Header>
<S:Body>
<ns2:addNumbersResponse xmlns:ns2="http://server.wsaddressing/">
<return>20</return>
</ns2:addNumbersResponse>
</S:Body>
</S:Envelope>
--------------------
...
---[HTTP request]---
Host: localhost:8088
Content-length: 663
Content-type: text/xml; charset=utf-8
Accept: text/xml, multipart/related, text/html, image/gif, image/jpeg,
*; q=.2, */*; q=.2
Connection: keep-alive
Soapaction: "http://server.wsaddressing/AddNumbersImpl/addNumbers2Request"
User-agent: JAX-WS RI 2.2 - JEUS 7
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<S:Header>
<wsa:To>http://localhost:8088/AddNumbers/addnumbers</wsa:To>
<wsa:Action>
http://server.wsaddressing/AddNumbersImpl/addNumbers2Request
</wsa:Action>
<wsa:ReplyTo xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsa:Address>
http://www.w3.org/2005/08/addressing/anonymous
</wsa:Address>
</wsa:ReplyTo>
<wsa:MessageID>uuid:bf65c920-9129-495a-b9dc-8cb8efb9c2a6</wsa:MessageID>
</S:Header>
<S:Body>
<ns2:addNumbers2 xmlns:ns2="http://server.wsaddressing/">
<arg0>10</arg0><arg1>10</arg1>
</ns2:addNumbers2>
</S:Body>
</S:Envelope>
---[HTTP response 200]---
<?xml version="1.0" ?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa="http://www.w3.org/2005/08/addressing">
<S:Header>
<wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
<wsa:Action>
http://server.wsaddressing/AddNumbersImpl/addNumbers2Response
</wsa:Action>
<wsa:MessageID>uuid:41975002-46e8-4219-89a6-ed6e72899fa8</wsa:MessageID>
<wsa:RelatesTo>uuid:bf65c920-9129-495a-b9dc-8cb8efb9c2a6</wsa:RelatesTo>
</S:Header>
<S:Body>
<ns2:addNumbers2Response xmlns:ns2="http://server.wsaddressing/">
<return>20</return>
</ns2:addNumbers2Response>
</S:Body>
</S:Envelope>
--------------------
...