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 message addressing properties (MAP) 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 information.

The following describes each element.

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.

@Addressing
@WebService
public class AddNumbersImpl {
    ...
}

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

        ...

    }
}

...

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

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

$ 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 8
<?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 8
<?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>
--------------------

...