JiBX Integration With Axis2

This document will explain the usage of JiBX with Axis2 in order to expose existing Java code as a Web service and to implement a client for an existing Web service (or the service stubs for implementing the service).

Content

Introduction

JiBX data binding supports fast and flexible conversions between plain old Java objects (POJOs) and XML. JiBX uses a mapped binding approach that's based on a binding definition document you provide. This lets you customize the way your Java objects are converted to and from XML. These features make JiBX especially useful if you're developing a Web service based on existing Java code.

Axis2 supports using JiBX with your Web services, including generating the necessary linkage code for both client and server sides. However, the Axis2 support for JiBX doesn't currently include code generation from the schema for a Web service - you need to provide your own data classes and JiBX binding definition, and you also need to make sure that the binding definition matches the XML structures defined for your Web service. The JiBX project provides some basic tools to help with code generation from schema, binding generation from Java classes, and schema generation from the combination of Java classes and a binding definition. In the future, improved versions of these tools will be integrated directly into the Axis2 framework support, but for now you're on your own with this part of the setup.

You can use JiBX data binding both to expose existing Java code as a service, and to build a client for an existing service. This document runs through the sequence of steps involved for each of these cases, just to help users understand the basic approach to working with JiBX in Axis2. You can find full instructions on the standard JiBX parts of this sequence on the JiBX Web site.

Starting from Java

Here's the sequence of steps for using JiBX with Axis2 to expose existing Java code as a Web service:

  1. Create a JiBX binding definition for the data being transferred by the Web service
  2. Create a schema that matches the XML defined by your binding (you may be able to use the JiBX schema generator to help with this)
  3. Create a WSDL document for your service, with the schema embedded or imported.
  4. Generate Axis2 server-side linkage code using WSDL2Java with the WSDL and your binding definition
  5. Run the JiBX binding compiler on your Java classes to add the actual binding code
  6. Include the axis2-jibx.jar in your runtime classpath, along with the jibx-runtime.jar (normally done by including these in the axis2/WEB-INF/lib directory)

The above is assuming:

  1. Your code already provides methods to implement the operations you want to expose as a Web service
  2. These methods each take a single parameter object that's unique to the method
  3. Each return a single response object.

If this is not the case, you'll also need to create wrapper classes and perhaps wrapper methods for now. See the JiBX example for more details on this.

Starting from WSDL

Here's the sequence of steps for using JiBX with Axis2 to implement a client for an existing Web service (or the service stubs for implementing the service):

  1. Create Java classes for the data being transferred by the Web service, and a JiBX binding definition that maps these classes to the schema defined by the Web service (you may be able to use the JiBX xsd2jibx tool to help with this)
  2. Generate Axis2 client linkage code using WSDL2Java with the WSDL and your binding definition
  3. Run the JiBX binding compiler on your Java classes to add the actual binding code
  4. Include the axis2-jibx.jar in your runtime classpath, along with the jibx-runtime.jar

Axis2 JiBX Code Generation

To run the WSDL2Java tool for JiBX data binding you need:

  1. To specify -d jibx to select JiBX binding.
  2. You also need an additional parameter, -Ebindingfile {file} (where {file} is the file path to your JiBX binding definition).
  3. Finally, you need to have the axis2-jibx.jar, the jibx-bind-1.1beta2.jar, and the jibx-run-1.1beta2.jar files from your Axis2 distribution included in the WSDL2Java classpath.

Coming Attractions

Soon after the release of Axis2 1.0 the JiBX support will be extended to support automatic handling of "wrapped" doc/lit services. This will dramatically reduce the number of classes that need to be defined for working with simple services, and simplify both starting from Java and starting from WSDL.

The full JiBX 1.1 release will also provide much improved support for code generation from schemas, and for binding+schema generation from code, and these features will be integrated into the Axis2 JiBX support. Check the JiBX project site for updates on both JiBX 1.1 and the Axis2 JiBX support.

References

JiBX: Bindings Tutorial