| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2017-05-06 |
| | 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="20170506" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – ADB - Howto</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="text/html; charset=us-ascii" /> </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-05-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.5<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 ">ADB - Howto</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> |
| </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>Axis2 Databinding Framework</h1> |
| |
| <p>This document aims to provide an architectural overview of the |
| Axis2 Databinding Framework (referred to as ADB from here onwards) |
| and be a guide to anyone who wants to use and modify ADB. The |
| information is presented under the following topics.</p> |
| |
| <div class="section"> |
| <h2><a name="Content"></a>Content</h2> |
| |
| <ul> |
| |
| <li><a href="#intro">Introduction</a></li> |
| |
| <li><a href="#archi">Architectural Overview</a></li> |
| |
| <li><a href="#code_depend">Code and Dependencies</a></li> |
| |
| <li><a href="#code_gen">Invoking the ADB Code Generator</a> |
| |
| <ul> |
| |
| <li><a href="#schema_compiler">As a Stand-alone Schema |
| Compiler</a></li> |
| |
| <li><a href="#api">Through the API</a></li> |
| </ul> |
| </li> |
| |
| <li><a href="#gen_modes">Generation Modes</a></li> |
| |
| <li><a href="#deep">Deep into Generated Code</a> |
| |
| <ul> |
| |
| <li><a href="#example">An Example!</a></li> |
| </ul> |
| </li> |
| |
| <li><a href="#limitation">Known Limitations</a></li> |
| |
| <li><a href="#more">Want to Learn More?</a></li> |
| </ul> |
| <a name="intro" id="intro"></a> |
| |
| <div class="section"> |
| <h2><a name="Introduction"></a>Introduction</h2> |
| |
| <p>The objective of the Axis2 Databinding framework is to provide a |
| lightweight and simple schema compiler/Java bean generator for |
| Axis2. By no means is it intended to be a fully functional schema |
| compiler like XMLBeans. Note that ADB is written in a fashion that |
| allows it to be used as a stand-alone schema compiler and also to |
| be extended to generate code for other languages.</p> |
| <a name="archi" id="archi"></a> |
| |
| <div class="section"> |
| <h2><a name="Architectural_Overview"></a>Architectural Overview</h2> |
| |
| <p>ADB is built on a modular architecture that allows it to utilize |
| a pre-configured writer depending on the configuration. The 'big |
| block diagram' for the code generator architecture is depicted |
| below.</p> |
| |
| <p><img src="images/ADB.jpg" alt="ADB architecture" /></p> |
| |
| <p>ADB utilizes the WS-Commons <a class="externalLink" href="http://ws.apache.org/commons/XmlSchema/index.html">XmlSchema |
| library</a> for reading the Schema. The object model for the schema |
| comes in the form of an XmlSchema object. The schema compiler keeps |
| an instance of the writer (in the default case it's the |
| JavaBeanWriter) which actually writes the classes. The writers may |
| use whatever technique they prefer, in the case of the |
| JavaBeanWriter, it uses an XSLT template. The SchemaCompiler also |
| uses a typemapper object that tells it what classnames to use for |
| the QNames that it encounters. This type mapper is also part of the |
| configuration and the users can override the default type mapper by |
| overriding the property setting.</p> |
| <a name="code_depend" id="code_depend"></a> |
| |
| <div class="section"> |
| <h2><a name="Code_and_Dependencies"></a>Code and Dependencies</h2> |
| |
| <p>As explained in the previous section, the schema compiler |
| depends on the WS-Commons XmlSchema library. The XSLT |
| transformations are dependent on the JVM's DOM implementation |
| (either Crimson or Xerces) which means that the underlying JVM |
| should be 1.4 or higher. Apart from that ADB has no dependencies on |
| any other special jar files. The code for the schema compiler is |
| completely in the <b>org.apache.axis2.schema.*</b> |
| package. This package resides in the codegen module of the Axis2 |
| source tree.</p> |
| |
| <p>The following are the important classes and files of ADB:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li><b>SchemaCompiler</b> - The work horse that really |
| compiles the schema into classes.</li> |
| |
| <li><b>BeanWriter</b> - BeanWriters handle the the actual |
| rendering of the classes. BeanWriter is the interface that writers |
| need to implement in order to be used by the SchemaCompiler.</li> |
| |
| <li><b>JavaBeanWriter</b> - The default implementation of |
| the BeanWriter interface.</li> |
| |
| <li><b>TypeMap</b> - represents the interface that the |
| schema compiler uses to find class names for a given QName.</li> |
| |
| <li><b>JavaTypeMap</b> - the default implementation of |
| the TypeMap</li> |
| |
| <li><b>ADBBeanTemplate.xsl</b> - the XSLtemplate the |
| JavaBeanWriter uses.</li> |
| |
| <li><b>Schema-compile.properties</b> - The property file |
| for the schema compiler</li> |
| </ol> |
| |
| <p>The easiest way to obtain the ADB binaries is to run the maven |
| build for the Axis2 adb-codegen module. This will generate the |
| <b>axis2-adb-codegen-{$version}.jar</b> inside the target |
| folder which is directly usable when the ADB schema compiler is |
| required.</p> |
| |
| <p>The runtime dependencies for the ADB generated classes is in the |
| Axis2 adb module and the kernal module. Hence to compile and work |
| with the generated classes the |
| <b>axis2-adb-{$version}.jar</b> and |
| <b>axis2-kernal-{$version}.jar</b> needs to be in the |
| classpath in addition to other dependencies such as StAX, Axiom, |
| Commons-logging and javax.activation.</p> |
| <a name="code_gen" id="code_gen"></a> |
| |
| <div class="section"> |
| <h2><a name="Invoking_the_ADB_Code_Generator"></a>Invoking the ADB Code Generator</h2> |
| <a name="schema_compiler" id="schema_compiler"></a> |
| |
| <div class="section"> |
| <h3><a name="As_a_Standalone_Schema_Compiler"></a>As a Standalone Schema Compiler</h3> |
| |
| <p>ADB comes with a XSD2Java code generator that allows the schemas |
| to be compiled just by giving the schema file reference. This main |
| class is presently rather primitive and does not provide much |
| control over the code generation process. This is bound to improve |
| in the near future.</p> |
| |
| <p>XSD2Java accepts the following parameters:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>The Schema file name - This should be a complete file name |
| pointing to the local file system</li> |
| |
| <li>The output folder name - This should be the name of a folder |
| within the local file system</li> |
| </ol> |
| |
| <p>Since the code generator presently has no validations built into |
| it, the compiler is likely to show various error messages if these |
| parameters are not supplied properly.</p> |
| <a name="api" id="api"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Through_the_API"></a>Through the API</h3> |
| |
| <p>This is the only way to harness the full potential of the schema |
| compiler. The current Axis2 integration of ADB happens through this |
| API. The most important classes and methods of the Schema compiler |
| are as follows.</p> |
| |
| <ul> |
| |
| <li><b>SchemaCompiler - Constructor</b> |
| |
| <p>The constructor of the schema compiler expects a CompilerOptions |
| object. This compilerOptions object is more of a holder for the |
| parameters that are passed to the SchemaCompiler. The only |
| mandatory parameter in the CompilerOptions is the output |
| directory.</p> |
| </li> |
| |
| <li><b>SchemaCompiler - Compile(XMLSchema schema)</b> |
| |
| <p>The compile method to call for a single schema. The expected |
| object is a XMLSchema which is part of the XmlSchema library.</p> |
| </li> |
| |
| <li><b>SchemaCompiler - Compile(List schemaList)</b> |
| |
| <p>Similar to the previous method but accepts a list of schemas |
| instead of one.</p> |
| </li> |
| </ul> |
| |
| <p>For a comprehensive code sample in invoking the schema compiler |
| through the API, the following classes would be helpful. One would |
| also need an understanding of the generation modes of the ADB |
| schema compiler when using it through the API. Hence the following |
| section includes a brief description of the generation modes.</p> |
| |
| <ul> |
| |
| <li><b>org.apache.axis2.schema.XSD2Java</b></li> |
| |
| <li><b>org.apache.axis2.schema.ExtensionUtility</b></li> |
| </ul> |
| <a name="gen_modes" id="gen_modes"></a> |
| </div> |
| <div class="section"> |
| <h2><a name="Generation_Modes"></a>Generation Modes</h2> |
| |
| <p>ADB extension provides several generation modes for the data |
| bound classes.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li><b>Integrated Mode</b> |
| |
| <p>In this mode the classes are generated as inner classes of the |
| stub, message receiver or the interface. The ADB framework does not |
| actually write the classes but instead provides a map of DOM |
| document objects that contains the model for the databinding |
| classes. The Axis2 codegen engine in turn parses these documents |
| within its own XSLT parser to create the necessary classes. |
| Implementers are free to use these models differently for their own |
| particular needs.</p> |
| |
| <p>Integrated mode is intended to be used by tool builders.</p> |
| </li> |
| |
| <li><b>Wrapped Mode</b> |
| |
| <p>In the wrapped mode, the ADB databinder generates one class that |
| contains all the databound classes. This is convenient when the |
| number of classes need to be limited.</p> |
| </li> |
| |
| <li><b>Expanded Mode</b> |
| |
| <p>This is the usual mode where the code generator generates a |
| class for each of the outer elements and the named complex types. |
| The command line tool (XSD2Java) always generates code in the |
| expanded mode.</p> |
| </li> |
| </ol> |
| |
| <p>The rules for generating code (described in the next section) |
| applies regardless of the mode. Switching these modes can be done |
| by passing the correct options via the CompilerOptions object. The |
| following table lists the options and the effects of using |
| them.</p> |
| |
| <table border="0" class="table table-striped" summary="Options and descriptions"> |
| <tbody> |
| |
| <tr class="a"> |
| |
| <td><b>Field Name in Options</b></td> |
| |
| <td><b>Description</b></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>writeOutput</td> |
| |
| <td>This determines whether to write the output or not. If the flag |
| is on then the classes will be written by ADB. The default is |
| off.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>wrapClasses</td> |
| |
| <td>This determines whether to wrap the generated classes. If the |
| flag is on then a single class (with adb added to the end of the |
| specified package) will be generated. The default is off.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>mapperClassPackage</td> |
| |
| <td>The package name for the mapper class. Please see the advanced |
| section for details of the mapper class.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>helperMode</td> |
| |
| <td>The switch that determines whether to switch to helper mode or |
| not. Please see the advanced section for details of helper |
| mode.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ns2PackageMap</td> |
| |
| <td>A map that stores the namespace name against the package name |
| These details are used to override the default packages</td> |
| </tr> |
| </tbody> |
| </table> |
| <a name="deep" id="deep"></a> |
| |
| <div class="section"> |
| <h2><a name="Deep_into_Generated_Code"></a>Deep into Generated Code</h2> |
| |
| <p>When the schema compiler is invoked (one-way or another) it |
| generates code depending on the following rules:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>All named complex types become bean classes. Any attribute or |
| element encapsulated in this complex type will become a field in |
| the generated class. Note that the support for constructs other |
| than xsd:sequence and xsd:all is not yet implemented.</li> |
| |
| <li>All top level elements become classes. This is a rather obvious |
| feature since unless classes are generated for the top level |
| elements the handling of elements becomes difficult and messy!</li> |
| |
| <li>SimpleType restrictions are handled by replacing the relevant |
| type with the basetype</li> |
| </ol> |
| |
| <p>Once the code is generated according to the rules it looks like |
| the following. Consider the following schema:</p> |
| |
| <div> |
| <pre> |
| <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema" |
| xmlns:tns="http://soapinterop.org/types" targetNamespace="http://soapinterop.org/types" |
| elementFormDefault="qualified" > |
| <import namespace="http://schemas.xmlsoap.org/soap/encoding/"/> |
| <complexType name="SOAPStruct"> |
| <sequence> |
| <element name="varString" type="xsd:string"/> |
| <element name="varInt" type="xsd:int"/> |
| <element name="varFloat" type="xsd:float"/> |
| </sequence> |
| </complexType> |
| <element name="myElement" type="tns:SOAPStruct"/> |
| </schema> |
| </pre></div> |
| |
| <p>For comprehension let us consider the expanded mode for the code |
| generator. Unless specifically mentioned, the rest of this document |
| assumes that the expanded mode of the code generation is used. This |
| particular schema will generate the following two classes in the |
| designated package, which in this case would be |
| <b>org.soapinterop.types</b>. The package name is derived |
| from the target namespace of the schema.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>MyElement.java</li> |
| |
| <li>SOAPStruct.java</li> |
| </ol> |
| |
| <p>As explained earlier, SOAPStruct refers to the complexType. |
| MyElement is the class that refers to the element. Just as |
| expected, the SOAPStruct bean has getters and setters for |
| varString, varInt and varFloat which are String, int and float |
| respectively. MyElement on the other hand has a single field |
| representing the SOAPStruct object that it encapsulates.</p> |
| |
| <p>The most important aspect of the generated code is that it |
| encapsulates two methods for creating and serializing the beans. |
| Note that to make this work, the generated beans implement the |
| <b>org.apache.axis2.databinding.ADBBean</b> interface</p> |
| |
| <p>The creator and serializer methods look like the following:</p> |
| |
| <ul> |
| |
| <li> |
| |
| <div> |
| <pre> |
| public javax.xml.stream.XMLStreamReader |
| getPullParser(javax.xml.namespace.QName qName) |
| </pre></div> |
| |
| <p>This method returns a pull parser that throws the right events |
| for this particular object. However there is a subtle difference |
| between element based classes and complexType based classes</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>An element based bean class (like MyElement.java in the |
| example) will <b><i>ignore the passed in QName</i></b>. |
| Instead of using the passed in QName it'll utilize its own QName |
| which is embedded in the class under the constant MY_QNAME, during |
| the code generation. Hence it is usual to call getPullparser() with |
| a null parameter for elements.</li> |
| |
| <li>A ComplexType based bean class (like SOAPStruct.java in the |
| example) will use the passed-in QName to return an instance of the |
| ADBpullparser. This will effectively wrap the elements inside with |
| an element having the passed QName</li> |
| </ol> |
| </li> |
| |
| <li> |
| |
| <div> |
| <pre> |
| public org.apache.axiom.om.OMElement getOMElement( |
| final javax.xml.namespace.QName parentQName, |
| final org.apache.axiom.om.OMFactory factory){ |
| </pre></div> |
| |
| <p>This method returns an OMElement representing the ADB bean |
| object.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Inside the getOMElement method an anonymous ADBDataSource class |
| is created. This anonymous class implements a serialize() method |
| where the serialization logic for that particular bean class is |
| handled. Finally an OMSourcedElementImpl object with the above |
| anonymous class type object as the data source is returned.</li> |
| </ol> |
| </li> |
| |
| <li> |
| |
| <div> |
| <pre> |
| public static [Object].Factory. |
| parse(javax.xml.stream.XMLStreamReader reader) |
| throws java.lang.Exception |
| </pre></div> |
| |
| <p>This method returns a populated instance of the class in |
| question. Note that</p> |
| |
| <div> |
| <pre> |
| [Object] |
| </pre></div> |
| will be replaced by the actual class that contains this method. Say |
| for SOAPStruct the method looks like |
| |
| <div> |
| <pre> |
| public static SOAPStruct.Factory. |
| parse(javax.xml.stream.XMLStreamReader reader) |
| throws java.lang.Exception |
| </pre></div> |
| |
| <p>Also note that the above parse method is available in the |
| <b>Factory</b> nested class within the relevant top level |
| class. Hence one will have to get the static Factory instance |
| before calling the parse method.</p> |
| </li> |
| </ul> |
| <a name="example" id="example"></a> |
| |
| <div class="section"> |
| <h3><a name="An_Example"></a>An Example!</h3> |
| |
| <p>Consider the following XML fragment</p> |
| |
| <div> |
| <pre> |
| <myElement xmlns="http://soapinterop.org/types"> |
| <varInt>5</varInt> |
| <varString>Hello</varString> |
| <varFloat>3.3</varFloat> |
| </myElement> |
| </pre></div> |
| |
| <p>Enthusiastic readers might already have figured out that this |
| XML fragment complies with the Schema mentioned above. The |
| following code snippet shows how to build a populated instance of |
| MyElement with the XML above:</p> |
| |
| <div> |
| <pre> |
| XMLStreamReader reader = XMLInputFactory.newInstance(). |
| createXMLStreamReader( |
| new ByteArrayInputStream(xmlString.getBytes())); |
| MyElement elt = MyElement.Factory.parse(reader); |
| </pre></div> |
| |
| <p>Optionally, the above xml fragment can be reproduced with the |
| following code fragment:</p> |
| |
| <div> |
| <pre> |
| OMElement omElement = myElement.getOMElement |
| (MyElement.MY_QNAME, OMAbstractFactory.getSOAP12Factory()); |
| String xmlString = omElement.toStringWithConsume(); |
| </pre></div> |
| |
| <p>Although this example takes on the tedious effort of creating a |
| reader out of a String, inside the Axis2 environment an |
| XMLStreamReader can be directly obtained from the OMElement! Hence, |
| the parse method becomes a huge advantage for hassle free object |
| creation.</p> |
| |
| <p>Similarly the reader obtained from the object can also be |
| utilized as needed. The following code fragment shows how to |
| utilize the getPullParser method to create an OMElement :</p> |
| |
| <div> |
| <pre> |
| XMLStreamReader reader = elt.getPullParser(null); |
| OMElement omElt = new StAXOMBuilder(reader).getDocumentElement(); |
| </pre></div> |
| |
| <p>That's all to it! If you are interested in learning more on ADB |
| the following documents may also be helpful. However, be sure to |
| check the limitations section that follows if you are planning to |
| use ADB for something serious.</p> |
| <a name="limitation" id="limitation"></a> |
| </div> |
| <div class="section"> |
| <h2><a name="Known_Limitations"></a>Known Limitations</h2> |
| |
| <p>ADB is meant to be a 'Simple' databinding framework and was not |
| meant to compile all types of schemas. The following limitations |
| are the most highlighted.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li>Complex Type Extensions and Restrictions.</li> |
| </ol> |
| <a name="more" id="more"></a> |
| |
| <div class="section"> |
| <h2><a name="Want_to_Learn_More"></a>Want to Learn More?</h2> |
| |
| <ul> |
| |
| <li><a href="adb-advanced.html">Advanced features of the ADB code |
| generator</a> - explains xsi:type based deserialization and helper |
| mode</li> |
| |
| <li><a href="adb-tweaking.html">Tweaking the ADB Code Generator</a> |
| - explains available mechanisms to extend ADB and possibly adopt it |
| to compile schemas to support other languages.</li> |
| |
| <li><a href="adb-codegen-integration.html">ADB and Axis2 |
| Integration</a> - explains how the ADB schema compiler was attached |
| to the Axis2 framework</li> |
| </ul> |
| |
| </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> |
