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.