You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2006/04/26 08:52:21 UTC
svn commit: r397113 - in /webservices/axis2/trunk/java/xdocs/latest/adb:
adb-codegen-integration.html adb-howto.html adb-tweaking.html
Author: chatra
Date: Tue Apr 25 23:52:19 2006
New Revision: 397113
URL: http://svn.apache.org/viewcvs?rev=397113&view=rev
Log:
upgraded/improved docs for Axis2 1.0
Modified:
webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html
webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html
webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html
Modified: webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html?rev=397113&r1=397112&r2=397113&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-codegen-integration.html Tue Apr 25 23:52:19 2006
@@ -7,7 +7,17 @@
<body>
<h1>ADB Integration With Axis2</h1>
-<h2>Introduction</h2>
+<p>This document will assist you to write an extension using the integrator
+in order to integrate ADB with Axis2.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#select_modes">Selection of Generation Modes for ADB</a></li>
+ <li><a href="#remember">Things to Remember</a></li>
+</ul>
+
+<h2><a name="intro">Introduction</a></h2>
<p>ADB Integration with Axis2 is simple and straightforward. Given the
extension mechanism of the Axis2 code generator, the obvious choice for the
@@ -16,13 +26,15 @@
(<strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong>)
and can be found in the extensions list of the codegen-config.properties
file.</p>
+<a name="select_modes"></a>
<h2>Selection of Generation Modes for ADB</h2>
<p>The extension sets the options for the code generator via the
CompilerOptions, depending on the users settings. The following table
-summarizes the use of options. Please refer the ADB-How to document for the
-different generation modes and their descriptions.</p>
+summarizes the use of options. Please refer the <a href="adb-howto.html"
+target="_blank">ADB-How to document</a> for the different generation modes
+and their descriptions.</p>
<table border="1">
<caption></caption>
@@ -72,6 +84,7 @@
<p>Note that these parameters have no relevant long names and MUST be
prefixed with a -E to be processed bt the code generator. For example</p>
<pre>WSDL2Java .... -Er true</pre>
+<a name="remember"></a>
<h2>Things to Remember</h2>
<ol>
Modified: webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html?rev=397113&r1=397112&r2=397113&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-howto.html Tue Apr 25 23:52:19 2006
@@ -1,6 +1,6 @@
<html>
<head>
- <meta http-equiv="content-type" content="">
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta content="">
<meta content="">
<meta content="">
@@ -10,19 +10,43 @@
<title>ADB - Howto</title>
</head>
-<body>
+<body lang="en">
<h1>Axis2 Databinding Framework</h1>
-<h2>Introduction</h2>
+<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 provided is
+categorized 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="#more">Want to Learn More?</a></li>
+ <li><a href="#limitation">Known Limitations</a></li>
+</ul>
+
+<h2><a name="intro">Introduction</a></h2>
<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>
+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"></a>
<h2>Architectural Overview</h2>
@@ -41,6 +65,7 @@
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"></a>
<h2>Code and Dependencies</h2>
@@ -52,31 +77,35 @@
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>
+<p>Following are the important classes and files:</p>
<ol>
- <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>Schema-compile.properties - The property file for the schema
- compiler</li>
+ <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 codegen-{$version}.jar inside the
target folder which is directly usable when the ADB schema compiler is
required.</p>
+<a name="code_gen"></a>
<h2>Invoking the ADB Code Generator</h2>
+<a name="schema_compiler"></a>
-<h3>As a standalone schema compiler</h3>
+<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
@@ -94,6 +123,7 @@
<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"></a>
<h3>Through the API</h3>
@@ -101,17 +131,17 @@
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>SchemaCompiler - Constructor
+ <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>SchemaCompiler - Compile(XMLSchema schema)
+ <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>SchemaCompiler - Compile(List schemaList)
+ <li><strong>SchemaCompiler - Compile(List schemaList)</strong>
<p>Similar to the previous method but accepts a list of schemas instead
of one.</p>
</li>
@@ -119,19 +149,20 @@
<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.</p>
+understanding of the generation modes of the ADB schema compiler when using
+it through the API.</p>
<ul>
<li><strong>org.apache.axis2.schema.XSD2Java</strong></li>
<li><strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong></li>
</ul>
+<a name="gen_modes"></a>
<h2>Generation Modes</h2>
-<p>ADB extension provides several Generation modes for the data bound
+<p>ADB extension provides several generation modes for the data bound
classes.</p>
<ol>
- <li><strong>Integrated mode</strong>
+ <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
@@ -140,12 +171,12 @@
documents with the an 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>
+ <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>
+ <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>
@@ -177,10 +208,11 @@
</tr>
</tbody>
</table>
+<a name="deep"></a>
-<h2>Deep into the Generated Code</h2>
+<h2>Deep into Generated Code</h2>
-<p>When the schema compiler is invoked (oneway or another) it generates code
+<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
@@ -261,6 +293,7 @@
throws java.lang.Exception </pre>
</li>
</ul>
+<a name="example"></a>
<h3>An Example!</h3>
@@ -274,8 +307,6 @@
<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>
-
-<p></p>
<pre>XMLStreamReader reader = XMLInputFactory.newInstance().
createXMLStreamReader(
new ByteArrayInputStream(xmlString.getBytes()));
@@ -289,20 +320,20 @@
<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>
-
-<p></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</p>
+<a name="more"></a>
-<p></p>
+<h2>Want to Learn More?</h2>
<ul>
- <li><a href="adb-tweaking.html">Tweaking the ADB code generator</a></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></li>
</ul>
+<a name="limitation"></a>
<h2>Known Limitations</h2>
ADB is meant to be a 'Simple' databinding framework and was not meant to
Modified: webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html?rev=397113&r1=397112&r2=397113&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/adb/adb-tweaking.html Tue Apr 25 23:52:19 2006
@@ -4,15 +4,30 @@
<title></title>
</head>
-<body>
+<body lang="en">
<h1>ADB Tweaking Guide</h1>
+<p>This document explains available mechanisms to extend ADB and possibly
+adopt it to compile schemas to support other languages.</p>
+
+<h2>Content</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#config">Know the Configuration</a></li>
+ <li><a href="#first_tweak">The First Tweak - Generate Plain Java
+ Beans</a></li>
+ <li><a href="#advanced_tweak">A More Advanced Tweak - Generate Code for
+ Another Language</a></li>
+</ul>
+<a name="intro"></a>
+
<h2>Introduction</h2>
<p>ADB is written with future extensions in mind, with a clear and flexible
-way to extend or modify it's functionality. This document explains available
-mechanisms to extend ADB and possibly adopt it to compile schemas to support
-other languages.</p>
+way to extend or modify it's functionality. Available mechanisms to extend
+ADB and possibly adopt it to compile schemas to support other languages are
+described below.</p>
+<a name="config"></a>
<h2>Know the Configuration</h2>
@@ -24,7 +39,7 @@
<li>schema.bean.writer.class
<p>This is the writer class. This is used by the schema compiler to write
the beans and should implement the
- <strong>org.apache.axis2.schema.writer.BeanWriter</strong> inteface. The
+ <strong>org.apache.axis2.schema.writer.BeanWriter</strong> interface. The
schema compiler delegates the bean writing task to the specified instance
of the BeanWriter.</p>
</li>
@@ -41,13 +56,14 @@
type QName to Class name string mapping.</p>
</li>
</ul>
+<a name="first_tweak"></a>
<h2>The First Tweak - Generate Plain Java Beans</h2>
<p>The first, most simple tweak for the code generator could be to switch to
plain bean generation. The default behavior of the ADB framework is to
generate ADBBeans, but most users, if they want to use ADB as a standalone
-compiler, would love to have plain java beans. This can infact be done by
+compiler, would love to have plain java beans. This can in fact be done by
simply changing the template used.</p>
<p>The template for plain java beans is already available in the
@@ -56,15 +72,16 @@
<strong>/org/apache/axis2/databinding/schema/template/ADBBeanTemplate.xsl
</strong>with the
<strong>/org/apache/axis2/databinding/schema/template/PlainBeanTemplate.xsl
-</strong>in the schema-compile.properties<strong>.</strong> </p>
+</strong>in the schema-compile.properties<strong>.</strong></p>
-<p>Congratualtions! You just tweaked ADB to generate plain java beans.</p>
+<p>Congratulations! You just tweaked ADB to generate plain java beans.</p>
<p>To generate custom formats, the templates need to be modified. The schema
-for the xml generated by the JavaBeanWriter is availble in the source tree
+for the xml generated by the JavaBeanWriter is available in the source tree
under the Other directory in the codegen module. Advanced users with
knowledge of XSLT can easily modify the templates to generate code in their
own formats.</p>
+<a name="advanced_tweak"></a>
<h2>A More Advanced Tweak - Generate Code for Another Language</h2>
@@ -74,7 +91,7 @@
<li>The BeanWriter
<p>Implement the BeanWriter interface for this class. A nice example is
the <strong>org.apache.axis2.schema.writer.JavaBeanWriter</strong> which
- has a lot of reusable code. Infact if the language is OOP based (such as
+ has a lot of reusable code. In fact if the language is OOP based (such as
C# or even C++), one would even be able to extend the JavaBeanWriter
itself.</p>
</li>
@@ -88,8 +105,8 @@
</li>
</ul>
-<p>Surprisngly this is enough to have other language support for ADB. Change
-the configuration and you are ready to generate code for other lanuages!</p>
+<p>Surprisingly this is enough to have other language support for ADB. Change
+the configuration and you are ready to generate code for other languages!</p>
<p>This tweaking guide is supposed to be a simple guideline for anyone who
wishes to dig deep into the mechanics of the ADB code generator. Users are