Author: chatra
Date: Thu Nov 9 23:18:58 2006
New Revision: 473220
URL: http://svn.apache.org/viewvc?view=rev&rev=473220
Log:
made minor improvements with the help of Jira AXIS2-1654 patch
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/adb/adb-howto.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/adb/adb-howto.html
URL:
http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/adb/adb-howto.html?view=diff&rev=473220&r1=473219&r2=473220
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/adb/adb-howto.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/adb/adb-howto.html Thu Nov 9
23:18:58 2006
@@ -1,379 +1,380 @@
-<!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 http-equiv="content-type" content=
-"text/html; charset=us-ascii" />
-<title>ADB - Howto</title>
-</head>
-<body lang="en" xml:lang="en">
-<h1>Axis2 Databinding Framework</h1>
-<p>This document aims to provide the 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>
-<h2>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>
-<h2><a name="intro" id="intro">Introduction</a></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 it's 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>
-<h2>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 XmlSchema library 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 be used 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>
-<h2>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 DOMimplementation
-(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 <strong>org.apache.axis2.schema.*</strong>
-package. This package resides in the codegen module of the Axis2
-source tree.</p>
-<p>Following are the important classes and files:</p>
-<ol>
-<li><strong>SchemaCompiler</strong> - The work horse that really
-compiles the schema into classes.</li>
-<li><strong>BeanWriter</strong> - BeanWriter represents the kind of
-interface the SchemaCompiler accepts as a writer. The writer needs
-to handle the actual writing of the clasess</li>
-<li><strong>JavaBeanWriter</strong> - The default implementation of
-the BeanWriter interface.</li>
-<li><strong>TypeMap</strong> - represents the interface that the
-schema compiler looks towards to find classes</li>
-<li><strong>JavaTypeMap</strong> - the default implementation of
-the TypeMap</li>
-<li><strong>BeanTemplate.xsl</strong> - the XSLtemplate the
-JavaBeanWriter uses.</li>
-<li><strong>Schema-compile.properties</strong> - 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 codegen module. This will generate the
-<strong>axis2-codegen-{$version}.jar</strong> inside the target
-folder which is directly usable when the ADB schema compiler is
-required.</p>
-<p>The runtime dependancies for the ADB generated classes is in the
-Axis2 ADB module. Hence to compile and work with the generated
-classes the <strong>axis2-adb-{$version}.jar</strong> needs to be
-in the classpath apart from other dependancies like the StAX
-utilities.</p>
-<p><a name="code_gen" id="code_gen"></a></p>
-<h2>Invoking the ADB Code Generator</h2>
-<h3>As a Standalone Schema Compiler</h3>
-<p>ADB comes with a main class XSD2Java that allows the schemas to
-be compiled just by giving the schema file reference.This main
-class is pretty much primitive and does not provide much control
-over the code generation process. This is bound to improve in the
-near future.</p>
-<p>Code generator accepts the following parameters</p>
-<ol>
-<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 main class has no validations built in, the compiler
-is likely to cough up an unexpected error message if these
-parameters are not supplied properly.</p>
-<a name="api" id="api"></a>
-<h3>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><strong>SchemaCompiler - Constructor</strong>
-<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><strong>SchemaCompiler - Compile(XMLSchema schema)</strong>
-<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><strong>SchemaCompiler - Compile(List schemaList)</strong>
-<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><strong>org.apache.axis2.schema.XSD2Java</strong></li>
-<li><strong>org.apache.axis2.schema.ExtensionUtility</strong></li>
-</ul>
-<a name="gen_modes" id="gen_modes"></a>
-<h2>Generation Modes</h2>
-<p>ADB extension provides several generation modes for the data
-bound classes.</p>
-<ol>
-<li><strong>Integrated Mode</strong>
-<p>In this mode the classes are generated as inner classes of the
-stub, message receiver or the interface. The ADB framework refrains
-from writing the classes but provides a map of DOM document objects
-that contains the model for the databinding class. The implementers
-are free to use the models for their needs. The Axis2 codegen
-engine parses these documents within its own XSLT parser to create
-the necessary code.</p>
-<p>Integrated mode is supposed to be used by the tool builders.</p>
-</li>
-<li><strong>Wrapped Mode</strong>
-<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><strong>Expanded Mode</strong>
-<p>This is the usual mode where the codegenerator 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 is table lists the options and the consequences of using
-them.</p>
-<table border="1" summary="Options and descriptions">
-<tbody>
-<tr>
-<td><strong>Field Name in Options</strong></td>
-<td><strong>Description</strong></td>
-</tr>
-<tr>
-<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>
-<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>
-<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>
-<td>helperMode</td>
-<td>The switch that determines whether to switch to helper mode or
-not. Please see the advanced section for details of the helper
-mode</td>
-</tr>
-<tr>
-<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>
-<h2>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>
-<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 the sequence and all is not yet implemented.</li>
-<li>All top level elements become classes. This is a rather
-questioning feature since unless classes are generated for the top
-level elements the handling of elements become 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 piece of schema</p>
-<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">
-<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>
-<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 generates the following two classes in the
-designated package, which in this case would be
-<strong>org.soapinterop.types</strong>. This package is derived
-from the target namespace of the schema.</p>
-<ol>
-<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 creation and serializing the beans.
-Note that to make this work, the generated beans implement the
-<strong>org.apache.axis2.databinding.ADBBean</strong> interface</p>
-<p>The creator and reader methods look like the following</p>
-<ul>
-<li>
-<pre>
-public javax.xml.stream.XMLStreamReader
- getPullParser(javax.xml.namespace.QName qName)
-</pre>
-<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>
-<li>An element based bean class (like MyElement.java in the
-example) will <strong><em>ignore the passed in QName</em></strong>.
-Instead of using the passed in QName it'll utilize it's 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 for the 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>
-<pre>
- public static [Object].Factory.
- parse(javax.xml.stream.XMLStreamReader reader)
- throws java.lang.Exception
-</pre>
-<p>This method returns a populated instance of the class in
-question. Note that</p>
-<pre>
-[Object]
-</pre>
-will be replaced by the actual class that contains this method. Say
-for SOAPStruct the method looks like
-<pre>
-public static SOAPStruct.Factory.
- parse(javax.xml.stream.XMLStreamReader reader)
- throws java.lang.Exception
-</pre>
-<p>Also note that the above parse method is available in the
-<strong>Factory</strong> class generated into the relevant top
-level class.Hence one will have to get the static Factory instance
-before calling the parse methods</p>
-</li>
-</ul>
-<a name="example" id="example"></a>
-<h3>An Example!</h3>
-<p>Consider the following XML fragment</p>
-<pre>
-<myElement>
- <varInt>5</varInt>
- <varString>Hello</varString>
- <varFloat>3.3</varFloat>
-</myElement>
-</pre>
-<p>Enthusiastic readers might already have figured out that this
-piece of XML complies to the Schema mentioned above. The following
-piece of code shows how to build a populated instance of MyElement
-with this fragment of XML</p>
-<pre>
-XMLStreamReader reader = XMLInputFactory.newInstance().
- createXMLStreamReader(
- new
ByteArrayInputStream(xmlString.getBytes()));
-MyElement elt = MyElement.Factory.parse(reader);
-</pre>
-<p>Although this example takes on the tedious effort of creating a
-reader out of the String, inside the Axis2 environment an
-XMLStreamReader can be direclty asked 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>
-<pre>
-XMLStreamReader reader = elt.getPullParser(null);
-OMElement omElt = new StAXOMBuilder(reader).getDocumentElement();
-</pre>
-<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>
-<h2>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>
-<li>Complex Extensions and Restrictions, Simple Extensions and
-Restrictions are not supported.</li>
-</ol>
-<p><a name="more" id="more"></a></p>
-<h2>Want to Learn More?</h2>
-<ul>
-<li><a href="adb-advanced.html">Advanced features of the ADB code
-generator</a>- explains xsi:type based desrialization 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>
-<hr />
-</body>
-</html>
+<!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 http-equiv="content-type" content=
+"text/html; charset=us-ascii" />
+<title>ADB - Howto</title>
+</head>
+<body lang="en" xml:lang="en">
+<h1>Axis2 Databinding Framework</h1>
+<p>This document aims to provide the 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>
+<h2>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>
+<h2>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 it's 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>
+<h2>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 XmlSchema library 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 be used 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>
+<h2>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 DOMimplementation
+(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 <strong>org.apache.axis2.schema.*</strong>
+package. This package resides in the codegen module of the Axis2
+source tree.</p>
+<p>Following are the important classes and files:</p>
+<ol>
+<li><strong>SchemaCompiler</strong> - The work horse that really
+compiles the schema into classes.</li>
+<li><strong>BeanWriter</strong> - BeanWriter represents the kind of
+interface the SchemaCompiler accepts as a writer. The writer needs
+to handle the actual writing of the clasess</li>
+<li><strong>JavaBeanWriter</strong> - The default implementation of
+the BeanWriter interface.</li>
+<li><strong>TypeMap</strong> - represents the interface that the
+schema compiler looks towards to find classes</li>
+<li><strong>JavaTypeMap</strong> - the default implementation of
+the TypeMap</li>
+<li><strong>BeanTemplate.xsl</strong> - the XSLtemplate the
+JavaBeanWriter uses.</li>
+<li><strong>Schema-compile.properties</strong> - 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 codegen module. This will generate the
+<strong>axis2-codegen-{$version}.jar</strong> inside the target
+folder which is directly usable when the ADB schema compiler is
+required.</p>
+<p>The runtime dependancies for the ADB generated classes is in the
+Axis2 ADB module. Hence to compile and work with the generated
+classes the <strong>axis2-adb-{$version}.jar</strong> needs to be
+in the classpath apart from other dependancies like the StAX
+utilities.</p>
+<a name="code_gen" id="code_gen"></a>
+<h2>Invoking the ADB Code Generator</h2>
+<a name="schema_compiler"></a>
+<h3>As a Standalone Schema Compiler</h3>
+<p>ADB comes with a main class XSD2Java that allows the schemas to
+be compiled just by giving the schema file reference.This main
+class is pretty much primitive and does not provide much control
+over the code generation process. This is bound to improve in the
+near future.</p>
+<p>Code generator accepts the following parameters</p>
+<ol>
+<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 main class has no validations built in, the compiler
+is likely to cough up an unexpected error message if these
+parameters are not supplied properly.</p>
+<a name="api" id="api"></a>
+<h3>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><strong>SchemaCompiler - Constructor</strong>
+<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><strong>SchemaCompiler - Compile(XMLSchema schema)</strong>
+<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><strong>SchemaCompiler - Compile(List schemaList)</strong>
+<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><strong>org.apache.axis2.schema.XSD2Java</strong></li>
+<li><strong>org.apache.axis2.schema.ExtensionUtility</strong></li>
+</ul>
+<a name="gen_modes" id="gen_modes"></a>
+<h2>Generation Modes</h2>
+<p>ADB extension provides several generation modes for the data
+bound classes.</p>
+<ol>
+<li><strong>Integrated Mode</strong>
+<p>In this mode the classes are generated as inner classes of the
+stub, message receiver or the interface. The ADB framework refrains
+from writing the classes but provides a map of DOM document objects
+that contains the model for the databinding class. The implementers
+are free to use the models for their needs. The Axis2 codegen
+engine parses these documents within its own XSLT parser to create
+the necessary code.</p>
+<p>Integrated mode is supposed to be used by the tool builders.</p>
+</li>
+<li><strong>Wrapped Mode</strong>
+<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><strong>Expanded Mode</strong>
+<p>This is the usual mode where the codegenerator 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 is table lists the options and the consequences of using
+them.</p>
+<table border="1" summary="Options and descriptions">
+<tbody>
+<tr>
+<td><strong>Field Name in Options</strong></td>
+<td><strong>Description</strong></td>
+</tr>
+<tr>
+<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>
+<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>
+<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>
+<td>helperMode</td>
+<td>The switch that determines whether to switch to helper mode or
+not. Please see the advanced section for details of the helper
+mode</td>
+</tr>
+<tr>
+<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>
+<h2>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>
+<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 the sequence and all is not yet implemented.</li>
+<li>All top level elements become classes. This is a rather
+questioning feature since unless classes are generated for the top
+level elements the handling of elements become 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 piece of schema</p>
+<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">
+<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>
+<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 generates the following two classes in the
+designated package, which in this case would be
+<strong>org.soapinterop.types</strong>. This package is derived
+from the target namespace of the schema.</p>
+<ol>
+<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 creation and serializing the beans.
+Note that to make this work, the generated beans implement the
+<strong>org.apache.axis2.databinding.ADBBean</strong> interface</p>
+<p>The creator and reader methods look like the following</p>
+<ul>
+<li>
+<pre>
+public javax.xml.stream.XMLStreamReader
+ getPullParser(javax.xml.namespace.QName qName)
+</pre>
+<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>
+<li>An element based bean class (like MyElement.java in the
+example) will <strong><em>ignore the passed in QName</em></strong>.
+Instead of using the passed in QName it'll utilize it's 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 for the 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>
+<pre>
+ public static [Object].Factory.
+ parse(javax.xml.stream.XMLStreamReader reader)
+ throws java.lang.Exception
+</pre>
+<p>This method returns a populated instance of the class in
+question. Note that</p>
+<pre>
+[Object]
+</pre>
+will be replaced by the actual class that contains this method. Say
+for SOAPStruct the method looks like
+<pre>
+public static SOAPStruct.Factory.
+ parse(javax.xml.stream.XMLStreamReader reader)
+ throws java.lang.Exception
+</pre>
+<p>Also note that the above parse method is available in the
+<strong>Factory</strong> class generated into the relevant top
+level class.Hence one will have to get the static Factory instance
+before calling the parse methods</p>
+</li>
+</ul>
+<a name="example" id="example"></a>
+<h3>An Example!</h3>
+<p>Consider the following XML fragment</p>
+<pre>
+<myElement>
+ <varInt>5</varInt>
+ <varString>Hello</varString>
+ <varFloat>3.3</varFloat>
+</myElement>
+</pre>
+<p>Enthusiastic readers might already have figured out that this
+piece of XML complies to the Schema mentioned above. The following
+piece of code shows how to build a populated instance of MyElement
+with this fragment of XML</p>
+<pre>
+XMLStreamReader reader = XMLInputFactory.newInstance().
+ createXMLStreamReader(
+ new
ByteArrayInputStream(xmlString.getBytes()));
+MyElement elt = MyElement.Factory.parse(reader);
+</pre>
+<p>Although this example takes on the tedious effort of creating a
+reader out of the String, inside the Axis2 environment an
+XMLStreamReader can be direclty asked 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>
+<pre>
+XMLStreamReader reader = elt.getPullParser(null);
+OMElement omElt = new StAXOMBuilder(reader).getDocumentElement();
+</pre>
+<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>
+<h2>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>
+<li>Complex Extensions and Restrictions, Simple Extensions and
+Restrictions are not supported.</li>
+</ol>
+<a name="more" id="more"></a>
+<h2>Want to Learn More?</h2>
+<ul>
+<li><a href="adb-advanced.html">Advanced features of the ADB code
+generator</a> - explains xsi:type based desrialization 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>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
