JBoss.orgCommunity Documentation

Chapter 15. JBossWS-CXFWS-ReliableMessagingtutorial

15.1. The service
15.2. Generating WSDL and JAX-WS Endpoint Artifacts
15.3. Generating JAX-WS Client Artifacts
15.4. Writing Regular JAX-WS Client
15.5. Turning on WS-RM 1.0
15.5.1. Extending WSDL Using WS-Policy
15.5.2. Basic WS-RM configuration
15.5.3. Advanced WS-RM configuration
15.6. Sample Sources

Apache CXF comes with support for WS-RM 1.0. In this sample we will show how to create client and endpoint communicating each other using WS-RM 1.0. The sample uses WS-Policy specification to configure WS-RM.

Creating the WS-RM based service and client is very simple. User needs to create regular JAX-WS service and client first. The last step is to configure WSRM.

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

package org.jboss.test.ws.jaxws.samples.wsrm.service;
 
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebService;
 
@WebService
(
   name = "SimpleService",
   serviceName = "SimpleService",
   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
)
public class SimpleServiceImpl
{
   @Oneway
   @WebMethod
   public void ping()
   {
      System.out.println("ping()");
   }
 
   @WebMethod
   public String echo(String s)
   {
      System.out.println("echo(" + s + ")");
      return s;
   }
}

Let's say that compiled endpoint class is in directory /home/username/wsrm/cxf/classes. Our next step is to generate JAX-WS artifacts and WSDL.

 

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/wsrm/cxf/classes \
   --output=/home/username/wsrm/cxf/wsprovide/generated/classes \
   --resource=/home/username/wsrm/cxf/wsprovide/generated/wsdl \
   --source=/home/username/wsrm/cxf/wsprovide/generated/src \
   org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl

The above command generates the following artifacts:

# compiled classes
ls /home/username/wsrm/cxf/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
Echo.class  EchoResponse.class  Ping.class

# java sources
ls /home/username/wsrm/cxf/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
Echo.java  EchoResponse.java  Ping.java

# contract artifacts
ls /home/username/wsrm/cxf/wsprovide/generated/wsdl/
SimpleService.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.wsrm.service;
 
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebService;
 
@WebService
(
   name = "SimpleService",
   serviceName = "SimpleService",
   wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl",
   targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
)
public class SimpleServiceImpl
{
   @Oneway
   @WebMethod
   public void ping()
   {
      System.out.println("ping()");
   }
 
   @WebMethod
   public String echo(String s)
   {
      System.out.println("echo(" + s + ")");
      return s;
   }
}

Created endpoint war archive consists of the following entries:

