Franz van Betteraey: Using Apache CXF SOAP service with customized JiBX databinding

This post gives a brief overview on how to build an Apache CXF SOAP service with JiBX databinding.

Apache CXF is an open source services framework that helps building JAX-WS and JAX-RS web services. JiBX is a XML binding tool for Java. To understand the post it is necessary to be familiar with Apache CXF and JiBX.

Apache CXF uses JAXB as its default XML databinding. Thus this combination works out off the box and is well documented. Although JiBX is also supported it seems to be a bit neglected. The support is not even mentioned in the CXF databinding documentation (to get it there an improvement request was opened CXF-4801).

To demonstrate the usage of Apache CXF with JiBX I built a sample application (simple calculator service). It is accessible on github (cxf-soap-with-jibx) and shows how to build a wsdl first webservice using maven, the cxf-codegen-plugin and the jibx-maven-plugin.

The sample application offers a simple SOAP calculator service with the following definitions

calculator.wsdl    service definition
                    targetNamespace="http://calculator.sample.frvabe.de/ws"
calculator.xsd business objects
                    targetNamespace="http://calculator.sample.frvabe.de/types"

I will not paste the file content here as it will make the post unnecessarily long. Instead I will explain the most recent parts of the maven pom.xml that are necessary to build the project.

First of all we use the cxf-codegen-plugin to generate the SOAP service classes. I used it that way:

<!-- generate service code from wsdl (skip code generation from schema) -->
<!-- 
  This process will generate no 'de.frvabe.sample.calculator.types'
  source classes but the full JiBX binding definition file here:
  ${project.build.directory}/generated-sources/jibx_bindings/calculator.xml
  This file will be ignored by the further build process!
-->
<plugin>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-codegen-plugin</artifactId>
<version>${cxf.version}</version>
<executions>
  <execution>
 <phase>generate-sources</phase>
 <configuration>
   <sourceRoot>${project.build.directory}/generated-sources</sourceRoot>
   <wsdlOptions>
  <wsdlOption>
    <wsdl>${project.basedir}/src/main/resources/wsdl/calculator.wsdl</wsdl>
    <dataBinding>jibx</dataBinding>
    <extraargs>
   <extraarg>-nexclude</extraarg>
   <extraarg>http://calculator.sample.frvabe.de/types</extraarg>
    </extraargs>
  </wsdlOption>
   </wsdlOptions>
 </configuration>
 <goals>
   <goal>wsdl2java</goal>
 </goals>
  </execution>
</executions>
</plugin>

This will only generate the source code for the service classes. The usage of JiBX is specified in the <dataBinding> element. The cxf-codegen-plugin normally would also generate the classes for the business objects (specified in the calculator.xsd) but it does not allow to pass any specific options to the JiBX code generation process. But that should be done because the business object classes should implement the java.io.Serializable interface. Therefore we need to extend the code generation by using a class-decorator. The customization file custom-jibx-codegen.xml which defines the usage of the class-decorator for all classes of the http://calculator.sample.frvabe.de/types namespace looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<schema-set xmlns:xs="http://calculator.sample.frvabe.de/types">
    <class-decorator class="org.jibx.schema.codegen.extend.SerializableDecorator"
                     serial-version="1" />
</schema-set>

Now the jibx-maven-plugin is used to generate the business object classes:

<!-- generate classes from schema and run the binding compiler -->
<plugin>
  <groupId>org.jibx</groupId>
  <artifactId>jibx-maven-plugin</artifactId>
  <version>${jibx.version}</version>
  <executions>
    <!-- generate code from schema using JiBX with customization -->
    <!-- 
        This process will generate the 'de.frvabe.sample.calculator.types'
        source classes and the JiBX binding definition file at
        the default location: ${project.build.directory}/generated-sources/binding.xml
    -->
    <execution>
      <id>generate-java-code-from-schema</id>
      <phase>generate-sources</phase>
      <goals>
        <goal>schema-codegen</goal>
      </goals>
      <configuration>
        <schemaLocation>${project.basedir}/src/main/resources/wsdl</schemaLocation>
        <customizations>
          <customization>${project.basedir}/src/main/config/custom-jibx-codegen.xml</customization>
        </customizations>
      </configuration>
    </execution>
    <!-- run the JiBX binding compiler -->
    <!-- The binding.xml file at the default location will be used here. -->
    <execution>
      <id>compile-binding</id>
      <goals>
        <goal>bind</goal>
      </goals>
      <configuration>
        <schemaBindingDirectory>${project.build.directory}/generated-sources</schemaBindingDirectory>
        <includeSchemaBindings>
          <includeSchemaBinding>binding.xml</includeSchemaBinding>
        </includeSchemaBindings>
      </configuration>
    </execution>
  </executions>
</plugin>

The schema-codegen goal of this plugin definition will generate the code with the defined customization. The compile-binding goal will compile the generated binding definition into the Java classes (what makes the JiBX XML mapping so fast).

And that's all what has to be done.

In the example Spring is used to start the service with an embedded jetty. The application context xml file is short. Notice that JiBX is also declared as databinding here:

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans" 
       xmlns:jaxws="http://cxf.apache.org/jaxws"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://cxf.apache.org/jaxws 
        http://cxf.apache.org/schemas/jaxws.xsd">

  <import resource="classpath:META-INF/cxf/cxf.xml" />

  <bean id="calculator" class="de.frvabe.sample.calculator.ws.CalculatorImpl" />

  <jaxws:endpoint xmlns:tns="http://calculator.sample.frvabe.de/ws"
                    id="calculatorEndpoint" implementor="#calculator"
                    wsdlLocation="classpath:wsdl/calculator.wsdl" endpointName="tns:calculatorPort"
                    serviceName="tns:calculatorService"
                    address="http://0.0.0.0:8080/calculator">
    <jaxws:dataBinding>
      <bean class="org.apache.cxf.jibx.JibxDataBinding" />
    </jaxws:dataBinding>
  </jaxws:endpoint>

</beans>

After starting the service you can use e.g. SoapUI to test it with some simple requests, like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://calculator.sample.frvabe.de/types">
 <soapenv:Header/>
 <soapenv:Body>
  <typ:term>
   <part>
    <value>1</value>
   </part>
   <part>
    <operator>ADD</operator>
    <value>2</value>
   </part>
   <part>
    <operator>MULTIPLY</operator>
    <value>3</value>
   </part>
   <part>
    <operator>DIVIDE</operator>
    <value>4</value>
   </part>
   <part>
    <operator>SUBTRACT</operator>
    <value>5</value>
   </part>
  </typ:term>
 </soapenv:Body>
</soapenv:Envelope>

The result is something like this (please apologize that it ignores most mathematical rules):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Body>
  <types:result xmlns:types="http://calculator.sample.frvabe.de/types">
   <value>-2.75</value>
  </types:result>
 </soap:Body>
</soap:Envelope>

Conclusion:

Apache CXF and JiBX work well together. But if code generation customization is required there is a lack of support on the Apache CXF tool side for JiBX. Thus some extra work(-around) has to be done.

I opened an improvement request for a better JiBX support CXF-4980. Feel free to vote on this issue!

Sunday, April 28, 2013

Using Apache CXF SOAP service with customized JiBX databinding