
<html>

<head>
  <meta http-equiv="content-type" content="">
  <title>JiBX Integration with Axis2</title>
  <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
</head>

<body>

<h1>JiBX Integration With Axis2</h1>

<p>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.</p>

<h2>Content</h2>
<ul>
  <li><a href="#intro">Introduction</a></li>
  <li><a href="#wrapped">Wrapped vs. unwrapped</a></li>
  <li><a href="#java">Starting from Java</a></li>
  <li><a href="#wsdl">Starting from WSDL</a></li>
  <li><a href="#codegen">Axis2 JiBX Code Generation</a></li>
  <li><a href="#coming">Coming Attractions</a></li>
</ul>

<a name="intro"></a>
<h2>Introduction</h2>

<p><a href="http://www.jibx.org">JiBX data binding</a> 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).</p>

<p>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.</p>

<p>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 <a
href="http://www.jibx.org">JiBX Web site</a>.</p>

<a name="wrapped"></a>
<h2>Wrapped vs. unwrapped</h2>

<p>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
<a href="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">WS-I Basic Profile</a>).
</p>

<p>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.
</p>

<p>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 <a href="./jibx-unwrapped-example.html">JiBX Unwrapped
Example</a> and the <a href="./jibx-doclit-example.html">JiBX Document/Literal
Example</a> pages for a detailed comparison of the two forms of service
interface.
</p>

<a name="java"></a>
<h2>Starting from Java</h2>

<p>Here's the sequence of steps for using JiBX with Axis2 to expose existing
Java code as a Web service:</p>
<ol>
  <li>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).</li>
  <li>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.</li>
  <li>Create a WSDL document for your service, with the schema embedded or
    imported.</li>
  <li>Generate Axis2 server-side linkage code using WSDL2Java with the WSDL
    and your binding definition.</li>
  <li>Run the JiBX binding compiler on your Java classes to add the actual
    binding code.</li>
  <li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
    the <i>jibx-runtime.jar</i>.</li>
</ol>

<p>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
<a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> page for more
details on how this works.
</p>

<p>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
<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> page for
more details on this case.
</p>

<a name="wsdl"></a>
<h2>Starting from WSDL</h2>

<p>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):</p>
<ol>
  <li>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).</li>
  <li>Generate Axis2 client linkage code using WSDL2Java with the WSDL and
    your binding definition.</li>
  <li>Run the JiBX binding compiler on your Java classes to add the actual
    binding code.</li>
  <li>Include the <i>axis2-jibx.jar</i> in your runtime classpath, along with
    the <i>jibx-runtime.jar</i></li>
</ol>

<p>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 <a href="./jibx-unwrapped-example.html">JiBX Unwrapped Example</a> and
<a href="./jibx-doclit-example.html">JiBX Document/Literal Example</a> pages for
more details.</p>

<a name="codegen"></a>
<h2>WSDL2Java usage</h2>

<p>To run the WSDL2Java tool for JiBX data binding you need:</p>
<ol>
  <li>To specify <i>-d jibx</i> to select JiBX binding.</li>
  <li>You also need an additional parameter, <i>-Ebindingfile {file}</i>
    (where <i>{file}</i> is the file path to your JiBX binding definition).</li>
  <li>Finally, you need to have the <i>axis2-jibx-XXXX.jar</i>, the
    <i>jibx-bind-XXXX.jar</i>, and the <i>jibx-run-XXXX.jar</i> files
    from your Axis2 distribution included in the WSDL2Java classpath.</li>
</ol>

<p>If you want to use the unwrapped form of interface you also need to specify
the <i>-uw</i> 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 <i>type-name</i>
attribute that matches the schema <i>complexType</i> used in the WSDL. You can
also use formats in the binding definition to define the handling of schema
<i>simpleType</i>s. Schema types corresponding to Java primitives and simple
objects with build-in JiBX conversions are handled automatically.</p>

<p>If you're not unwrapping the interface, your JiBX binding definition must
include a concrete mapping for each element used as input or output by any
operation.</p>

<a name="coming"></a>
<h2>Coming Attractions</h2>

<p>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 <a
href="http://www.jibx.org">JiBX project site</a> for updates on both JiBX
and the Axis2 JiBX support.</p>

<h2>References</h2>

<p><a href="http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX:
Bindings Tutorial</a>
</p>

</body>

</html>