JBossWS - CXF WS-Addressing tutorial

    Since 3.1.0 (CXF)

    Apache CXF comes with support for WS-Addressing 1.0. In this sample we will show how to create client and endpoint communicating each other using this feature.

    Creating WS-Addressing based service and client is very simple. User needs to create regular JAX-WS service and client first. The last step is to configure the addressing on both sides.

     

     

    The Service

    We will start with the following endpoint implementation (bottom-up approach):

     

    @WebService
    (
       portName = "AddressingServicePort",
       serviceName = "AddressingService",
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
       endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
    )
    public class ServiceImpl implements ServiceIface
    {
       public String sayHello()
       {
          return "Hello World!";
       }
    }
    

    The endpoint implements the following endpoint interface:

    package org.jboss.test.ws.jaxws.samples.wsa;
    
    import javax.jws.WebMethod;
    import javax.jws.WebService;
    
    @WebService
    (
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing"
    )
    public interface ServiceIface
    {
       @WebMethod
       String sayHello();
    }
    

    Let's say that compiled endpoint and interface classes are located in directory /home/username/wsa/cxf/classes. Our next step is to generate JAX-WS artifacts and WSDL that will be part of endpoint archive.

     

    Generating WSDL and JAX-WS Endpoint Artifacts

    We will use wsprovide  commandline tool to generate WSDL and JAX-WS artifacts. Here's the command:

    cd JBOSS_HOME/bin
    
    ./wsprovide.sh --keep --wsdl \
       --classpath=/home/username/wsa/cxf/classes \
       --output=/home/username/wsa/cxf/wsprovide/generated/classes \
       --resource=/home/username/wsa/cxf/wsprovide/generated/wsdl \
       --source=/home/username/wsa/cxf/wsprovide/generated/src \
       org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl
    

    The above command generates the following artifacts:

    # compiled classes
    ls /home/username/wsa/cxf/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws
    SayHello.class  SayHelloResponse.class
    
    # java sources
    ls /home/username/wsa/cxf/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsa/jaxws
    SayHello.java  SayHelloResponse.java
    
    # contract artifacts
    ls /home/username/wsa/cxf/wsprovide/generated/wsdl/
    AddressingService.wsdl

    All aforementioned generated artifacts will be part of endpoint archive. But before we will create the endpoint archive we need to reference generated WSDL from endpoint. To achieve that we will use wsdlLocation annotation attribute. Here's the updated endpoint implementation before packaging it to the war file:

    package org.jboss.test.ws.jaxws.samples.wsa;
    
    import javax.jws.WebService;
    
    @WebService
    (
       portName = "AddressingServicePort",
       serviceName = "AddressingService",
       wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
       endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
    )
    public class ServiceImpl implements ServiceIface
    {
       public String sayHello()
       {
          return "Hello World!";
       }
    }
    

     

    Created endpoint war archive consists of the following entries:

     

    jar -tvf jaxws-samples-wsa.war 
         0 Mon Apr 21 20:39:30 CEST 2008 META-INF/
       106 Mon Apr 21 20:39:28 CEST 2008 META-INF/MANIFEST.MF
         0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/
       593 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/web.xml
         0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/classes/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/
       374 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceIface.class
       954 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceImpl.class
         0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
       703 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHello.class
      1074 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHelloResponse.class
         0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/wsdl/
      2378 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/wsdl/AddressingService.wsdl
    

    The content of web.xml file is:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <web-app
       version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
       <servlet>
          <servlet-name>AddressingService</servlet-name>
          <servlet-class>org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl</servlet-class>
       </servlet>
       <servlet-mapping>
          <servlet-name>AddressingService</servlet-name>
          <url-pattern>/*</url-pattern>
       </servlet-mapping>
    </web-app>
    

    Writing Regular JAX-WS Client

    The following is the regular JAX-WS client using endpoint interface to lookup the webservice:

     

    package org.jboss.test.ws.jaxws.samples.wsa;


    import java.net.URL;
    import javax.xml.namespace.QName;
    import javax.xml.ws.Service;

    public final class SimpleServiceTestCase
    {

       private final String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
      
       public static void main(String[] args) throws Exception
       {
          // create service
          QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService");
          URL wsdlURL = new URL(serviceURL + "?wsdl");
          Service service = Service.create(wsdlURL, serviceName);
          ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
         
          // invoke method
          proxy.sayHello();
       }
      
    }

    Now we have both endpoint and client implementation but without WS-Addressing in place. Our next goal is to turn on the WS-Addressing feature.

    Turning on WS-Addressing 1.0

    In order to turn on WS-Addressing in JBossWS-CXF integration the last two steps are remaining:

    • annotate service endpoint with @Addressing annotation
    • modify client to configure WS-Addressing using JAX-WS webservice feature

     

    Updating Endpoint Code to Configure WS-Addressing

    Now we need to update endpoint implementation to configure WS-Addressing. Here's the updated endpoint code:

    package org.jboss.test.ws.jaxws.samples.wsa;
    
    import javax.jws.WebService;
    import javax.xml.ws.soap.Addressing;
    
    @WebService
    (
       portName = "AddressingServicePort",
       serviceName = "AddressingService",
       wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
       endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
    )
    @Addressing(enabled=true, required=true)
    public class ServiceImpl implements ServiceIface
    {
       public String sayHello()
       {
          return "Hello World!";
       }
    }
    

    As users can see we added JAX-WS 2.1  Addressing annotation to configure WS-Addressing. The next step is to repackage the endpoint archive to apply this change.

     

    Updating Client Code to Configure WS-Addressing

    Now we need to update client implementation as well to configure WS-Addressing. Here's the updated client code:

    package org.jboss.test.ws.jaxws.samples.wsa;
    
    import java.net.URL;
    import javax.xml.namespace.QName;
    import javax.xml.ws.Service;
    import javax.xml.ws.soap.AddressingFeature;
    
    public final class AddressingTestCase
    {
       private final String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
       
       public static void main(String[] args) throws Exception
       {
          // construct proxy
          QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService");
          URL wsdlURL = new URL(serviceURL + "?wsdl");
          Service service = Service.create(wsdlURL, serviceName);
          ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class,  new AddressingFeature());
          // invoke method
          assertEquals("Hello World!", proxy.sayHello());
       }
       
    }
    

    And that's all. Now we have both JAX-WS client and endpoint communicating each other using WS-Addressing feature.

     

     

    Since 3.4.0 (CXF)

    Leveraging WS-Addressing Policy

    An option you can also evaluate to simplify both client and server deployment, is to let the server engine generate and publish the wsdl contract instead of using the one mentioned above: (please note the removal of wsdlLocation attribute in the @WebService annotation)

     

    @WebService
    (
       portName = "AddressingServicePort",
       serviceName = "AddressingService",
       targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
       endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
    )
    @Addressing(enabled=true, required=true)
    public class ServiceImpl implements ServiceIface
    {
         ...
    }

     

    This way the endpoint is published with a contract containing a WS-Addressing Policy that tells clients addressing needs to be on.

     

    <wsp:Policy wsu:Id="AddressingServiceSoapBinding_WSAM_Addressing_Policy">
      <wsam:Addressing>
        <wsp:Policy/>
      </wsam:Addressing>
    </wsp:Policy>

     

    The client can then simply do as follows:

     

    Service service = Service.create(wsdlURL, serviceName);
    ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
    // invoke method

     

    No need for setting the AddressingFeature, the policy engine takes care of enabling WS-Addressing to match the policy advertised by the server.

     

    Sample Sources

    All sources from this tutorial are part of JBossWS-CXF testsuite.