You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by aj...@apache.org on 2006/01/10 09:44:53 UTC
svn commit: r367524 - in /webservices/axis2/trunk/java/xdocs/0_94/adb:
adb-codegen-integration.html adb-howto.html adb-tweaking.html
Author: ajith
Date: Tue Jan 10 00:44:47 2006
New Revision: 367524
URL: http://svn.apache.org/viewcvs?rev=367524&view=rev
Log:
Updated the ADB documentation
Modified:
webservices/axis2/trunk/java/xdocs/0_94/adb/adb-codegen-integration.html
webservices/axis2/trunk/java/xdocs/0_94/adb/adb-howto.html
webservices/axis2/trunk/java/xdocs/0_94/adb/adb-tweaking.html
Modified: webservices/axis2/trunk/java/xdocs/0_94/adb/adb-codegen-integration.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/adb/adb-codegen-integration.html?rev=367524&r1=367523&r2=367524&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/adb/adb-codegen-integration.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/adb/adb-codegen-integration.html Tue Jan 10 00:44:47 2006
@@ -12,19 +12,72 @@
<p>ADB Integration with Axis2 is simple and straightforward. Given the
extension mechanism of the Axis2 code generator, the obvious choice for the
integrator is to write an extension. The extension that is added to support
-ADB is the SimpleDBExtension and can be found in the extensions list of the
-codegen-config.properties file</p>
+ADB is the SimpleDBExtension
+(<strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong>)
+and can be found in the extensions list of the codegen-config.properties
+file.</p>
+
+<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>
+
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <td><strong>User parameters</strong></td>
+ <td><strong>Selected code generation parameters</strong></td>
+ </tr>
+ <tr>
+ <td>None (no other parameter than the mandatory ones)</td>
+ <td>wrapClasses=false,writeClasses=false</td>
+ </tr>
+ <tr>
+ <td>-ss (server side)</td>
+ <td>wrapClasses=false,writeClasses=true</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>If the users want to override these settings manually, they need to use
+the following parameters with the command line (prefixed with -E)</p>
+
+<table border="1">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <td><strong>Parameter Name</strong></td>
+ <td><strong>Allowed values</strong></td>
+ <td><strong>Description</strong></td>
+ </tr>
+ <tr>
+ <td>r</td>
+ <td>true, false</td>
+ <td>Sets the write flag. If set to true the classes will be written by
+ ADB</td>
+ </tr>
+ <tr>
+ <td>w</td>
+ <td>true, false</td>
+ <td>Sets the packing flag. if true the classes will be packed.</td>
+ </tr>
+ </tbody>
+</table>
+
+<p></p>
+
+<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>
<h2>Things to Remember</h2>
<ol>
- <li>The SimpleDBExtension adds a prefix to the ADB packaging. This prefix
- is curently adb, hence all the ADB generated code will be inside the
- adb.* package. This prefix is used by the ant build file template and any
- change done to this prefix needs to be carefully handled in order to keep
- the ant build intact.</li>
<li>SimpleDBExtension is made to process requests only when the databinding
framework is specified as ADB (using the switch -d adb )</li>
</ol>
-<hr/>
+<hr>
</body>
</html>
Modified: webservices/axis2/trunk/java/xdocs/0_94/adb/adb-howto.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/adb/adb-howto.html?rev=367524&r1=367523&r2=367524&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/adb/adb-howto.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/adb/adb-howto.html Tue Jan 10 00:44:47 2006
@@ -30,17 +30,17 @@
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"/></p>
+<p><img src="images/ADB.jpg"></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>
+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>
<h2>Code and Dependencies</h2>
@@ -49,9 +49,8 @@
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 <strong>org.apache.axis2.schema.*</strong>
-package. This package resides in the codegen module of the Axis2 source
-tree.</p>
+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>
@@ -119,12 +118,66 @@
</ul>
<p>For a comprehensive code sample in invoking the schema compiler throught
-the API, the following classes would be helpful</p>
+the API, the following classes would be helpful. One would also need an
+undertanding 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>
+<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 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>
+ <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">
+ <caption></caption>
+ <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
+ packge) will be generated. The default is off.</td>
+ </tr>
+ </tbody>
+</table>
+
<h2>Deep into the Generated Code</h2>
<p>When the schema compiler is invoked (oneway or another) it generates code
@@ -156,9 +209,11 @@
<element name="myElement" type="tns:SOAPStruct"/>
</schema></pre>
-<p>This particular schema generates the following two classes in the
-designated package. This package is derived from the target Namespace of the
-schema.</p>
+<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. This package
+is derived from the target Namespace of the schema.</p>
<ol>
<li>myElement.java</li>
<li>SOAPStruct.java</li>
@@ -166,9 +221,9 @@
<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>
+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
@@ -196,8 +251,8 @@
<li><pre> public static [Object]
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>
+ <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
Modified: webservices/axis2/trunk/java/xdocs/0_94/adb/adb-tweaking.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/adb/adb-tweaking.html?rev=367524&r1=367523&r2=367524&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/adb/adb-tweaking.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/adb/adb-tweaking.html Tue Jan 10 00:44:47 2006
@@ -24,9 +24,9 @@
<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 schema compiler delegates the bean writing task to the
- specified instance of the BeanWriter.</p>
+ <strong>org.apache.axis2.schema.writer.BeanWriter</strong> inteface. The
+ schema compiler delegates the bean writing task to the specified instance
+ of the BeanWriter.</p>
</li>
<li>schema.bean.writer.template
<p>This specifies the template to be used in the BeanWriter. The
@@ -36,10 +36,9 @@
</li>
<li>schema.bean.typemap
<p>This is the type map to be used by the schema compiler. it should be
- an implementation of the
- <strong>org.apache.axis2.schema.typemap</strong> interface.
- The default typemap implementation encapsulates a hashmap with type QName
- to Class name string mapping.</p>
+ an implementation of the <strong>org.apache.axis2.schema.typemap</strong>
+ interface. The default typemap implementation encapsulates a hashmap with
+ type QName to Class name string mapping.</p>
</li>
</ul>
@@ -52,13 +51,14 @@
simply changing the template used.</p>
<p>The template for plain java beans is already available in the
-<strong>org.apache.axis2.schema.template </strong>package. To
-make this work replace the
+<strong>org.apache.axis2.schema.template </strong>package. To make this work
+replace the
<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> Congratualtions!
-You just tweaked ADB to generate plain java beans.</p>
+</strong>in the schema-compile.properties<strong>.</strong> </p>
+
+<p>Congratualtions! 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
@@ -73,17 +73,16 @@
<ul>
<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 C# or even C++), one would even be able to extend the
- JavaBeanWriter itself.</p>
+ 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
+ C# or even C++), one would even be able to extend the JavaBeanWriter
+ itself.</p>
</li>
<li>The TypeMap
<p>Implement the TypeMap interface for this class. The
- <strong>org.apache.axis2.schema.typemap.JavaTypeMap</strong>
- class is a simple implementation for the typemap where the QName to class
- name strings are kept inside a hashmap instance. This technique is fairly
+ <strong>org.apache.axis2.schema.typemap.JavaTypeMap</strong> class is a
+ simple implementation for the typemap where the QName to class name
+ strings are kept inside a hashmap instance. This technique is fairly
sufficient and only the type names would need to change to support
another language.</p>
</li>
@@ -92,6 +91,10 @@
<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>
-<hr/>
+<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
+free experiment with it and modify the schema compiler accordingly to their
+needs.</p>
+<hr>
</body>
</html>