axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r330014 - in /webservices/axis2/trunk/java/xdocs/adb: ./ adb-howto.html
Date Tue, 01 Nov 2005 10:09:02 GMT
Author: ajith
Date: Tue Nov  1 02:08:56 2005
New Revision: 330014

Adding ADB documentation. Still halfway through


Added: webservices/axis2/trunk/java/xdocs/adb/adb-howto.html
--- webservices/axis2/trunk/java/xdocs/adb/adb-howto.html (added)
+++ webservices/axis2/trunk/java/xdocs/adb/adb-howto.html Tue Nov  1 02:08:56 2005
@@ -0,0 +1,145 @@
+  <meta http-equiv="content-type" content="">
+  <title></title>
+<h1>Axis2 Databinding Framework</h1>
+<p>The objective of the Axis2Databinding 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. 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. Note that ADB is written in a fashion that
+allows it to be used as a standalone schema compiler and also to be extended
+to generate code for other languages.</p>
+<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 generators architecture is depicted below</p>
+<p>ADB utilizes the WS-commons XmlSchema library for reading the Schema. The
+object model for the schema comes in the form of a 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 the technique they prefer, as in the case of the JavaBeanWriter,
+they use 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>
+<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 special
+dependencies on any other special jar files. The code for the schema compiler
+is completely in the org.apache.axis2.databinding.schema.* package. This
+package resides in the codegen module of the Axis2 source tree.</p>
+<p>Following are the important classes and files</p>
+  <li>SchemaCompiler - The work horse that really compiles the schema into
+    classes.</li>
+  <li>BeanWriter - 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>JavaBeanWriter - The default implementation of the BeanWriter
+  interface.</li>
+  <li>TypeMap - represents the interface that the schema compiler looks
+    towards to find classes</li>
+  <li>JavaTypeMap - the default implementation of the TypeMap</li>
+  <li>BeanTemplate.xsl - the XSLtemplate the JavaBeanWriter uses.</li>
+  <li> - The property file for the schema
+  compiler</li>
+<p>The easiest way to obtain the ADB binaries is to run the maven build for
+the codegen module. This will generate the codegen-{$version}.jar inside the
+target folder which is directly usable when the ADB schema compiler is
+<h2>Invoking the ADB Code Generator</h2>
+<h3>As a standalone schema compiler</h3>
+<p>ADB comes with a mainclass 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 follwing parameters</p>
+  <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 fileSystem</li>
+<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
+<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>
+  <li>SchemaCompiler - Constructor
+    <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>SchemaCompiler - Compile(XMLSchema schema)
+    <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>SchemaCompiler - Compile(List schemaList)
+    <p>Similar to the previous method but accepts a list of schemas instead
+    of one.</p>
+  </li>
+<h2>Deep into the Generated Code</h2>
+<p>When the schema compiler is invoked (oneway or another) it generates code
+depending on the following rules</p>
+  <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 rather a questioning
+    feature but unless classes are generated for the top level elements the
+    handling of elements become difficult and messy!</li>
+<p>Once the code is generated according to the rules it looks like the
+following. Consider the follwing piece of schema</p>
+<pre>&lt;schema xmlns="" xmlns:xsd=""
+xmlns:tns="" targetNamespace=""&gt;
+&lt;import namespace=""/&gt;
+&lt;complexType name="SOAPStruct"&gt;
+&lt;element name="varString" type="xsd:string"/&gt;
+&lt;element name="varInt" type="xsd:int"/&gt;
+&lt;element name="varFloat" type="xsd:float"/&gt;
+&lt;element name="myElement" type="tns:SOAPStruct"/&gt;
+<p>This particular schema generates the following two classes </p>

View raw message