jar -tvf jaxws-samples-wsrm.war 
     0 Wed Apr 16 14:39:22 CEST 2008 META-INF/
   106 Wed Apr 16 14:39:20 CEST 2008 META-INF/MANIFEST.MF
     0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/
   591 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/web.xml
     0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/classes/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
     0 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
     0 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
     0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
  1235 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
   997 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
  1050 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
   679 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
     0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/wsdl/
  2799 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/wsdl/SimpleService.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>SimpleService</servlet-name>
      <servlet-class>org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl</servlet-class>
   </servlet>
   <servlet-mapping>
      <servlet-name>SimpleService</servlet-name>
      <url-pattern>/*</url-pattern>
   </servlet-mapping>
</web-app>

Before we will write regular JAX-WS client we need to generate client artifacts from WSDL. Here's the command to achieve that:

cd $JBOSS_HOME/bin

./wsconsume.sh --keep \
   --package=org.jboss.test.ws.jaxws.samples.wsrm.generated \
   --output=/home/username/wsrm/cxf/wsconsume/generated/classes \
   --source=/home/username/wsrm/cxf/wsconsume/generated/src \
   /home/username/wsrm/cxf/wsprovide/generated/wsdl/SimpleService.wsdl

The above command generates the following artifacts:

# compiled classes
ls /home/username/wsrm/cxf/wsconsume/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/generated/
Echo.class          ObjectFactory.class  Ping.class           SimpleService_Service.class
EchoResponse.class  package-info.class   SimpleService.class  SimpleService_SimpleServicePort_Client.class

# java sources
ls /home/username/wsrm/cxf/wsconsume/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/generated/
Echo.java          ObjectFactory.java  Ping.java           SimpleService_Service.java
EchoResponse.java  package-info.java   SimpleService.java  SimpleService_SimpleServicePort_Client.java

Now the last step is to write the regular JAX-WS client using generated artifacts.

 

The following is the regular JAX-WS client using generated artifacts:

package org.jboss.test.ws.jaxws.samples.wsrm.client;

import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;

public final class SimpleServiceTestCase
{

   private static final String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
   
   public static void main(String[] args) throws Exception
   {
      // create service
      QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
      URL wsdlURL = new URL(serviceURL + "?wsdl");
      Service service = Service.create(wsdlURL, serviceName);
      SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
      
      // invoke methods
      proxy.ping(); // one way call
      proxy.echo("Hello World!"); // request responce call
   }
   
}

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

 

To activate WSRM on server side we need to extend the WSDL with WSRM and addressing policies. Here is how it looks like:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="SimpleService" targetNamespace="http://www.jboss.org/jbossws/ws-extensions/wsrm" xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/wsrm" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsp="http://www.w3.org/2006/07/ws-policy">
<wsdl:types>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.jboss.org/jbossws/ws-extensions/wsrm" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="http://www.jboss.org/jbossws/ws-extensions/wsrm">
<xsd:element name="ping" type="tns:ping"/>
<xsd:complexType name="ping">
<xsd:sequence/>
</xsd:complexType>
<xsd:element name="echo" type="tns:echo"/>
<xsd:complexType name="echo">
<xsd:sequence>
<xsd:element minOccurs="0" name="arg0" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="echoResponse" type="tns:echoResponse"/>
<xsd:complexType name="echoResponse">
<xsd:sequence>
<xsd:element minOccurs="0" name="return" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
  </wsdl:types>
  <wsdl:message name="echoResponse">
    <wsdl:part name="parameters" element="tns:echoResponse">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="echo">
    <wsdl:part name="parameters" element="tns:echo">
    </wsdl:part>
  </wsdl:message>
  <wsdl:message name="ping">
    <wsdl:part name="parameters" element="tns:ping">
    </wsdl:part>
  </wsdl:message>
  <wsdl:portType name="SimpleService">
    <wsdl:operation name="ping">
      <wsdl:input name="ping" message="tns:ping">
    </wsdl:input>
    </wsdl:operation>
    <wsdl:operation name="echo">
      <wsdl:input name="echo" message="tns:echo">
    </wsdl:input>
      <wsdl:output name="echoResponse" message="tns:echoResponse">
    </wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="SimpleServiceSoapBinding" type="tns:SimpleService">

    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
    <!-- Created WS-Policy with WSRM addressing assertions -->
    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - --><wsp:Policy>
      <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2006/05/addressing/wsdl"/>
      <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"/>
    </wsp:Policy>

    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="ping">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input name="ping">
        <soap:body use="literal"/>
      </wsdl:input>
    </wsdl:operation>
    <wsdl:operation name="echo">
      <soap:operation soapAction="" style="document"/>
      <wsdl:input name="echo">
        <soap:body use="literal"/>
      </wsdl:input>
      <wsdl:output name="echoResponse">
        <soap:body use="literal"/>
      </wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="SimpleService">
    <wsdl:port name="SimpleServicePort" binding="tns:SimpleServiceSoapBinding">
      <soap:address location="http://localhost:9090/hello"/>
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

 

 

When users want to have full control over the way WS-RM communication is established, the current CXF Bus needs to be properly configured. This can be done through a CXF Spring configuration.

Next step is to create the client CXF configuration file that will be used by client. The following file was copied/pasted from CXF 2.0.5 ws_rm sample. It simply activates the WSRM protocol for CXF client. We will name this file cxf.xml in our sample. Here's the content of this file:

<beans
  xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:cxf="http://cxf.apache.org/core"
  xmlns:wsa="http://cxf.apache.org/ws/addressing"
  xmlns:http="http://cxf.apache.org/transports/http/configuration"
  xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"
  xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager"
  xsi:schemaLocation="
    http://cxf.apache.org/core
    http://cxf.apache.org/schemas/core.xsd
    http://cxf.apache.org/transports/http/configuration
    http://cxf.apache.org/schemas/configuration/http-conf.xsd
    http://schemas.xmlsoap.org/ws/2005/02/rm/policy
    http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd
    http://cxf.apache.org/ws/rm/manager
    http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans.xsd">
 
  <cxf:bus>
    <cxf:features>
      <cxf:logging/>
      <wsa:addressing/>
      <wsrm-mgr:reliableMessaging>
        <wsrm-policy:RMAssertion>
          <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>           
          <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/>          
        </wsrm-policy:RMAssertion>
        <wsrm-mgr:destinationPolicy>
          <wsrm-mgr:acksPolicy intraMessageThreshold="0" />
        </wsrm-mgr:destinationPolicy>
      </wsrm-mgr:reliableMessaging>
    </cxf:features>
  </cxf:bus>
    
</beans>

And that's almost all. The client configuration needs to picked up by the client classloader; in order to achieve that the cxf.xml file has to be put in the META-INF directory of client jar. That jar should then be provided when setting the class loader.

Alternatively the bus configuration can also be read programmatically as follows:

 

And here's the last piece the updated CXF client:

package org.jboss.test.ws.jaxws.samples.wsrm.client;
 
import java.net.URL;
import java.io.File;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
import org.apache.cxf.Bus;
import org.apache.cxf.BusFactory;
import org.apache.cxf.bus.spring.SpringBusFactory;
import org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
 
public final class SimpleServiceTestCase
{
 
   private static final String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
   
   public static void main(String[] args) throws Exception
   {
      // create bus
      SpringBusFactory busFactory = new SpringBusFactory();
      URL cxfConfig = new File("resources/jaxws/samples/wsrm/cxf.xml").toURL();
      Bus bus = busFactory.createBus(cxfConfig);
      busFactory.setDefaultBus(bus);
 
      // create service
      QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
      URL wsdlURL = new URL(serviceURL + "?wsdl");
      Service service = Service.create(wsdlURL, serviceName);
      SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
      
      // invoke methods
      proxy.ping(); // one way call
      proxy.echo("Hello World!"); // request responce call
 
      // shutdown bus
      bus.shutdown(true);
   }
   
}

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