<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements. See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership. The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License. You may obtain a copy of the License at
  ~
  ~ http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied. See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<meta http-equiv="content-type" content="" />
<title>JiBX Integration with Axis2</title>
</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" id="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" id="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" id="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" id="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" id="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 generally 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 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 <i>-Ebindingfile
{file}</i> parameter is not needed.</p>
<p>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.</p>
<a name="coming" id="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 JiBX.</p>
<h2>References</h2>
<p><a href=
"http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX:
Bindings Tutorial</a></p>
</body>
</html>