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 di...@apache.org on 2007/07/14 06:37:36 UTC
svn commit: r556222 [3/22] - in /webservices/axis2/trunk/java/xdocs: ./
@axis2_version_dir@/ @axis2_version_dir@/adb/ @axis2_version_dir@/jibx/
@axis2_version_dir@/src/ download/0_9/ download/0_91/ download/0_92/
download/0_93/ download/0_94/ download/...
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/WS_policy.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/WS_policy.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/WS_policy.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.xml Fri Jul 13 21:37:26 2007
@@ -1,205 +1,193 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
- -->
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
- <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
- <title>WS Policy Support in Axis2</title>
- <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
- <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
- media="all">
-</head>
-
-<body lang="en">
-<h1 align="center">Web Services Policy Support In Apache Axis2</h1>
-
-<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">Axis2 site</a>.) Kindly
-prefix every email subject with [Axis2].</p>
-
-<h2>Content</h2>
-<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>
-<a name="what"></a>
-
-<h2>What is Web Services (WS) Policy?</h2>
-
-<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>
-<a name="client"></a>
-
-<h2>Client Side WS-Policy Support</h2>
-
-<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>
-
-<h3>How it works:</h3>
-
-<h4>Phase 1: At PolicyEvaluator</h4>
-
-<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>
-<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy>
- <a:Foo/> <a:Foo/> <b:Foo/>
- <b:Bar/> => </wsp:Policy>
- </wsp:Policy>
- </wsp:Policy></pre>
-
-<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>
-
-<h4>Phase 2: At AxisServiceBasedMultiLanguageClientEmitter</h4>
-
-<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>
-
-<h4>Phase 3: Runtime</h4>
-
-<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>
-<a name="server"></a>
-
-<h2>Server Side WS-Policy Support</h2>
-
-<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>
-<a name="resources"></a>
-
-<h2>Resources</h2>
-<ul>
- <li>Apache Neethi (WS Policy Implementation) official site- <a
- href="http://ws.apache.org/commons/neethi/index.html"
- 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"
- target="_blank">Web services Policy - Why, What & How</a></li>
- <li><a
- href="http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
- target="_blank">WS-commons/policy SVN</a></li>
- <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf"
- target="_blank">Web Services Policy Framework (WS-Policy)</a></li>
-</ul>
-</body>
-</html>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<meta http-equiv="content-type" content=
+"text/html; charset=us-ascii" />
+<title>WS Policy Support in Axis2</title>
+<meta name="generator" content=
+"amaya 9.2.1, see http://www.w3.org/Amaya/" />
+<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+media="all" />
+</head>
+<body lang="en" xml:lang="en">
+<h1 align="center">Web Services Policy Support In Apache Axis2</h1>
+<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">Axis2 site</a>.)
+Kindly prefix every email subject with [Axis2].</p>
+<h2>Content</h2>
+<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>
+<a name="what" id="what"></a>
+<h2>What is Web Services (WS) Policy?</h2>
+<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>
+<a name="client" id="client"></a>
+<h2>Client Side WS-Policy Support</h2>
+<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>
+<h3>How it works:</h3>
+<h4>Phase 1: At PolicyEvaluator</h4>
+<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>
+<pre>
+ <wsp:Policy> <wsp:Policy> <wsp:Policy>
+ <a:Foo/> <a:Foo/> <b:Foo/>
+ <b:Bar/> => </wsp:Policy>
+ </wsp:Policy>
+ </wsp:Policy>
+</pre>
+<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>
+<h4>Phase 2: At AxisServiceBasedMultiLanguageClientEmitter</h4>
+<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>
+<h4>Phase 3: Runtime</h4>
+<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>
+<a name="server" id="server"></a>
+<h2>Server Side WS-Policy Support</h2>
+<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>
+<a name="resources" id="resources"></a>
+<h2>Resources</h2>
+<ul>
+<li>Apache Neethi (WS Policy Implementation) official site-
+<a href="http://ws.apache.org/commons/neethi/index.html" 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"
+target="_blank">Web services Policy - Why, What & How</a></li>
+<li><a href=
+"http://svn.apache.org/viewcvs.cgi/webservices/commons/trunk/modules/neethi/"
+target="_blank">WS-commons/policy SVN</a></li>
+<li><a href=
+"http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf" target=
+"_blank">Web Services Policy Framework (WS-Policy)</a></li>
+</ul>
+</body>
+</html>
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-advanced.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-advanced.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-advanced.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.xml Fri Jul 13 21:37:26 2007
@@ -1,140 +1,143 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
- -->
-<html>
-<head>
- <meta http-equiv="content-type" content="text/html; charset=UTF-8">
- <title>Advanced Axis2 Databinding Framework Features</title>
- <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
-</head>
-
-<body lang="en">
-<h1>Advanced Axis2 Databinding Framework Features</h1>
-
-<p>The aim of this section is provide an insight into the newly added
-advanced features of the Axis2 Databinding (ADB) Framework.</p>
-
-<h2>Content</h2>
-<ul>
- <li><a href="#typeSupport">xsi:type Support</a></li>
- <li><a href="#helper">Helper Mode</a></li>
- <li><a href="#more">Additional ADB Topics</a></li>
-</ul>
-<a name="typeSupport"></a>
-<h2>xsi:type Support</h2>
-
-<p>This is implemented by adding a extension mapping class. The code that
-calls the extension mapper is generated inside the Factory.parse method of
-the beans and gets activated when the xsi:type attribute is present. The
-following code fragment shows what the generated type mapper looks like : </p>
-<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>
-
-<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 currently being parsed.</p>
-
-<p>The following code fragment shows how the ADB deserialize method calls the
-mapper class: </p>
-<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>
-
-<p>This makes xsi:type based parsing possible and results
-in proper xsi:type based serializations at runtime.</p>
-
-<p>By default, the mapping package is derived from the targetnamespace of the
-first schema that is encountered. The package name can also be explicitly set
-by a CompilerOption:</p>
-
-<pre>
- CompilerOptions compilerOptions = new CompilerOptions();
- compilerOptions.setWriteOutput(true);
- <strong>compilerOptions.setMapperClassPackage("com.test");</strong>
- 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>
-
-<a name="helper"></a>
-<h2>Helper mode</h2>
-
-<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 instead of the two previously generated:</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 serialization code that otherwise
-would go into the ADBBeans. Hence the beans in the helper mode are much
-more simplified. Also note that the helper mode is available only if you
-are in 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>
-<pre><strong>compilerOptions.setHelperMode(true);</strong></pre>
-
-<a name="more"></a>
-<h2>Additional ADB Topics</h2>
-<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>
-<hr>
-</body>
-</html>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<meta http-equiv="content-type" content=
+"text/html; charset=us-ascii" />
+<title>Advanced Axis2 Databinding Framework Features</title>
+<link href="../../css/axis-docs.css" rel="stylesheet" type=
+"text/css" media="all" />
+</head>
+<body lang="en" xml:lang="en">
+<h1>Advanced Axis2 Databinding Framework Features</h1>
+<p>The aim of this section is provide an insight into the newly
+added advanced features of the Axis2 Databinding (ADB)
+Framework.</p>
+<h2>Content</h2>
+<ul>
+<li><a href="#typeSupport">xsi:type Support</a></li>
+<li><a href="#helper">Helper Mode</a></li>
+<li><a href="#more">Additional ADB Topics</a></li>
+</ul>
+<a name="typeSupport" id="typeSupport"></a>
+<h2>xsi:type Support</h2>
+<p>This is implemented by adding a extension mapping class. The
+code that calls the extension mapper is generated inside the
+Factory.parse method of the beans and gets activated when the
+xsi:type attribute is present. The following code fragment shows
+what the generated type mapper looks like :</p>
+<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>
+<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 currently
+being parsed.</p>
+<p>The following code fragment shows how the ADB deserialize method
+calls the mapper class:</p>
+<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>
+<p>This makes xsi:type based parsing possible and results in proper
+xsi:type based serializations at runtime.</p>
+<p>By default, the mapping package is derived from the
+targetnamespace of the first schema that is encountered. The
+package name can also be explicitly set by a CompilerOption:</p>
+<pre>
+
+ CompilerOptions compilerOptions = new CompilerOptions();
+ compilerOptions.setWriteOutput(true);
+ <strong>compilerOptions.setMapperClassPackage("com.test");</strong>
+ 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>
+<a name="helper" id="helper"></a>
+<h2>Helper mode</h2>
+<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 instead of the two previously generated:</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 serialization code that
+otherwise would go into the ADBBeans. Hence the beans in the helper
+mode are much more simplified. Also note that the helper mode is
+available only if you are in 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>
+<pre>
+<strong>compilerOptions.setHelperMode(true);</strong>
+</pre>
+<a name="more" id="more"></a>
+<h2>Additional ADB Topics</h2>
+<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>
+<hr />
+</body>
+</html>
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-codegen-integration.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-codegen-integration.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-codegen-integration.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.xml Fri Jul 13 21:37:26 2007
@@ -20,8 +20,11 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>ADB Integration With Axis2</title>
- <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<title>ADB Integration With Axis2</title>
+<link href="../../css/axis-docs.css" rel="stylesheet" type=
+"text/css" media="all" />
</head>
<body>
<h1>ADB Integration With Axis2</h1>
@@ -69,7 +72,7 @@
</tr>
</tbody>
</table>
-<p>The following parameters (prefixed with -E) can be used to
+<p>The following parameters (prefixed with -E) can be used to
override these settings manually:</p>
<table border="1">
<tbody>
@@ -87,13 +90,14 @@
<tr>
<td>w</td>
<td>true, false</td>
-<td>Sets the wrapping flag. if true the classes will be wrapped.</td>
+<td>Sets the wrapping flag. if true the classes will be
+wrapped.</td>
</tr>
</tbody>
</table>
-<p>Note that these parameters have no corresponding long names and MUST
-be prefixed with a -E to be processed by the code generator. For
-example:</p>
+<p>Note that these parameters have no corresponding long names and
+MUST be prefixed with a -E to be processed by the code generator.
+For example:</p>
<pre>
WSDL2Java .... -Er true
</pre>
@@ -102,7 +106,7 @@
<ol>
<li>SimpleDBExtension is for the ADB databinding framework only and
will process requests only when this framework is specified during
-code generation (using the switch -d adb). In the most recent
+code generation (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>
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-howto.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-howto.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-howto.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.xml Fri Jul 13 21:37:26 2007
@@ -1,425 +1,427 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one
- ~ or more contributor license agreements. See the NOTICE file
- ~ distributed with this work for additional information
- ~ regarding copyright ownership. The ASF licenses this file
- ~ to you under the Apache License, Version 2.0 (the
- ~ "License"); you may not use this file except in compliance
- ~ with the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing,
- ~ software distributed under the License is distributed on an
- ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~ KIND, either express or implied. See the License for the
- ~ specific language governing permissions and limitations
- ~ under the License.
- -->
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
- <meta http-equiv="content-type" content="text/html; charset=us-ascii" />
- <title>ADB - Howto</title>
- <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
-</head>
-<body lang="en" xml:lang="en">
-<h1>Axis2 Databinding Framework</h1>
-<p>This document aims to provide an architectural overview of the
-Axis2 Databinding Framework (referred to as ADB from here onwards)
-and be a guide to anyone who wants to use and modify ADB. The
-information is presented under the following topics.</p>
-<h2>Content</h2>
-<ul>
-<li><a href="#intro">Introduction</a></li>
-<li><a href="#archi">Architectural Overview</a></li>
-<li><a href="#code_depend">Code and Dependencies</a></li>
-<li><a href="#code_gen">Invoking the ADB Code Generator</a>
-<ul>
-<li><a href="#schema_compiler">As a Stand-alone Schema
-Compiler</a></li>
-<li><a href="#api">Through the API</a></li>
-</ul>
-</li>
-<li><a href="#gen_modes">Generation Modes</a></li>
-<li><a href="#deep">Deep into Generated Code</a>
-<ul>
-<li><a href="#example">An Example!</a></li>
-</ul>
-</li>
-<li><a href="#limitation">Known Limitations</a></li>
-<li><a href="#more">Want to Learn More?</a></li>
-</ul>
-
-<a name="intro" id="intro"></a>
-<h2>Introduction</h2>
-<p>The objective of the Axis2 Databinding framework is to provide a
-lightweight and simple schema compiler/Java bean generator for
-Axis2. By no means is it intended to be a fully functional schema compiler
-like XMLBeans. Note that ADB is written in a fashion that allows it
-to be used as a stand-alone schema compiler and also to be extended
-to generate code for other languages.</p>
-<a name="archi" id="archi"></a>
-<h2>Architectural Overview</h2>
-<p>ADB is built on a modular architecture that allows it to utilize
-a pre-configured writer depending on the configuration. The 'big
-block diagram' for the code generator architecture is depicted
-below.</p>
-<p><img src="images/ADB.jpg" alt="ADB architecture" /></p>
-<p>ADB utilizes the WS-Commons <a href="http://ws.apache.org/commons/XmlSchema/index.html">
-XmlSchema library</a> 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 use for the QNames that it
-encounters. This type mapper is also part of the configuration and
-the users can override the default type mapper by overriding the
-property setting.</p>
-<a name="code_depend" id="code_depend"></a>
-<h2>Code and Dependencies</h2>
-<p>As explained in the previous section, the schema compiler
-depends on the WS-Commons XmlSchema library. The XSLT
-transformations are dependent on the JVM's DOM implementation
-(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>The following are the important classes and files of ADB:</p>
-<ol>
-<li><strong>SchemaCompiler</strong> - The work horse that really
-compiles the schema into classes.</li>
-<li><strong>BeanWriter</strong> - BeanWriters handle the the actual
-rendering of the classes. BeanWriter is the interface that
-writers need to implement in order to be used by the SchemaCompiler. </li>
-<li><strong>JavaBeanWriter</strong> - The default implementation of
-the BeanWriter interface.</li>
-<li><strong>TypeMap</strong> - represents the interface that the
-schema compiler uses to find class names for a given QName.</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 dependencies 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 in addition to other dependencies such as StAX,
-Axiom, Commons-logging and javax.activation.</p>
-<a name="code_gen" id="code_gen"></a>
-<h2>Invoking the ADB Code Generator</h2>
-<a name="schema_compiler"></a>
-<h3>As a Standalone Schema Compiler</h3>
-<p>ADB comes with a XSD2Java code generator that allows the schemas to
-be compiled just by giving the schema file reference. This main
-class is presently rather primitive and does not provide much control
-over the code generation process. This is bound to improve in the
-near future.</p>
-<p>XSD2Java 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 code generator presently has no validations built into it, the compiler
-is likely to show various error messages if these
-parameters are not supplied properly.</p>
-<a name="api" id="api"></a>
-<h3>Through the API</h3>
-<p>This is the only way to harness the full potential of the schema
-compiler. The current Axis2 integration of ADB happens through this
-API. The most important classes and methods of the Schema compiler
-are as follows.</p>
-<ul>
-<li><strong>SchemaCompiler - Constructor</strong>
-<p>The constructor of the schema compiler expects a CompilerOptions
-object. This compilerOptions object is more of a holder for the
-parameters that are passed to the SchemaCompiler. The only
-mandatory parameter in the CompilerOptions is the output
-directory.</p>
-</li>
-<li><strong>SchemaCompiler - Compile(XMLSchema schema)</strong>
-<p>The compile method to call for a single schema. The expected
-object is a XMLSchema which is part of the XmlSchema library.</p>
-</li>
-<li><strong>SchemaCompiler - Compile(List schemaList)</strong>
-<p>Similar to the previous method but accepts a list of schemas
-instead of one.</p>
-</li>
-</ul>
-<p>For a comprehensive code sample in invoking the schema compiler
-through the API, the following classes would be helpful. One would
-also need an understanding of the generation modes of the ADB
-schema compiler when using it through the API. Hence the following
-section includes a brief description of the generation modes.</p>
-<ul>
-<li><strong>org.apache.axis2.schema.XSD2Java</strong></li>
-<li><strong>org.apache.axis2.schema.ExtensionUtility</strong></li>
-</ul>
-<a name="gen_modes" id="gen_modes"></a>
-<h2>Generation Modes</h2>
-<p>ADB extension provides several generation modes for the data
-bound classes.</p>
-<ol>
-<li><strong>Integrated Mode</strong>
-<p>In this mode the classes are generated as inner classes of the
-stub, message receiver or the interface. The ADB framework does
-not actually write the classes but instead provides a map of DOM
-document objects that contains the model for the databinding classes.
-The Axis2 codegen engine in turn parses these documents within
-its own XSLT parser to create the necessary classes.
-Implementers are free to use these models differently for their own particular needs.
-</p>
-<p>Integrated mode is intended to be used by 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 code generator 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 table lists the options and the effects of using
-them.</p>
-<table border="1" summary="Options and descriptions">
-<tbody>
-<tr>
-<td><strong>Field Name in Options</strong></td>
-<td><strong>Description</strong></td>
-</tr>
-<tr>
-<td>writeOutput</td>
-<td>This determines whether to write the output or not. If the flag
-is on then the classes will be written by ADB. The default is
-off.</td>
-</tr>
-<tr>
-<td>wrapClasses</td>
-<td>This determines whether to wrap the generated classes. If the
-flag is on then a single class (with adb added to the end of the
-specified package) will be generated. The default is off.</td>
-</tr>
-<tr>
-<td>mapperClassPackage</td>
-<td>The package name for the mapper class. Please see the advanced
-section for details of the mapper class.</td>
-</tr>
-<tr>
-<td>helperMode</td>
-<td>The switch that determines whether to switch to helper mode or
-not. Please see the advanced section for details of helper
-mode.</td>
-</tr>
-<tr>
-<td>ns2PackageMap</td>
-<td>A map that stores the namespace name against the package name
-These details are used to override the default packages</td>
-</tr>
-</tbody>
-</table>
-<a name="deep" id="deep"></a>
-<h2>Deep into Generated Code</h2>
-<p>When the schema compiler is invoked (one-way or another) it
-generates code depending on the following rules:</p>
-<ol>
-<li>All named complex types become bean classes. Any attribute or
-element encapsulated in this complex type will become a field in
-the generated class. Note that the support for constructs other
-than xsd:sequence and xsd:all is not yet implemented.</li>
-<li>All top level elements become classes. This is a rather
-obvious feature since unless classes are generated for the top
-level elements the handling of elements becomes 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 schema:</p>
-<pre>
-<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
-xmlns:tns="http://soapinterop.org/types" targetNamespace="http://soapinterop.org/types"
-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>
-<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 will generate the following two classes in the
-designated package, which in this case would be
-<strong>org.soapinterop.types</strong>. The package name 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 creating 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 its 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 parameter for 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>Inside the getOMElement method an anonymous ADBDataSource class is created.
-This anonymous class implements a serialize() method where the serialization logic for that
-particular bean class is handled. Finally an OMSourcedElementImpl object with the
-above anonymous 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> nested class within the relevant top
-level class. Hence one will have to get the static Factory instance
-before calling the parse method.</p>
-</li>
-</ul>
-<a name="example" id="example"></a>
-<h3>An Example!</h3>
-<p>Consider the following XML fragment</p>
-<pre>
-<myElement xmlns="http://soapinterop.org/types">
- <varInt>5</varInt>
- <varString>Hello</varString>
- <varFloat>3.3</varFloat>
-</myElement>
-</pre>
-<p>Enthusiastic readers might already have figured out that this
-XML fragment complies with the Schema mentioned above. The following
-code snippet shows how to build a populated instance of MyElement
-with the XML above:</p>
-<pre>
-XMLStreamReader reader = XMLInputFactory.newInstance().
- createXMLStreamReader(
- new ByteArrayInputStream(xmlString.getBytes()));
-MyElement elt = MyElement.Factory.parse(reader);
-</pre>
-<p>
-Optionally, the above xml fragment can be reproduced with the following
-code fragment:
-<P>
-<pre>
-OMElement omElement = myElement.getOMElement
- (MyElement.MY_QNAME, OMAbstractFactory.getSOAP12Factory());
-String xmlString = omElement.toStringWithConsume();
-</pre>
-<p>Although this example takes on the tedious effort of creating a
-reader out of a String, inside the Axis2 environment an
-XMLStreamReader can be directly obtained from the OMElement! Hence, the
-parse method becomes a huge advantage for hassle free object
-creation.</p>
-<p>Similarly the reader obtained from the object can also be
-utilized as needed. The following code fragment shows how to
-utilize the getPullParser method to create an OMElement :</p>
-<pre>
-XMLStreamReader reader = elt.getPullParser(null);
-OMElement omElt = new StAXOMBuilder(reader).getDocumentElement();
-</pre>
-<p>That's all to it! If you are interested in learning more on ADB
-the following documents may also be helpful. However, be sure to
-check the limitations section that follows if you are planning to
-use ADB for something serious.</p>
-<a name="limitation" id="limitation"></a>
-<h2>Known Limitations</h2>
-<p>ADB is meant to be a 'Simple' databinding framework and was not meant to compile all types of schemas.
-The following limitations are the most highlighted.</p>
-<ol>
-<li>Complex Type Extensions and Restrictions.</li>
-</ol>
-<a name="more" id="more"></a>
-<h2>Want to Learn More?</h2>
-<ul>
-<li><a href="adb-advanced.html">Advanced features of the ADB code
-generator</a> - explains xsi:type based deserialization and helper
-mode</li>
-<li><a href="adb-tweaking.html">Tweaking the ADB Code
-Generator</a> - explains available mechanisms to extend ADB and
-possibly adopt it to compile schemas to support other
-languages.</li>
-<li><a href="adb-codegen-integration.html">ADB and Axis2
-Integration</a> - explains how the ADB schema compiler was attached
-to the Axis2 framework</li>
-</ul>
-</body>
-</html>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<meta http-equiv="content-type" content=
+"text/html; charset=us-ascii" />
+<title>ADB - Howto</title>
+<link href="../../css/axis-docs.css" rel="stylesheet" type=
+"text/css" media="all" />
+</head>
+<body lang="en" xml:lang="en">
+<h1>Axis2 Databinding Framework</h1>
+<p>This document aims to provide an architectural overview of the
+Axis2 Databinding Framework (referred to as ADB from here onwards)
+and be a guide to anyone who wants to use and modify ADB. The
+information is presented under the following topics.</p>
+<h2>Content</h2>
+<ul>
+<li><a href="#intro">Introduction</a></li>
+<li><a href="#archi">Architectural Overview</a></li>
+<li><a href="#code_depend">Code and Dependencies</a></li>
+<li><a href="#code_gen">Invoking the ADB Code Generator</a>
+<ul>
+<li><a href="#schema_compiler">As a Stand-alone Schema
+Compiler</a></li>
+<li><a href="#api">Through the API</a></li>
+</ul>
+</li>
+<li><a href="#gen_modes">Generation Modes</a></li>
+<li><a href="#deep">Deep into Generated Code</a>
+<ul>
+<li><a href="#example">An Example!</a></li>
+</ul>
+</li>
+<li><a href="#limitation">Known Limitations</a></li>
+<li><a href="#more">Want to Learn More?</a></li>
+</ul>
+<a name="intro" id="intro"></a>
+<h2>Introduction</h2>
+<p>The objective of the Axis2 Databinding framework is to provide a
+lightweight and simple schema compiler/Java bean generator for
+Axis2. By no means is it intended to be a fully functional schema
+compiler like XMLBeans. Note that ADB is written in a fashion that
+allows it to be used as a stand-alone schema compiler and also to
+be extended to generate code for other languages.</p>
+<a name="archi" id="archi"></a>
+<h2>Architectural Overview</h2>
+<p>ADB is built on a modular architecture that allows it to utilize
+a pre-configured writer depending on the configuration. The 'big
+block diagram' for the code generator architecture is depicted
+below.</p>
+<p><img src="images/ADB.jpg" alt="ADB architecture" /></p>
+<p>ADB utilizes the WS-Commons <a href=
+"http://ws.apache.org/commons/XmlSchema/index.html">XmlSchema
+library</a> 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 use for
+the QNames that it encounters. This type mapper is also part of the
+configuration and the users can override the default type mapper by
+overriding the property setting.</p>
+<a name="code_depend" id="code_depend"></a>
+<h2>Code and Dependencies</h2>
+<p>As explained in the previous section, the schema compiler
+depends on the WS-Commons XmlSchema library. The XSLT
+transformations are dependent on the JVM's DOM implementation
+(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>The following are the important classes and files of ADB:</p>
+<ol>
+<li><strong>SchemaCompiler</strong> - The work horse that really
+compiles the schema into classes.</li>
+<li><strong>BeanWriter</strong> - BeanWriters handle the the actual
+rendering of the classes. BeanWriter is the interface that writers
+need to implement in order to be used by the SchemaCompiler.</li>
+<li><strong>JavaBeanWriter</strong> - The default implementation of
+the BeanWriter interface.</li>
+<li><strong>TypeMap</strong> - represents the interface that the
+schema compiler uses to find class names for a given QName.</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 dependencies 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 in addition to other dependencies such as StAX, Axiom,
+Commons-logging and javax.activation.</p>
+<a name="code_gen" id="code_gen"></a>
+<h2>Invoking the ADB Code Generator</h2>
+<a name="schema_compiler" id="schema_compiler"></a>
+<h3>As a Standalone Schema Compiler</h3>
+<p>ADB comes with a XSD2Java code generator that allows the schemas
+to be compiled just by giving the schema file reference. This main
+class is presently rather primitive and does not provide much
+control over the code generation process. This is bound to improve
+in the near future.</p>
+<p>XSD2Java 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 code generator presently has no validations built into
+it, the compiler is likely to show various error messages if these
+parameters are not supplied properly.</p>
+<a name="api" id="api"></a>
+<h3>Through the API</h3>
+<p>This is the only way to harness the full potential of the schema
+compiler. The current Axis2 integration of ADB happens through this
+API. The most important classes and methods of the Schema compiler
+are as follows.</p>
+<ul>
+<li><strong>SchemaCompiler - Constructor</strong>
+<p>The constructor of the schema compiler expects a CompilerOptions
+object. This compilerOptions object is more of a holder for the
+parameters that are passed to the SchemaCompiler. The only
+mandatory parameter in the CompilerOptions is the output
+directory.</p>
+</li>
+<li><strong>SchemaCompiler - Compile(XMLSchema schema)</strong>
+<p>The compile method to call for a single schema. The expected
+object is a XMLSchema which is part of the XmlSchema library.</p>
+</li>
+<li><strong>SchemaCompiler - Compile(List schemaList)</strong>
+<p>Similar to the previous method but accepts a list of schemas
+instead of one.</p>
+</li>
+</ul>
+<p>For a comprehensive code sample in invoking the schema compiler
+through the API, the following classes would be helpful. One would
+also need an understanding of the generation modes of the ADB
+schema compiler when using it through the API. Hence the following
+section includes a brief description of the generation modes.</p>
+<ul>
+<li><strong>org.apache.axis2.schema.XSD2Java</strong></li>
+<li><strong>org.apache.axis2.schema.ExtensionUtility</strong></li>
+</ul>
+<a name="gen_modes" id="gen_modes"></a>
+<h2>Generation Modes</h2>
+<p>ADB extension provides several generation modes for the data
+bound classes.</p>
+<ol>
+<li><strong>Integrated Mode</strong>
+<p>In this mode the classes are generated as inner classes of the
+stub, message receiver or the interface. The ADB framework does not
+actually write the classes but instead provides a map of DOM
+document objects that contains the model for the databinding
+classes. The Axis2 codegen engine in turn parses these documents
+within its own XSLT parser to create the necessary classes.
+Implementers are free to use these models differently for their own
+particular needs.</p>
+<p>Integrated mode is intended to be used by 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 code generator 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 table lists the options and the effects of using
+them.</p>
+<table border="1" summary="Options and descriptions">
+<tbody>
+<tr>
+<td><strong>Field Name in Options</strong></td>
+<td><strong>Description</strong></td>
+</tr>
+<tr>
+<td>writeOutput</td>
+<td>This determines whether to write the output or not. If the flag
+is on then the classes will be written by ADB. The default is
+off.</td>
+</tr>
+<tr>
+<td>wrapClasses</td>
+<td>This determines whether to wrap the generated classes. If the
+flag is on then a single class (with adb added to the end of the
+specified package) will be generated. The default is off.</td>
+</tr>
+<tr>
+<td>mapperClassPackage</td>
+<td>The package name for the mapper class. Please see the advanced
+section for details of the mapper class.</td>
+</tr>
+<tr>
+<td>helperMode</td>
+<td>The switch that determines whether to switch to helper mode or
+not. Please see the advanced section for details of helper
+mode.</td>
+</tr>
+<tr>
+<td>ns2PackageMap</td>
+<td>A map that stores the namespace name against the package name
+These details are used to override the default packages</td>
+</tr>
+</tbody>
+</table>
+<a name="deep" id="deep"></a>
+<h2>Deep into Generated Code</h2>
+<p>When the schema compiler is invoked (one-way or another) it
+generates code depending on the following rules:</p>
+<ol>
+<li>All named complex types become bean classes. Any attribute or
+element encapsulated in this complex type will become a field in
+the generated class. Note that the support for constructs other
+than xsd:sequence and xsd:all is not yet implemented.</li>
+<li>All top level elements become classes. This is a rather obvious
+feature since unless classes are generated for the top level
+elements the handling of elements becomes 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 schema:</p>
+<pre>
+<schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+xmlns:tns="http://soapinterop.org/types" targetNamespace="http://soapinterop.org/types"
+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>
+<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 will generate the following two classes in the
+designated package, which in this case would be
+<strong>org.soapinterop.types</strong>. The package name 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 creating 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 its 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 parameter for 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>Inside the getOMElement method an anonymous ADBDataSource class
+is created. This anonymous class implements a serialize() method
+where the serialization logic for that particular bean class is
+handled. Finally an OMSourcedElementImpl object with the above
+anonymous 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> nested class within the relevant top level
+class. Hence one will have to get the static Factory instance
+before calling the parse method.</p>
+</li>
+</ul>
+<a name="example" id="example"></a>
+<h3>An Example!</h3>
+<p>Consider the following XML fragment</p>
+<pre>
+<myElement xmlns="http://soapinterop.org/types">
+ <varInt>5</varInt>
+ <varString>Hello</varString>
+ <varFloat>3.3</varFloat>
+</myElement>
+</pre>
+<p>Enthusiastic readers might already have figured out that this
+XML fragment complies with the Schema mentioned above. The
+following code snippet shows how to build a populated instance of
+MyElement with the XML above:</p>
+<pre>
+XMLStreamReader reader = XMLInputFactory.newInstance().
+ createXMLStreamReader(
+ new ByteArrayInputStream(xmlString.getBytes()));
+MyElement elt = MyElement.Factory.parse(reader);
+</pre>
+<p>Optionally, the above xml fragment can be reproduced with the
+following code fragment:</p>
+<pre>
+OMElement omElement = myElement.getOMElement
+ (MyElement.MY_QNAME, OMAbstractFactory.getSOAP12Factory());
+String xmlString = omElement.toStringWithConsume();
+</pre>
+<p>Although this example takes on the tedious effort of creating a
+reader out of a String, inside the Axis2 environment an
+XMLStreamReader can be directly obtained from the OMElement! Hence,
+the parse method becomes a huge advantage for hassle free object
+creation.</p>
+<p>Similarly the reader obtained from the object can also be
+utilized as needed. The following code fragment shows how to
+utilize the getPullParser method to create an OMElement :</p>
+<pre>
+XMLStreamReader reader = elt.getPullParser(null);
+OMElement omElt = new StAXOMBuilder(reader).getDocumentElement();
+</pre>
+<p>That's all to it! If you are interested in learning more on ADB
+the following documents may also be helpful. However, be sure to
+check the limitations section that follows if you are planning to
+use ADB for something serious.</p>
+<a name="limitation" id="limitation"></a>
+<h2>Known Limitations</h2>
+<p>ADB is meant to be a 'Simple' databinding framework and was not
+meant to compile all types of schemas. The following limitations
+are the most highlighted.</p>
+<ol>
+<li>Complex Type Extensions and Restrictions.</li>
+</ol>
+<a name="more" id="more"></a>
+<h2>Want to Learn More?</h2>
+<ul>
+<li><a href="adb-advanced.html">Advanced features of the ADB code
+generator</a> - explains xsi:type based deserialization and helper
+mode</li>
+<li><a href="adb-tweaking.html">Tweaking the ADB Code Generator</a>
+- explains available mechanisms to extend ADB and possibly adopt it
+to compile schemas to support other languages.</li>
+<li><a href="adb-codegen-integration.html">ADB and Axis2
+Integration</a> - explains how the ADB schema compiler was attached
+to the Axis2 framework</li>
+</ul>
+</body>
+</html>
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-tweaking.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-tweaking.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/adb-tweaking.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.xml Fri Jul 13 21:37:26 2007
@@ -20,13 +20,16 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <title>ADB Tweaking Guide</title>
- <link href="../../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+<meta name="generator" content=
+"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
+<title>ADB Tweaking Guide</title>
+<link href="../../css/axis-docs.css" rel="stylesheet" type=
+"text/css" media="all" />
</head>
<body lang="en" xml:lang="en">
<h1>ADB Tweaking Guide</h1>
-<p>This document explains the mechanisms available to extend ADB and
-possibly adopt it to compile schemas to support other
+<p>This document explains the mechanisms available to extend ADB
+and possibly adopt it to compile schemas to support other
languages.</p>
<h2>Content</h2>
<ul>
@@ -39,16 +42,16 @@
</ul>
<a name="intro" id="intro"></a>
<h2>Introduction</h2>
-<p>ADB was written with future extensibility in mind, with a clear and
-flexible way to extend or modify its functionality. Available
+<p>ADB was written with future extensibility in mind, with a clear
+and flexible way to extend or modify its functionality. Available
mechanisms to extend ADB and possibly adopt it to compile schemas
to support other languages are described below.</p>
<a name="config" id="config"></a>
<h2>Know the Configuration</h2>
<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>
+<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
@@ -61,14 +64,14 @@
<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 use
-a template.</p>
+may be left blank if the BeanWriter implementation does not use 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
+<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>
@@ -103,9 +106,9 @@
<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 target language
-is object-oriented (such as C# or even C++), one would even be able to extend
-the JavaBeanWriter itself.</p>
+which has a lot of reusable code. In fact if the target language is
+object-oriented (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
@@ -116,15 +119,15 @@
support another language.</p>
</li>
</ul>
-<p>Surprisingly, this is all that needs to be done to have other language support for
-ADB. Change the configuration and you are ready to generate code
-for other languages!</p>
+<p>Surprisingly, this is all that needs to be done 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 to 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>
+generator. Users are free to 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>
</body>
</html>
Copied: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.xml (from r556217, webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html)
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adv-userguide.xml?view=diff&rev=556222&p1=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adv-userguide.html&r1=556217&p2=webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adv-userguide.xml&r2=556222
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.xml Fri Jul 13 21:37:26 2007
@@ -19,10 +19,10 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
- <meta http-equiv="content-type" content="">
+ <meta http-equiv="content-type" content=""/>
<title>Axis2 Advanced User's Guide</title>
<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
- media="all">
+ media="all"/>
</head>
<body dir="ltr" lang="en-US">
@@ -151,7 +151,7 @@
org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
//send the string back.
retDoc.setEchoStringReturn(param4.getEchoStringParam());
- return retDoc;<br></pre>
+ return retDoc;<br/></pre>
</source><a name="Step4_Create_archive"></a>
<h3>Step 3: Create Archive File</h3>
@@ -182,7 +182,7 @@
this:</p>
<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
-border="0"></p>
+border="0"/></p>
<a name="Step5_Deploy_web_service"></a>
<h3>Step 4: Deploy Web Service</h3>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org