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 de...@apache.org on 2007/04/27 14:39:46 UTC
svn commit: r533081 [2/23] - in /webservices/axis2/site: ./ 1_2/ 1_2/adb/
1_2/adb/images/ 1_2/images/ 1_2/images/archi-guide/ 1_2/images/userguide/
1_2/jibx/ 1_2/resources/ 1_2/resources/schemas/ 1_2/src/ css/ download/0_9/
download/0_91/ download/0_92...
Added: webservices/axis2/site/1_2/WS_policy.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/WS_policy.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/WS_policy.html (added)
+++ webservices/axis2/site/1_2/WS_policy.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,132 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - WS Policy Support in Axis2</title><style type="text/css" media="all">
+ @import url("../style/maven-base.css");
+
+ @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="../modules/index.html">Modules</a></li><li class="none"><a href="../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../1_2/pojoguide.html">POJO Guide</a></li><li class="none"><a href="../1_2/spring.html">
Spring Guide</a></li><li class="none"><a href="../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../faq.html">FAQ</a></li><li class="none"><a href="../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href
="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../overview.html">Overview</a></li><li class="none"><a href="../svn.html">Checkout the Source</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a hr
ef="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Web_Services_Policy_Support_In_Apache_Axis2"></a><h2>Web Services Policy Support In Apache Axis2</h2><p>This document gives you an introduction to the role of Web services policy
+in Apache Axis2.</p><p>Send your feedback to: <a href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+(Subscription details are available on the <a href="http://ws.apache.org/axis2/mail-lists.html" class="externalLink" title="External Link">Axis2 site</a>.) Kindly
+prefix every email subject with [Axis2].</p><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li><a href="#what">What is Web Services (WS) Policy?</a></li>
+ <li><a href="#client">Client Side WS-Policy Support</a></li>
+ <li><a href="#server">Server Side WS-Policy Support</a></li>
+ <li><a href="#resources">Resources</a></li>
+</ul><p><a name="what"></a></p></div><div class="subsection"><a name="What_is_Web_Services__WS__Policy_"></a><h3>What is Web Services (WS) Policy?</h3><p>To consume non trivial web services you must fully understand its XML
+contract (WSDL) along with any other additional requirements, capabilities,
+or preferences that translate to the configuration of the service and
+essentially becomes the policies of the service.</p><p>WS Policy framework provides a way to express the policies of a service in
+a machine-readable way. A Web services infrastructure can be enhanced to
+understand and enforce policies at runtime. For instance, a service author
+might write a policy requiring a digital signature and encryption, while
+service consumers can use the policy information to reason out whether they
+can adhere to this policy information to use the service.</p><p>Furthermore, Web service infrastructure can be enhanced to enforce those
+requirements without requiring the service author to write even a single line
+of code.</p><p><a name="client"></a></p></div><div class="subsection"><a name="Client_Side_WS-Policy_Support"></a><h3>Client Side WS-Policy Support</h3><p>This release <strong>fully supports WS Policy at client-side</strong>. It
+means that when you codegen a stub against a WSLD which contains policies,
+the stub will contain the capability to engage the required modules with the
+appropriate configurations, plus it will generate additional methods in the
+stub where the user can set certain properties. For instance, if there is a
+security policy attached to a binding, the generated stub will engage the
+security module for that service with the appropriate security configurations
+with some addtional methods that the user can use to set properties in the
+generated stub.</p></div><div class="subsection"><a name="How_it_works:"></a><h3>How it works:</h3></div><div class="subsection"><a name="Phase_1:_At_PolicyEvaluator"></a><h3>Phase 1: At PolicyEvaluator</h3><p>The Codegen engine runs a few of its registered extensions before it
+generates the stub. When the PolicyEvalutor (which is a registered Codegen
+extension) is initialized, it populates a registry of QNames of supported
+policy assertions to PolicyExtensions.</p><p>For instance, module Foo might have a mapping of assertion
+{http://test.com/foo, foo} which means any assertion that has this name will
+be processed by this module. The Foo module might implement the
+ModulePolicyExtension interface through which the PolicyExtension object can
+be obtained.</p><p>A <strong>PolicyExtension</strong> is the access point for a module to add
+any additional methods to the stub. For instance a Reliable Messaging module
+can add startSequence() and endSequence() methods to the stub, that the user
+must call to start and end an RM sequence.</p><p>Then at the engagement of the PolicyEvaluator, the effective policy of
+each message of every operation is calculated based on policy information
+declared in the WSDL document. Here we assume that the effective policy of an
+operation contains a single alternative (<strong>Multiple policy alternatives
+are not supported</strong>). Then we split that policy as follows into few
+other policies such that, each policy will contain assertions that can be
+processed by a single module.</p>
+ <div class="source"><pre> <wsp:Policy> <wsp:Policy> <wsp:Policy>
+ <a:Foo/> <a:Foo/> <b:Foo/>
+ <b:Bar/> => </wsp:Policy>
+ </wsp:Policy>
+ </wsp:Policy>
+
+</pre></div>
+ <p>Then each policy is given the appropriate PolicyExtension with an
+org.w3c.Element type object to which the module can append any other
+elements/attributes it wishes. Those attributes/elements should resolve to
+meaningful stub functions through the Custom PolicyExtensionTemplate.xsl at a
+latter point of time.</p><p>For instance, depending on the policy, the Security module can append
+<username>, <passwd> elements to the given element as children,
+which are later resolved into setUsername(..), setPasswd(..), functions of
+the stub. This way a module can include additional methods to the stub that
+can be used to get specific propreties from the user. These methods store any
+user input in the ServiceClient properties
+(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
+the module.</p></div><div class="subsection"><a name="Phase_2:_At_AxisServiceBasedMultiLanguageClientEmitter"></a><h3>Phase 2: At AxisServiceBasedMultiLanguageClientEmitter</h3><p>Further, policies (based on the WSDL) at appropriate levels (service
+level, operation level) are stored as policy strings in the stub. If there
+are a few policies at a given level, they are merged together and represented
+as a single policy in the stub. Few more generic methods are also added to
+the stub which are used to evaluate and process the policies at runtime.</p></div><div class="subsection"><a name="Phase_3:_Runtime"></a><h3>Phase 3: Runtime</h3><p>When a new stub object is created, the policy strings in the stub are
+converted into policy objects and are set in the AxisDescription hierarchy
+that is used in the stub. In other words, any policy information available in
+the WSDL will be preserved in the AxisService object that is used in the
+stub.</p><p>Then based on its policy, each AxisDescription is engaged to a set of
+modules. Modules can do a prior calculation of configurations if needed at
+the engagement.</p><p>When the stub method is invoked, those modules which are engaged to that
+AxisDescription, access the policy for that operation via the AxisDescription
+object. It can get the other required information from the MessageContext,
+which is stored by stub methods that the module has added to the stub
+earlier, through the ModulePolicyExtension implementation. The modules are
+required to load their configurations according to the effective policy,
+which is set at AxisDescription, and the properties they get via
+MessageContext.</p><p><a name="server"></a></p></div><div class="subsection"><a name="Server_Side_WS-Policy_Support"></a><h3>Server Side WS-Policy Support</h3><p>In this current release, the Apache Axis2 framework uses the
+WS-Commons/Neethi framework to manipulate policy documents. All its
+description builders store the policy information included in description
+documents (services.xml, axis2.xml, .. etc) in the appropriate description
+classes. This information is available at both deployment and run time via
+these description classes.</p><p>When generating WSDL dynamically for each service, policy information in
+the description classes is included. For instance, if you declare a policy in
+axis2.xml, then that policy is reflected in the service elements of the WSDL
+of every service. If a policy is declared in a services.xml, it is shown in
+the service element of WSDL for that particular service.</p><p>Further, when a service is deployed, an arbitary policy alternative is
+selected and set for each AxisOperation and AxisMessages of the AxisService.
+If the selected Policy alternative cannot be supported by any modules that
+are capable of processing the selective alternative, then the service is
+considered as a faulty service. Else, the set of modules is engaged at
+appropriate levels to support the requirments and capabilities that are
+defined in the Policies associated with the AxisDescription.</p><p>It is evident that there is some work left to make Apache Axis2 a fully
+fledged ws-policy supported Web service infrastructure. However, it is
+encouraging to note that we've taken the first steps towards this goal. We
+appreciate any suggestions, patches, etc., you send us in this regard. Keep
+on contributing!</p><p><a name="resources"></a></p></div><div class="subsection"><a name="Resources"></a><h3>Resources</h3><ul>
+ <li>Apache Neethi (WS Policy Implementation) official site- <a href="http://ws.apache.org/commons/neethi/index.html" class="newWindow" title="New Window" target="_blank">Home Page</a></li>
+ <li>Sanka Samaranayake, March 2006. <a href="http://www.wso2.net/articles/neethi/java/2006/01/24/ws-policy" class="newWindow" title="New Window" target="_blank">Web services Policy - Why, What & How</a></li>
+ <li><a href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/" class="newWindow" title="New Window" target="_blank">WS-commons/policy SVN</a></li>
+ <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf" class="newWindow" title="New Window" target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
+</ul></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/adb/adb-advanced.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/adb/adb-advanced.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/adb/adb-advanced.html (added)
+++ webservices/axis2/site/1_2/adb/adb-advanced.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,119 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - Advanced Axis2 Databinding Framework Features</title><style type="text/css" media="all">
+ @import url("../../style/maven-base.css");
+
+ @import url("../../style/maven-theme.css");</style><link rel="stylesheet" href="../../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../../download.cgi">Releases</a></li><li class="none"><a href="../../modules/index.html">Modules</a></li><li class="none"><a href="../../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../../1_2/pojoguide.html">POJO Guide</a></li><li class="none"
><a href="../../1_2/spring.html">Spring Guide</a></li><li class="none"><a href="../../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../../faq.html">FAQ</a></li><li class="none"><a href="../../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../
../refLib.html">Reference Library</a></li><li class="none"><a href="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../../overview.html">Overview</a></li><li class="none"><a href="../../svn.html">Checkout the Source</a></li><li class="none"><a href="../../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../../team-list.html">Project Team</a></li><li class="none"><a href="../../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><l
i class="none"><a href="../../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Advanced_Axis2_Databinding_Framework_Features"></a><h2>Advanced Axis2 Databinding Framework Features</h2><p>The aim of this section is provide an insight into the newly added
+advanced features of Axis2 Databinding (ADB) Framework.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ <li><a href="#typeSupport">xsi:type Support</a></li>
+ <li><a href="#helper">Helper Mode</a></li>
+ <li><a href="#more">More Stuff on ADB?</a></li>
+</ul><p><a name="typeSupport"></a></p></div><div class="subsection"><a name="xsi:type_Support"></a><h3>xsi:type Support</h3><p>This is implemented by adding a extension maping class. The code that
+calls the extension mapper is generated inside the Factory.parse method of
+the beans and gets active when the xsi:type attribute is present. The
+following code fragment shows how the generated type mapper looks like : </p>
+ <div class="source"><pre> public static java.lang.Object getTypeObject(java.lang.String namespaceURI,
+ java.lang.String typeName,
+ javax.xml.stream.XMLStreamReader reader) throws java.lang.Exception{
+
+ if (
+ "http://soapinterop.org/types".equals(namespaceURI) &&
+ "SOAPStruct".equals(typeName)){
+ return com.test.SOAPStruct.Factory.parse(reader);
+ }
+ throw new java.lang.RuntimeException("Unsupported type " + namespaceURI + " " + typeName);
+ }
+
+</pre></div>
+ <p>Inside every Factory.parse method, the extension mapper gets called when a
+xsi:type attribute is encountered <strong>and</strong> that type is not the
+type that is being parsed.</p><p>The following code fragment shows how the ADB deserialize method calls the
+mapper class : </p>
+ <div class="source"><pre>
+ if (reader.getAttributeValue("http://www.w3.org/2001/XMLSchema-instance","type")!=null){
+ java.lang.String fullTypeName = reader.getAttributeValue("http://www.w3.org/2001/XMLSchema-instance",
+ "type");
+ if (fullTypeName!=null){
+ java.lang.String nsPrefix = fullTypeName.substring(0,fullTypeName.indexOf(":"));
+ nsPrefix = nsPrefix==null?"":nsPrefix;
+
+ java.lang.String type = fullTypeName.substring(fullTypeName.indexOf(":")+1);
+ if (!"SOAPStruct".equals(type)){
+ //find namespace for the prefix
+ java.lang.String nsUri = reader.getNamespaceContext().getNamespaceURI(nsPrefix);
+ return (SOAPStruct)org.soapinterop.types.ExtensionMapper.getTypeObject(
+ nsUri,type,reader);
+ }
+
+ }
+ }
+
+</pre></div>
+ <p>This should make the xsi:type based parsing possible and should
+result in proper xsi:type based serializations at runtime.</p><p>This is automatically done but the package name for the mapper class can
+be set as an CompilerOption.</p>
+ <div class="source"><pre>
+ CompilerOptions compilerOptions = new CompilerOptions();
+ compilerOptions.setWriteOutput(true);
+
+ compilerOptions.setOutputLocation(new File("src"));
+ try {
+ SchemaCompiler schemaCompiler = new SchemaCompiler(compilerOptions);
+ XmlSchemaCollection xmlSchemaCollection = new XmlSchemaCollection();
+ XmlSchema xmlSchema =xmlSchemaCollection.read(new FileReader("schema/sample.xsd"),null);
+ schemaCompiler.compile(xmlSchema);
+ } catch (Exception e) {
+ e.printStackTrace();
+ }
+
+
+</pre></div>
+ <p>When the mapping package is not specified it is derived from the
+targetnamespace of the first schema that is encountered.</p><p><a name="helper"></a></p></div><div class="subsection"><a name="Helper_mode"></a><h3>Helper mode</h3><p>Helper mode is a fairly new feature. In the helper mode, the beans are
+plain Java beans and all the deserialization/serialization code is moved to a
+helper class. For example, the simple schema mentioned in the ADB-howto
+document will yield four classes for the two that has been previously seen.</p><ol>
+ <li>MyElement.java</li>
+ <li>MyElementHelper.java</li>
+ <li>SOAPStruct.java</li>
+ <li>SOAPStructHelper.java</li>
+</ol><p>The helpers basically contain all the code that went into the ADBBeans.
+Hence the beans in the helper mode are pretty much readable than the rest.
+Also note that the helper mode is available only if you are in the unpacked
+mode. The code generator by default does not expand the classes.</p><p>Helper mode can be switched on by using the setHelperMode method
+in CompilerOptions : </p>
+ <div class="source"><pre>
+
+</pre></div>
+ <p><a name="more"></a></p></div><div class="subsection"><a name="More_Stuff_on_ADB_"></a><h3>More Stuff on ADB?</h3><ul>
+ <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></div></div><div class="section"></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/adb/adb-codegen-integration.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/adb/adb-codegen-integration.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/adb/adb-codegen-integration.html (added)
+++ webservices/axis2/site/1_2/adb/adb-codegen-integration.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,70 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - ADB Integration With Axis2</title><style type="text/css" media="all">
+ @import url("../../style/maven-base.css");
+
+ @import url("../../style/maven-theme.css");</style><link rel="stylesheet" href="../../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../../download.cgi">Releases</a></li><li class="none"><a href="../../modules/index.html">Modules</a></li><li class="none"><a href="../../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../../1_2/pojoguide.html">POJO Guide</a></li><li class="none"
><a href="../../1_2/spring.html">Spring Guide</a></li><li class="none"><a href="../../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../../faq.html">FAQ</a></li><li class="none"><a href="../../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../
../refLib.html">Reference Library</a></li><li class="none"><a href="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../../overview.html">Overview</a></li><li class="none"><a href="../../svn.html">Checkout the Source</a></li><li class="none"><a href="../../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../../team-list.html">Project Team</a></li><li class="none"><a href="../../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><l
i class="none"><a href="../../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="ADB_Integration_With_Axis2"></a><h2>ADB Integration With Axis2</h2><p>This document will assist you to write an extension using the
+integrator in order to integrate ADB with Axis2.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><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></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><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
+(<strong>org.apache.axis2.wsdl.codegen.extension.SimpleDBExtension</strong>)
+and can be found in the extensions list of the
+codegen-config.properties file.</p><p><a name="select_modes" id="select_modes"></a></p></div><div class="subsection"><a name="Selection_of_Generation_Modes_for_ADB"></a><h3>Selection of Generation Modes for ADB</h3><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 <a href="adb-howto.html" class="newWindow" title="New Window" target="_blank">ADB-How to document</a> for the
+different generation modes and their descriptions.</p><table class="bodyTable"><tbody>
+<tr class="a"><td><strong>User parameters</strong></td><td><strong>Selected code generation parameters</strong></td></tr>
+<tr class="b"><td>None (no other parameter than the mandatory ones)</td><td>wrapClasses=false,writeClasses=false</td></tr>
+<tr class="a"><td>-ss (server side)</td><td>wrapClasses=false,writeClasses=true</td></tr>
+<tr class="b"><td>-u (unwrap classes)</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 in the command line (prefixed with
+-E)</p><table class="bodyTable"><tbody>
+<tr class="a"><td><strong>Parameter Name</strong></td><td><strong>Allowed values</strong></td><td><strong>Description</strong></td></tr>
+<tr class="b"><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 class="a"><td>w</td><td>true, false</td><td>Sets the packing flag. if true the classes will be packed.</td></tr>
+</tbody></table><p>Note that these parameters have no relevant long names and MUST
+be prefixed with a -E to be processed by the code generator. For
+example</p>
+ <div class="source"><pre>
+WSDL2Java .... -Er true
+
+</pre></div>
+ <p><a name="remember" id="remember"></a></p></div><div class="subsection"><a name="Things_to_Remember"></a><h3>Things to Remember</h3><ol>
+<li>SimpleDBExtension is made to process requests only when the
+databinding framework is specified as ADB (using the switch -d adb
+). In the most recent release, the default has been set as ADB and
+hence if the -d option is missing then the databinding framework
+will be ADB.</li>
+</ol></div></div><div class="section"></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/adb/adb-howto.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/adb/adb-howto.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/adb/adb-howto.html (added)
+++ webservices/axis2/site/1_2/adb/adb-howto.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,348 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - ADB - Howto</title><style type="text/css" media="all">
+ @import url("../../style/maven-base.css");
+
+ @import url("../../style/maven-theme.css");</style><link rel="stylesheet" href="../../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../../download.cgi">Releases</a></li><li class="none"><a href="../../modules/index.html">Modules</a></li><li class="none"><a href="../../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../../1_2/pojoguide.html">POJO Guide</a></li><li class="none"
><a href="../../1_2/spring.html">Spring Guide</a></li><li class="none"><a href="../../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../../faq.html">FAQ</a></li><li class="none"><a href="../../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../
../refLib.html">Reference Library</a></li><li class="none"><a href="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../../overview.html">Overview</a></li><li class="none"><a href="../../svn.html">Checkout the Source</a></li><li class="none"><a href="../../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../../team-list.html">Project Team</a></li><li class="none"><a href="../../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><l
i class="none"><a href="../../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_Databinding_Framework"></a><h2>Axis2 Databinding Framework</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 is presented under the following topics.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><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><p><a name="intro" id="intro"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><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><p><a name="archi" id="archi"></a></p></div><div class="subsection"><a name="Architectural_Overview"></a><h3>Architectural Overview</h3><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"></img></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><p><a name="code_depend" id="code_depend"></a></p></div><div class="subsection"><a name="Code_and_Dependencies"></a><h3>Code and Dependencies</h3><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>ADBBeanTemplate.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 Axis2 adb-codegen module. This will generate the
+<strong>axis2-adb-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 and the kernal module. Hence to compile and work with the generated
+classes the <strong>axis2-adb-{$version}.jar</strong> and <strong>axis2-kernal-{$version}.jar</strong> needs to be
+in the classpath apart from other dependancies like the StAX,
+Axiom,Commons-logging and javax.activation.</p><p><a name="code_gen" id="code_gen"></a></p></div><div class="subsection"><a name="Invoking_the_ADB_Code_Generator"></a><h3>Invoking the ADB Code Generator</h3><p><a name="schema_compiler"></a></p></div><div class="subsection"><a name="As_a_Standalone_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><p><a name="api" id="api"></a></p></div><div class="subsection"><a name="Through_the_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><p><a name="gen_modes" id="gen_modes"></a></p></div><div class="subsection"><a name="Generation_Modes"></a><h3>Generation Modes</h3><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 class="bodyTable"><tbody>
+<tr class="b"><td><strong>Field Name in Options</strong></td><td><strong>Description</strong></td></tr>
+<tr class="a"><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="b"><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="a"><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="b"><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 class="a"><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><p><a name="deep" id="deep"></a></p></div><div class="subsection"><a name="Deep_into_Generated_Code"></a><h3>Deep into Generated Code</h3><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>
+ <div class="source"><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 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 serializer 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 org.apache.axiom.om.OMElement getOMElement(
+ final javax.xml.namespace.QName parentQName,
+ final org.apache.axiom.om.OMFactory factory){
+</pre>
+<p>This method returns an OMElement representing the ADB bean object.</p>
+<ol>
+<li>There is an annonymous ADBDataSource class has implemented, in side the getOMElement method.
+This annonymous class implements the serialize method where the serializing logic is written,
+for that pirticular bean class. Fianlly an OMSourcedElementImpl object with the
+above annonymous class type object as the data source, is
+returned.
+</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><p><a name="example" id="example"></a></p></div><div class="subsection"><a name="An_Example_"></a><h3>An Example!</h3><p>Consider the following XML fragment</p>
+ <div class="source"><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
+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>
+ <div class="source"><pre>
+XMLStreamReader reader = XMLInputFactory.newInstance().
+ createXMLStreamReader(
+ new ByteArrayInputStream(xmlString.getBytes()));
+MyElement elt = MyElement.Factory.parse(reader);
+
+</pre></div>
+ <p>
+Optionally above xml fragment can be reproduced with the following
+code fragment
+</p><p>
+<pre>
+OMElement omElement = myElement.getOMElement
+ (MyElement.MY_QNAME, OMAbstractFactory.getSOAP12Factory());
+String xmlString = omElement.toStringWithConsume();
+</pre>
+</p><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>
+ <div class="source"><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><p><a name="limitation" id="limitation"></a></p></div><div class="subsection"><a name="Known_Limitations"></a><h3>Known Limitations</h3><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.</li>
+</ol><p><a name="more" id="more"></a></p></div><div class="subsection"><a name="Want_to_Learn_More_"></a><h3>Want to Learn More?</h3><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></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/adb/adb-tweaking.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/adb/adb-tweaking.html?view=auto&rev=533081
==============================================================================
--- webservices/axis2/site/1_2/adb/adb-tweaking.html (added)
+++ webservices/axis2/site/1_2/adb/adb-tweaking.html Fri Apr 27 05:39:33 2007
@@ -0,0 +1,109 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/Java - ADB Tweaking Guide</title><style type="text/css" media="all">
+ @import url("../../style/maven-base.css");
+
+ @import url("../../style/maven-theme.css");</style><link rel="stylesheet" href="../../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis2" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 27 April 2007
+ | Doc for 1.2</div><div class="xright">
+
+ <a href="../../index.html">Axis2/Java</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org/axis2/c" class="externalLink" title="External Link">Axis2/C</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://ws.apache.org" class="externalLink" title="External Link">Apache WS</a>
+
+
+
+ <span class="separator">|</span>
+
+
+ <a href="http://www.apache.org" class="externalLink" title="External Link">Apache </a>
+ </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_Java"><h5>Axis2/Java</h5><ul><li class="none"><a href="../../index.html">Home</a></li></ul></div><div id="menuDownloads"><h5>Downloads</h5><ul><li class="none"><a href="../../download.cgi">Releases</a></li><li class="none"><a href="../../modules/index.html">Modules</a></li><li class="none"><a href="../../tools/index.html">Tools</a></li></ul></div><div id="menuDocumentation"><h5>Documentation</h5><ul><li class="expanded"><a href="../../1_2/contents.html">Version 1.2</a><ul><li class="none"><a href="../../1_2/toc.html">Table of Contents</a></li><li class="none"><a href="../../1_2/installationguide.html">Installation Guide</a></li><li class="none"><a href="../../1_2/quickstartguide.html">QuickStart Guide</a></li><li class="none"><a href="../../1_2/userguide.html">User Guide</a></li><li class="none"><a href="../../1_2/pojoguide.html">POJO Guide</a></li><li class="none"
><a href="../../1_2/spring.html">Spring Guide</a></li><li class="none"><a href="../../1_2/webadminguide.html">Web Administrator's Guide</a></li><li class="none"><a href="../../1_2/migration.html">Migration Guide (from Axis1)</a></li></ul></li><li class="none"><a href="../../1_1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_1/index.html">Version 1.0</a></li><li class="none"><a href="../../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../../0_93/index.html">Version 0.93</a></li></ul></div><div id="menuResources"><h5>Resources</h5><ul><li class="none"><a href="../../faq.html">FAQ</a></li><li class="none"><a href="../../articles.html">Articles</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="../
../refLib.html">Reference Library</a></li><li class="none"><a href="http://ws.apache.org/axis2/1_2/api/index.html" class="externalLink" title="External Link">Online Java Docs</a></li></ul></div><div id="menuGet_Involved"><h5>Get Involved</h5><ul><li class="none"><a href="../../overview.html">Overview</a></li><li class="none"><a href="../../svn.html">Checkout the Source</a></li><li class="none"><a href="../../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../../siteHowTo.html">Build the Site</a></li></ul></div><div id="menuProject_Information"><h5>Project Information</h5><ul><li class="none"><a href="../../team-list.html">Project Team</a></li><li class="none"><a href="../../issue-tracking.html">Issue Tracking</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><l
i class="none"><a href="../../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="ADB_Tweaking_Guide"></a><h2>ADB Tweaking Guide</h2><p>This document explains the mechanisms available to extend ADB and
+possibly adopt it to compile schemas to support other
+languages.</p><div class="subsection"><a name="Content"></a><h3>Content</h3><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><p><a name="intro" id="intro"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>ADB is written with future extensions in mind, with a clear and
+flexible 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><p><a name="config" id="config"></a></p></div><div class="subsection"><a name="Know_the_Configuration"></a><h3>Know the Configuration</h3><p>The configuration for the ADB framework is in the
+<strong>schema-compile.properties</strong> file found in the
+<strong>org.apache.axis2.schema</strong> package. This
+properties file has the following important properties</p><ul>
+<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>
+interface. 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
+BeanWriter author is free to use any mechanism to write the classes
+but the default mechanism is to use a xsl template. This property
+may be left blank if the BeanWriter implementation does not require
+a template.</p>
+</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.TypeMap</strong> interface. The
+default typemap implementation encapsulates a hashmap with type
+QName to Class name string mapping.</p>
+</li>
+</ul><p><a name="first_tweak" id="first_tweak"></a></p></div><div class="subsection"><a name="The_First_Tweak_-_Generate_Plain_Java_Beans"></a><h3>The First Tweak - Generate Plain Java Beans</h3><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 in fact be done by 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/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><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 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><p><a name="advanced_tweak" id="advanced_tweak"></a></p></div><div class="subsection"><a name="A_More_Advanced_Tweak_-_Generate_Code_for_Another_Language"></a><h3>A More Advanced Tweak - Generate Code for Another Language</h3><p>To generate code for another language, there are two main
+components to be written.</p><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. 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>
+<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 sufficient and only the type names would need to change to
+support another language.</p>
+</li>
+</ul><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 free experiment with it and modify the schema
+compiler accordingly to their needs. Also note that the intention
+of this section is <em>not</em> to be a step by step guide to
+custom code generation. Anyone who wish to do so would need to dig
+into the code and get their hands dirty!</p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/1_2/adb/images/ADB.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/site/1_2/adb/images/ADB.jpg?view=auto&rev=533081
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/site/1_2/adb/images/ADB.jpg
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org