| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2017-11-22 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20171122" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – JiBX Integration with Axis2</title> |
| <link rel="stylesheet" href="../../css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="../../css/site.css" /> |
| <link rel="stylesheet" href="../../css/print.css" media="print" /> |
| <script type="text/javascript" src="../../js/apache-maven-fluido-1.6.min.js"></script> |
| <meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" /> </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div> |
| <div class="pull-right"><a href="../.././" id="bannerRight"><img src="../../images/axis.jpg" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2017-11-22<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.7<span class="divider">|</span></li> |
| <li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li> |
| <li class="active ">JiBX Integration with Axis2</li> |
| </ul> |
| </div> |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Axis2/Java</li> |
| <li><a href="../../index.html" title="Home"><span class="none"></span>Home</a> </li> |
| <li><a href="../../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li> |
| <li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a> |
| <ul class="nav nav-list"> |
| <li><a href="../../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li> |
| <li><a href="../../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li> |
| <li><a href="../../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li> |
| <li><a href="../../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li> |
| <li><a href="../../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li> |
| <li><a href="../../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li> |
| <li><a href="../../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li> |
| <li><a href="../../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li> |
| <li><a href="../../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li> |
| <li><a href="../../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li> |
| <li><a href="../../release-notes/1.7.6.html" title="1.7.6"><span class="none"></span>1.7.6</a> </li> |
| <li><a href="../../release-notes/1.7.7.html" title="1.7.7"><span class="none"></span>1.7.7</a> </li> |
| </ul> |
| </li> |
| <li><a href="../../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li> |
| <li><a href="../../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li> |
| <li><a href="../../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> |
| <li><a href="../../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li> |
| <li><a href="../../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li> |
| <li><a href="../../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li> |
| <li><a href="../../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li> |
| <li><a href="../../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li> |
| <li><a href="../../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li> |
| <li><a href="../../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li> |
| <li class="nav-header">Resources</li> |
| <li><a href="../../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> |
| <li><a href="../../articles.html" title="Articles"><span class="none"></span>Articles</a> </li> |
| <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li> |
| <li><a href="../../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li> |
| <li><a href="../../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li> |
| <li class="nav-header">Get Involved</li> |
| <li><a href="../../overview.html" title="Overview"><span class="none"></span>Overview</a> </li> |
| <li><a href="../../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li> |
| <li><a href="../../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> |
| <li><a href="../../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> |
| <li><a href="../../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li> |
| <li><a href="../../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li> |
| <li class="nav-header">Project Information</li> |
| <li><a href="../../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> |
| <li><a href="../../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> |
| <li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li> |
| <li><a href="../../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li> |
| <li class="nav-header">Apache</li> |
| <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> |
| <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li> |
| </ul> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </div> |
| <div id="bodyColumn" class="span10" > |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="Content"></a>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> |
| |
| <div class="section"> |
| <h2><a name="Introduction"></a>Introduction</h2> |
| |
| <p><a class="externalLink" 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 class="externalLink" href="http://www.jibx.org">JiBX Web site</a>.</p> |
| <a name="wrapped" id="wrapped"></a> |
| |
| <div class="section"> |
| <h2><a name="Wrapped_vs._unwrapped"></a>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 class="externalLink" 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> |
| |
| <div class="section"> |
| <h2><a name="Starting_from_Java"></a>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 style="list-style-type: decimal"> |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="Starting_from_WSDL"></a>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 style="list-style-type: decimal"> |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="WSDL2Java_usage"></a>WSDL2Java usage</h2> |
| |
| <p>To run the WSDL2Java tool for JiBX data binding you need:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <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> |
| |
| <div class="section"> |
| <h2><a name="Coming_Attractions"></a>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 class="externalLink" href="http://www.jibx.org">JiBX project site</a> for updates on JiBX.</p> |
| |
| <div class="section"> |
| <h2><a name="References"></a>References</h2> |
| |
| <p><a class="externalLink" href="http://jibx.sourceforge.net/tutorial/binding-tutorial.html">JiBX: |
| Bindings Tutorial</a></p> |
| |
| </html> |
| </div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>Copyright ©2004–2017 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |