JiBX Integration With Axis2

This document describes using JiBX data binding with Axis2. JiBX differs from the other data binding techniques supported by Axis2 in that it allows you to use your own Java data objects (as opposed to Java data objects generated from a schema definition). JiBX also provides a nicer form of unwrapped Web services interface than is supported by the other data binding techniques. On the downside, JiBX requires more setup than the other data binding techniques - in particular, you need to come up with a set of data classes and a binding definition in order to work with JiBX in Axis2.

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 binding definition documents you provide. This approach let's you customize the way your Java objects are converted to and from XML. You can even define multiple bindings to use the same Java objects with different XML representations. These features make JiBX especially useful if you're developing a Web service based on existing Java code, or when you need to support multiple XML representations for a Web service (as when you're using versioned schema definitions).

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 does not 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.

Wrapped vs. unwrapped

Axis2 support for JiBX currently only works with the document-literal (doc/lit) form of Web services definitions. Doc/lit Web services generally use particular schema elements as input and output from each operation, and the Axis2 support for JiBX assumes this structure (which is also the structure required for compatibility with the WS-I Basic Profile).

A popular subset of doc/lit Web services use a form called "wrapped". Wrapped doc/lit Web services define service operations that correspond to method calls, using input and output element names based on the method name and embedding the actual parameter values for the method call within the input element.

When used with Axis2, JiBX supports both general doc/lit and wrapped service definitions. Wrapped service definitions can be "unwrapped" during code generation to provide a greatly simplified interface. JiBX unwrapping of service definitions is not compatible with the unwrapping support for other data binding frameworks used with Axis2, but most users will find the JiBX approach easy and convenient. See the JiBX Unwrapped Example and the JiBX Document/Literal Example pages for a detailed comparison of the two forms of service interface.

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 (you may be able to use the JiBX binding generator to help with this step).
  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). If you're using a wrapped form of interface to your service you'll also need to create schema definitions for the wrapper input and output elements used by each operation.
  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.

If you use a wrapped interface for your Web service you can expose method calls in your existing code directly as operations in the service. In this case you normally just use your existing data objects with JiBX data binding, and add schema definitions for the wrapper elements. See the JiBX Unwrapped Example page for more details on how this works.

If you use a non-wrapped interface for your Web service you need to define classes to hold the data input and output from each operation. In this case these holder classes need to be included in the JiBX binding definition. See the JiBX Document/Literal Example page for more details on this case.

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 actual service, when you've been supplied with the WSDL your service is to implement):

  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

As with the starting from Java case, there are some differences in the handling depending on whether your service definition fits the wrapped form. See the JiBX Unwrapped Example and JiBX Document/Literal Example pages for more details.

WSDL2Java usage

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

  1. To specify -d jibx to select JiBX binding.
  2. You also generally 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-XXXX.jar, the jibx-bind-XXXX.jar, and the jibx-run-XXXX.jar files from your Axis2 distribution included in the WSDL2Java classpath.

If you want to use the unwrapped form of interface you also need to specify the -uw option to WSDL2Java. In this case your JiBX binding definition must include abstact mappings for all the complex objects which correspond to method parameters, and each abstract mapping must specify a type-name attribute that matches the schema complexType used in the WSDL. You can also use formats in the binding definition to define the handling of schema simpleTypes. Schema types corresponding to Java primitives and simple objects with built-in JiBX conversions are handled automatically, and if all the parameter and return values in your wrapped WSDL are of these types you don't even need a JiBX binding definition. This is the one case where the -Ebindingfile {file} parameter is not needed.

If you're not unwrapping the interface, you must use a JiBX binding definition and it must include a concrete mapping for each element used as input or output by any operation.

Coming Attractions

Work is in-progress on better tools to support generating Java classes and corresponding JiBX binding definitions from an input schema, and also for generating binding+schema generation from existing code. These features will be integrated into the Axis2 JiBX support when they are available. Check the JiBX project site for updates on JiBX.

References

JiBX: Bindings Tutorial