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 ch...@apache.org on 2007/05/25 10:09:37 UTC
svn commit: r541579 [2/18] - in /webservices/axis2/trunk/java/xdocs: ./
@axis2_version_dir@/ @axis2_version_dir@/adb/
@axis2_version_dir@/adb/images/ @axis2_version_dir@/images/
@axis2_version_dir@/images/archi-guide/ @axis2_version_dir@/images/usergui...
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/Axis2ArchitectureGuide.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/Axis2ArchitectureGuide.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/Axis2ArchitectureGuide.html Fri May 25 01:09:03 2007
@@ -0,0 +1,779 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Architecture Guide</title>
+ <meta content="20050916;22455288">
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1 align="center">eApache Axis2 Architecture Guide</h1>
+
+<p>This document gives an introduction to Axis2's modular architecture with
+explanations on every module.</p>
+
+<p><i>Send your feedback to: <a
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix subject with [Axis2].</p>
+
+<h2>Contents</h2>
+<ul>
+ <li><a href="#bmBP">The Big Picture</a></li>
+ <li><p><a href="#requirements">Requirement of Axis2</a></p>
+ </li>
+ <li><a href="#thearchi">Axis2 Architecture</a>
+ <ul>
+ <li><p><a href="#bmcore">Core Modules</a></p>
+ </li>
+ <li><a href="#bmother">Other Modules</a></li>
+ <li><p><a href="#bmInfoMod">Information Model</a></p>
+ </li>
+ <li><a href="#bmXML">XML Processing Model</a></li>
+ <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
+ <ul>
+ <li><a href="#default">Axis2 Default Processing Model</a></li>
+ <li><p><a href="#incomingsoap">Processing an Incoming SOAP
+ Message</a></p>
+ </li>
+ <li><a></a><a href="#outgoing">Processing of the Outgoing
+ Message</a></li>
+ <li><p><a href="#extending">Extending the SOAP Processing
+ Model</a></p>
+ <ul>
+ <li><a href="#extendingwithhandlers">Extending the SOAP
+ Processing Model with Handlers</a></li>
+ <li><p><a href="#extendingwithmodules">Extending the SOAP
+ Processing Model with Modules</a></p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#bmDeployment">Deployment</a>
+ <ul>
+ <li><a href="#xmlfile">The <em>axis2.xml</em> file</a></li>
+ <li><p><a href="#servicearchive">Service Archive</a></p>
+ </li>
+ <li><a href="#modulearchive">Module Archive</a></li>
+ </ul>
+ </li>
+ <li><p><a href="#bmClientAPI">Client API</a></p>
+ <ul>
+ <li><a href="#oneway">One Way Messaging Support</a></li>
+ <li><p><a href="#requestresponse">Request Response Messaging
+ Support</a></p>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#bmTransports">Transports</a></li>
+ <li><p><a href="#bmWSDL">Code Generation</a></p>
+ </li>
+ <li><a href="#bmDB">Data Binding</a>
+ <ul>
+ <li><a href="#integration">Integration with Code Generation
+ Engine</a></li>
+ <li><p><a href="#serial">Serialization and De-Serialization</a></p>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+</ul>
+<a name="bmBP"></a>
+
+<h2>The Big Picture</h2>
+
+<p>A new architecture for Axis was introduced during the August 2004 Summit
+in Colombo, Sri Lanka. This new architecture on which Axis2 is based is more
+flexible, efficient, and configurable in comparison to <a
+href="http://ws.apache.org/axis/java/architecture-guide.html">Axis1.x
+architecture</a>. Some well established concepts from Axis 1.x, like handlers
+etc., have been preserved in this new architecture.</p>
+
+<p>Any architecture is a result of what that architecture should yield. The
+success of an architecture should be evaluated based on the requirements
+expected to be met by that architecture. Let us start our journey into Axis2
+by looking at the requirements.</p>
+<a name="requirements"></a>
+
+<h2>Requirement of Axis2</h2>
+
+<p>In SOAP terminology, a participant who is taking part in a Web service
+interaction is known as a SOAP Node. Delivery of a single SOAP Message is
+defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP
+message is sent by a SOAP Sender and received by a SOAP Receiver. A single
+SOAP delivery is the most basic unit that builds the Web service
+interaction.</p>
+
+<p>Each SOAP Node may be written in specific programming language, may it be
+Java, C++, .NET or Perl, but the Web services allow them to interoperate.
+This is possible because on the wire each Web service interaction is done via
+SOAP, which is common to every SOAP Node.</p>
+
+<p><img alt="" src="images/archi-guide/soap.gif" name="Graphic1"
+align="bottom" width="691" height="319" border="0"></p>
+
+<p>Web service middleware handles the complexity in SOAP messaging and lets
+the users work with the programming language they are accustomed to. Axis2
+allows Java users to invoke Web services using Java representations, and
+handles the SOAP messaging behind the curtain.</p>
+
+<p>Axis2 handles SOAP processing along with numerous other tasks. This makes
+life of a Web service developer a whole lot easier. Following are the
+identified requirements:</p>
+<ol>
+ <li>Provide a framework to process the SOAP messages. The framework should
+ be extensible and the users should be able to extend the SOAP processing
+ per service or per operation basis. Furthermore, it should be able to
+ model different Message Exchange Patterns (MEPs) using the processing
+ framework.</li>
+ <li>Ability to deploy a Web service (with or without WSDL)</li>
+ <li>Provide a Client API that can be used to invoke Web services. This API
+ should support both the Synchronous and Asynchronous programming
+ models.</li>
+ <li>Ability to configure Axis2 and its components through deployment.</li>
+ <li>Ability to send and receive SOAP messages with different
+ transports.</li>
+</ol>
+
+<p>Apart from the above functionalities, performance in terms of memory and
+speed is a major consideration for Axis2. Axis2 Core Architecture is built on
+three specifications- <a href="http://www.w3.org/TR/wsdl">WSDL</a>, <a
+href="http://www.w3.org/TR/soap/">SOAP</a> and <a
+href="http://www.w3.org/Submission/ws-addressing/">WS-Addressing</a>. Other
+specifications like JAX-RPC, <a
+href="http://java.sun.com/webservices/saaj/index.jsp"> SAAJ</a> and <a
+href="http://www.w3.org/Submission/WS-Policy/">WS-Policy</a> are layered on
+top of the Core Architecture.</p>
+<a name="thearchi"></a>
+
+<h2>Axis2 Architecture</h2>
+Axis2 architecture lays out some principals to preserve the uniformity. They
+are as follows:
+<ul>
+ <li><p>Axis2 architecture separates the logic and the states. Code that
+ does the processing does not have a state inside Axis2. This allows code
+ to be executed freely by parallel threads.</p>
+ </li>
+ <li>All the information is kept in one information model, allowing the
+ system to be suspended and resumed.</li>
+</ul>
+
+<p>Axis2 architecture is modular. Therefore, Axis2 Framework is built up of
+core modules that collectively make up the core architecture of Axis2.
+Non-core/other modules are layered on top of this core
+modules/architecture.</p>
+<a name="bmcore"></a>
+
+<h3>Core Modules:</h3>
+<ul>
+ <li><a href="#bmInfoMod">Information Model</a> - Axis2 defines a model to
+ handle information and all states are kept in this model. The model
+ consists of a hierarchy of information. The system manages the life cycle
+ of the objects in this hierarchy.</li>
+ <li><p><a href="#bmXML">XML processing Model</a> - Handling the SOAP
+ Message is the most important and most complex task. The efficiency of
+ this is the single most important factor that decides the performance. It
+ makes sense to delegate this task to a separate sub-project under the Web
+ services project, allowing that sub-project (<a
+ href="http://ws.apache.org/commons/axiom/index.html">AXIOM</a> or AXis
+ Object Model) to provide a simple API for SOAP and XML info-set. It will
+ hide the complexities of the efficient XML processing within the
+ implementation.</p>
+ </li>
+ <li><a href="#bmSOAPPM">SOAP Processing Model</a> - This controls the
+ execution of the processing. The model defines different phases the
+ execution would walk through, and the user can extend the Processing
+ Model at specific places.</li>
+ <li><p><a href="#bmDeployment">Deployment Model</a> - The Axis2 deployment
+ model allows the user to deploy services, configure the transports, and
+ extend the SOAP Processing model per system, service, or operation
+ basis.</p>
+ </li>
+ <li><a href="#bmClientAPI">Client API</a> - This provides a convenient API
+ for users to communicate with Web services using Axis2. There are a set
+ of classes to interact with IN-OUT and IN-Only style <a
+ href="http://www.w3.org/2002/ws/cg/2/07/meps.html">Message Exchange
+ Patterns (MEPs)</a>, where they can be used to construct any other MEP.
+ (Please note that even if the client API has in-built support for the
+ above named MEPs, it does not by any means limit Axis2's flexibility to
+ support custom MEPs.)</li>
+ <li><p><a href="#bmTransports">Transports</a> - Axis2 defines a transport
+ framework that enables the user to use multiple different transports. The
+ transports fit into specific places in the SOAP processing model. The
+ implementation provides a few common transports and the user can write or
+ plug-in new ones if and when it is needed.</p>
+ </li>
+</ul>
+<a name="bmother"></a>
+
+<h3>Other Modules:</h3>
+<ul>
+ <li><a href="#bmWSDL">Code Generation</a> - Axis2 provides a code
+ generation tool that generates server side and client side code along
+ with descriptors and a test case. The generated code would simplify the
+ service deployment and the service invocation. This would increase the
+ usability of Axis2.</li>
+ <li><p><a href="#bmDB">Data Binding</a> - The basic client API of Axis2
+ lets the users process SOAP at the infoset level, where as data binding
+ extends it to make it more convenient to the users by encapsulating the
+ infoset layer and providing a programming language specific interface.</p>
+ </li>
+</ul>
+<map name="Graphic2Map" id="g2m">
+ <area shape="rect" coords="123,31,222,97" href="#bmInfoMod" alt="">
+ <area shape="rect" coords="239,62,319,134" href="#bmXML" alt="">
+ <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM" alt="">
+ <area shape="rect" coords="12,39,89,95" href="#bmDeployment" alt="">
+ <area shape="rect" coords="0,108,94,156" href="#bmWSDL" alt="">
+ <area shape="rect" coords="350,31,426,86" href="#bmClientAPI" alt="">
+ <area shape="rect" coords="350,114,421,164" href="#bmTransports" alt="">
+</map>
+
+<p><img src="images/archi-guide/all.png" name="Graphic2" width="426" alt=""
+height="189" border="0" align="bottom" usemap="#Graphic2Map"></p>
+<a name="bmInfoMod"></a>
+
+<h2>Information Model</h2>
+
+<p>Information Model has two main hierarchies-Contexts and Descriptions. This
+model is described in UML notations below.</p>
+
+<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
+alt="" width="400" height="443" border="0"></p>
+
+<p>( A ----<> B says, B has 1 or more objects of A. A------>B says,
+the given relationship holds between A and B.)</p>
+
+<p>The two hierarchies are connected as shown in the above figure. The
+Description hierarchy represents the static data. This data may be loaded
+from a configuration file that exists throughout the lifetime of Axis2. For
+example, deployed Web services, operations, etc. On the other hand, the
+context hierarchy holds more dynamic information about the things that have
+more than one instance (e.g.Message Context).</p>
+
+<p>These two hierarchies create a model that provides the ability to search
+for key value pairs. When the values are searched at a given level, they are
+searched while moving up the hierarchy until a match is found. In the
+resulting model, the lower levels override the values in the upper levels.
+For example, when a value is looked up in the Message Context and is not
+found, it would be looked up in the Operation Context, etc, up the hierarchy.
+The Search is first done up the hierarchy, and if the starting point is a
+Context then it searches in the Description hierarchy as well.</p>
+
+<p>This allows the user to declare and override values, with the result being
+a very flexible configuration model. The flexibility could be the
+<em>Achilles</em> heel for the system as the search is expensive, specially
+for something that does not exist. Yet in the final analysis, developers
+believe that the flexibility would serve better in this instant.</p>
+
+<table width="955" border="1" cellpadding="2" cellspacing="3">
+ <col width="112"><col width="371"><col width="103"><col width="336"><tbody>
+ <tr>
+ <td><strong>Context</strong></td>
+ <td><strong>Description</strong></td>
+ <td><strong>Configuration</strong></td>
+ <td><strong>Description</strong></td>
+ </tr>
+ <tr>
+ <td width="112"><p>Configuration Context</p>
+ </td>
+ <td width="371"><p>Holds the Axis2's run time status. A deep copy of
+ this would essentially make a copy of Axis2.</p>
+ </td>
+ <td width="103"><p>Axis Configuration</p>
+ </td>
+ <td width="336"><p>Holds all global configurations. Transports, global
+ modules, parameters, and services etc.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Group Context</p>
+ </td>
+ <td width="371"><p>Holds information about a particular usage of the
+ respective service group. The life of a Service Group Context starts
+ when a user starts interacting with a service that belong to this
+ service group. This can be used to share information between services
+ (within the same service group) in a single interaction.</p>
+ </td>
+ <td width="103"><p>AxisServiceGroup</p>
+ </td>
+ <td width="336"><p>Holds deployment time information about a particular
+ service group.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Context</p>
+ </td>
+ <td width="371"><p>This context is available throughout the usage of
+ the respective service. This can be used to share information between
+ several MEPs of the same service, within a single interaction. The
+ life cycle depends on the scope of the service.</p>
+ </td>
+ <td width="103"><p>AxisService</p>
+ </td>
+ <td width="336"><p>Holds the Operations and the service level
+ configurations</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Operation Context</p>
+ </td>
+ <td width="371"><p>Holds the information about the current MEP
+ instance, maintain the messages in the current MEP etc.</p>
+ </td>
+ <td width="103"><p>AxisOperation</p>
+ </td>
+ <td width="336"><p>Holds the operation level configurations</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><a name="messageContext"></a>
+
+ <p>Message Context</p>
+ </td>
+ <td width="371"><p>Holds all the information about the Message
+ currently being executed.</p>
+ </td>
+ <td width="103"><p>AxisMessage</p>
+ </td>
+ <td width="336"><p>Holds message level static information like the
+ schema of the particular message.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<a name="bmXML"></a>
+
+<h2>XML Processing Model</h2>
+
+<p>As we mentioned above, the XML processing model of Axis2 has become a
+separate sub-project, called <a
+href="http://ws.apache.org/commons/axiom/index.html">Apache Axiom</a>, in the
+Apache Web services project. Please refer to the <a href="OMTutorial.html">OM
+Tutorial</a> for more information.</p>
+<a name="bmSOAPPM"></a>
+
+<h2>SOAP Processing Model</h2>
+
+<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" alt=""
+align="bottom" width="755" height="348" border="0"></p>
+
+<p>The architecture identified two basic actions a SOAP processor should
+perform, sending and receiving SOAP messages. The architecture provides two
+Pipes ('Flows'), to perform these two basic actions. The Axis Engine or the
+driver of Axis2 defines two methods send() and receive() to implement these
+two Pipes. The two pipes are named <i><b>In</b> Pipe</i> and <i><b>Out</b>
+Pipe</i>, and the complex Message Exchange Patterns (MEPs) are constructed by
+combining these two pipes.</p>
+
+<p>Extensibility of the SOAP processing model is provided through handlers.
+When a SOAP message is being processed, the handlers that are registered will
+be executed. The handlers can be registered in global, service, or operation
+scopes and the final handler chain is calculated combining the handlers from
+all the scopes.</p>
+
+<p>The handlers act as interceptors and they process parts of the SOAP
+message and provide add-on services. Usually handlers work on the SOAP
+headers, yet they may access or change the SOAP body as well.</p>
+
+<p>When a SOAP message is being sent through the Client API, an <i>Out
+Pipe</i> would begin, the <i>Out Pipe</i> invokes the handlers and end with a
+Transport Sender that sends the SOAP message to the target endpoint. The SOAP
+message is received by a Transport Receiver at the target endpoint, which
+reads the SOAP message and starts the <i>In Pipe</i>. The <em>In Pipe</em>
+consists of handlers and ends with the <a href="#mr">Message Receiver</a>,
+which consumes the SOAP message.</p>
+
+<p>The processing explained above happens for each and every SOAP message
+that is exchanged. After processing one message, Axis2 may decide to create
+other SOAP messages, in which case more complex message patterns emerge.
+However, Axis2 always views the SOAP message in terms of processing a single
+message. The combination of the messages are layered on top of that basic
+framework.</p>
+
+<p>The two pipes does not differentiate between the Server and the Client.
+The SOAP Processing Model handles the complexity and provides two abstract
+pipes to the user. The different areas or the stages of the pipes are given
+names, and according to Axis2 slang, they are named 'phases'. A Handler
+always runs inside a phase, and the phase provides a mechanism to specify the
+ordering of handlers. Both Pipes have built-in phases, and both define the
+areas for 'User Phases' which can be defined by the user.</p>
+<a name="default"></a>
+
+<h3>Axis2 Default Processing Model</h3>
+
+<p>Axis2 has some inbuilt handlers that run in inbuilt phases and they create
+the default configuration for Axis2. We will be looking more in to how to
+extend the default processing Model in the next section.</p>
+There are three special handlers defined in Axis2.
+<ol>
+ <li>Dispatchers - Finds the service and the operation the SOAP message is
+ directed to. Dispatchers always run on the <em>In-Pipe</em> and inside
+ the Dispatch phase. The in-built dispatchers dispatch to a particular
+ operation depending on various conditions like WS-Addressing information,
+ URI information, SOAP action information, etc. ( See more information on
+ <a
+ href="http://www.wso2.net/tutorials/axis2/java/2006/06/18/operation-service-message-is-destined-to">Dispatching</a>)</li>
+</ol>
+<ul>
+ <li><a name="mr"></a>Message Receiver - Consumes the SOAP message and hands
+ it over to the application. The message receiver is the last handler of
+ the in-pipe</li>
+ <li><p>Transport Sender - Sends the SOAP message to the SOAP endpoint the
+ message is destined to. Always runs as the last handler in the
+ out-pipe</p>
+ </li>
+</ul>
+<a name="incomingsoap"></a>
+
+<h3>Processing an Incoming SOAP Message</h3>
+
+<p>An incoming SOAP message is always received by a Transport Receiver
+waiting for the SOAP messages. Once the SOAP message arrives, the transport
+Headers are parsed and a <a href="#messageContext">Message Context</a> is
+created from the incoming SOAP message. This message context encapsulates all
+the information, including the SOAP message itself, transport headers, etc.,
+inside it. Then the <i>In Pipe</i> is executed with the Message Context.</p>
+
+<p>Let us see what happens at each phase of the execution. This process can
+happen in the server or in the client.</p>
+<ol>
+ <li><strong>Transport Phase</strong> - The handlers are in the phase that
+ processes transport specific information such as validating incoming
+ messages by looking at various transport headers, adding data into
+ message context, etc.</li>
+ <li><strong>Pre-Dispatch Phase</strong>- The main functionality of the
+ handlers in this phase is to populate message context to do the
+ dispatching. For example, processing of addressing headers of the SOAP
+ message, if any, happens in this phase. Addressing handlers extract
+ information and put them in to the message context.</li>
+ <li><strong>Dispatch Phase</strong> - The Dispatchers run in this phase and
+ try to find the correct service and operation this particular message is
+ destined for.<br>
+ The post condition of the dispatch phase (any phase can contain a post
+ condition) checks whether a service and an operation were found by the
+ dispatchers. If not, the execution will halt and give a "service not
+ found' error.</li>
+ <li><strong>User Defined Phases</strong> - Users can engage their custom
+ handlers here.</li>
+ <li><strong>Message Validation Phase</strong> - Once the user level
+ execution has taken place, this phase validates whether SOAP Message
+ Processing has taken place correctly.</li>
+ <li><strong>Message Processing Phase</strong> - The Business logic of the
+ SOAP message is executed here. A <a href="#mr">Message Receiver</a> is
+ registered with each Operation. This message receiver (associated to the
+ particular operation) will be executed as the last handler of this
+ phase.</li>
+</ol>
+
+<p>There may be other handlers in any of these phases. Users may use custom
+handlers to override the mechanics in each of these phases.</p>
+<a name="outgoing"></a>
+
+<h3>Processing of the Outgoing Message</h3>
+
+<p>The<em> Out Pipe</em> is simpler because the service and the operation to
+dispatch are known by the time the pipe is executed. The <em>Out Pipe</em>
+may be initiated by the</p>
+<a href="#mr">Message Receiver</a> or the Client API implementation. Phases
+of the <em>Out Pipe</em> are described below:
+<ol>
+ <li><strong>Message Initialize Phase</strong> - First phase of the <em>Out
+ Pipe</em>. Serves as the placeholder for the custom handlers.</li>
+ <li><strong>User Phases</strong> - Executes handlers in user-defined
+ phases.</li>
+ <li><strong>Transports Phase</strong> - Executes any transport handlers
+ taken from the associated transport configuration. The last handler would
+ be a transport sender which will send the SOAP message to the target
+ endpoint.</li>
+</ol>
+<a name="extending"></a>
+
+<h3>Extending the SOAP Processing Model</h3>
+
+<p>Above, we discussed the default processing model of Axis2. Now let us
+discuss the extension mechanism for the SOAP processing model. After all, the
+whole effort of making this SOAP engine/processing model was focused on
+making it extendable.</p>
+
+<p>The idea behind introducing step-wise processing of the SOAP message in
+terms of handlers and phases is to allow easier modification of the
+processing order. The notion of phases makes it easier to place handlers in
+between other handlers. This enables modification of the default processing
+behavior. The SOAP Processing Model can be extended with <a
+href="#extendingwithhandlers">handlers</a> or <a
+href="#extendingwithmodules">modules</a>.</p>
+
+<h4>Extending the SOAP Processing Model with Handlers</h4>
+
+<p>The handlers in a module can specify the phase they need to be placed in.
+Furthermore, they can specify their location inside a phase by providing
+phase rules. Phase rules will place a handler,</p>
+<ol>
+ <li>as the first handler in a phase,</li>
+ <li>as the last handler in a phase,</li>
+ <li>before a given handler,</li>
+ <li>or after a given handler.</li>
+</ol>
+<a name="extendingwithmodules"></a>
+
+<h4>Extending the SOAP Processing Model with Modules</h4>
+
+<p>Axis2 defines an entity called a 'module' that can introduce handlers and
+Web service operations. A Module in terms of Axis2 usually acts as a
+convenient packaging that includes:</p>
+<ul>
+ <li>A set of handlers and</li>
+ <li>An associated descriptor which includes the phase rules</li>
+</ul>
+
+<p>Modules have the concept of being 'available' and 'engaged'.
+'Availability' means the module is present in the system, but has not been
+activated, i.e., the handlers included inside the module have not been used
+in the processing mechanism. When a module is 'engaged' it becomes active and
+the handlers get placed in the proper phases. The handlers will act in the
+same way as explained in the previous section. Usually a module will be used
+to implement a WS-* functionality such as WS-Addressing.</p>
+
+<p>Apart from the extension mechanism based on the handlers, the WS-*
+specifications may suggest a requirement for adding new operations. For
+example, once a user adds Reliable Messaging capability to a service, the
+"Create Sequence" operation needs to be available to the service endpoint.
+This can be implemented by letting the modules define the operations. Once
+the module is engaged to a service, the necessary operations will be added to
+that service.</p>
+
+<p>A service, operation, or the system may engage a module. Once the module
+is engaged, the handlers and the operations defined in the module are added
+to the entity that engaged them.</p>
+
+<p>Modules cannot be added (no hot deployment) while the Axis2 engine is
+running, but they will be available once the system is restarted.</p>
+<a name="bmDeployment"></a>
+
+<h2>Deployment</h2>
+
+<p>The Deployment Model provides a concrete mechanism to configure Axis2.
+This model has three entities that provide the configuration.</p>
+<a name="xmlfile"></a>
+
+<h3>The axis2.xml file</h3>
+
+<p>This file holds the global configuration for the client and server, and
+provides the following information:</p>
+<ol>
+ <li>The global parameters</li>
+ <li>Registered transport-in and transport-outs</li>
+ <li>User-defined phase names</li>
+ <li>Modules that are engaged globally (to all services)</li>
+ <li>Globally defined <a href="#mr">Message Receivers</a></li>
+</ol>
+<a name="servicearchive"></a>
+
+<h3>Service Archive</h3>
+
+<p>The Service archive must have a <em>META-INF/<a
+href="resources/schemas/services.xsd">services.xml</a></em> file and may
+contain the dependent classes. The <em>services.xml</em> file has the
+following information.</p>
+<ol>
+ <li>Service level parameters</li>
+ <li>Modules that are engaged at service level</li>
+ <li>Service Specific <a href="#mr">Message Receivers</a></li>
+ <li>Operations inside the service</li>
+</ol>
+<a name="modulearchive"></a>
+
+<h3>Module Archive</h3>
+
+<p>Module archive must have a META-INF/<a
+href="resources/schemas/module.xsd">module.xml</a> file and dependent
+classes. The <em>module.xml</em> file has Module parameters and the
+Operations defined in the module.</p>
+
+<p>When the system starts up, Axis2 prompts the deployment model to create an
+Axis Configuration. The deployment model first finds the axis2.xml file and
+builds the global configuration. Then it checks for the module archives and
+then for the service archives. After that, the corresponding services and
+modules are added to the Axis Configuration. The system will build contexts
+on top of the Axis Configuration. After this, Axis2 is ready to send or
+receive SOAP messages. Hot deployment is only allowed for services.</p>
+<a name="bmClientAPI"></a>
+
+<h2>Client API</h2>
+
+<p>There are three parameters that decide the nature of the Web service
+interaction.</p>
+<ol>
+ <li>Message Exchange Pattern (MEP)</li>
+ <li>The behavior of the transport, whether it's One-Way or Two-Way</li>
+ <li>Synchronous/ Asynchronous behavior of the Client API</li>
+</ol>
+
+<p>Variations of the three parameters can result in an indefinite number of
+scenarios. Even though Axis2 is built on a core that supports any messaging
+interaction, the developers were compelled to provide in-built support for
+only two most widely used Message Exchange Patterns (MEPs).</p>
+
+<p>The two supported MEPs are One-Way and the In-Out (Request-Response)
+scenarios in the Client API. The implementation is based on a class called
+<code>ServiceClient</code> and there are extensions for each MEP that Axis2
+Client API supports.</p>
+<a name="oneway"></a>
+
+<h3>One Way Messaging Support</h3>
+
+<p>The One-Way support is provided by the <code>fireAndForget</code> method
+of <code>ServiceClient</code>. For one way invocations, one can use HTTP ,
+SMTP and TCP transports. In the case of the HTTP transport, the return
+channel is not used, and the HTTP 202 OK is returned in the return
+channel.</p>
+<a name="requestresponse"></a>
+
+<h3>In-Out (Request Response) Messaging Support</h3>
+
+<p>The In-Out support is provided by the <code>sendReceive()</code> method in
+ServiceClient. This provides a simpler interface for the user. The Client API
+has four ways to configure a given message exchange</p>
+<ol>
+ <li>Blocking or Non-Blocking nature - this can be decided by using
+ <code>sendReceive()</code> or <code>sendReceiveNonBlocking()</code>
+ methods</li>
+ <li>Sender transport - transport that sends the SOAP message</li>
+ <li>Listener transport - transport that receives the response</li>
+ <li>Use Separate Channel - determines whether the response is sent over a
+ separate transport connection or not. This can be false only when the
+ sender and listener transport is same and is a Two-Way transport.</li>
+</ol>
+
+<p>Depending on the values of the above four parameters, Axis2 behaves
+differently.</p>
+<a name="bmTransports"></a>
+
+<h2>Transports</h2>
+
+<p>Axis2 has two basic constructs for transports, namely: Transport Senders
+and Transport Receivers. These are accessed via the AxisConfiguration.</p>
+
+<p>The incoming transport is the transport via which the AxisEngine receives
+the message. The outgoing transport is decided based on the addressing
+information (wsa:ReplyTo and wsa:FaultTo). If addressing information is not
+available and if the server is trying to respond, then the out going
+transport will be the outputstream of the incoming transport (if it is
+two-way transport).</p>
+
+<p>At the client side, the user is free to specify the transport to be
+used.</p>
+
+<p>Transport Senders and Transport Receivers contain the following
+information.</p>
+<ol>
+ <li>Transport Sender for Out Configuration</li>
+ <li>Transport Listener for In Configuration</li>
+ <li>Parameters of the transport</li>
+</ol>
+
+<p>Each and every transport out configuration defines a transport sender. The
+transport sender sends the SOAP message depending on its configuration.</p>
+
+<p>The transport receiver waits for the SOAP messages, and for each SOAP
+message that arrives, it uses the <i>In Pipe</i> to process the SOAP
+message.</p>
+
+<p>Axis2 presently supports the following transports:</p>
+<ol>
+ <li>HTTP - In HTTP transport, the transport listener is a servlet or
+ org.apache.axis2.transport.http.SimpleHTTPServer provided by Axis2. The
+ transport sender uses commons-httpclient to connect and send the SOAP
+ message.</li>
+ <li>TCP - This is the simplest transport, but needs the WS - Addressing
+ support to be functional.</li>
+ <li>SMTP - This works off a single email account. Transport receiver is a
+ thread that checks for emails in fixed time intervals.</li>
+ <li>JMS</li>
+</ol>
+<a name="bmWSDL" id="bmWSDL"></a>
+
+<h2>Code Generation</h2>
+
+<p>Although the basic objective of the code generation tools has not changed,
+the code generation module of Axis2 has taken a different approach to
+generate code. Primarily, the change is in the use of templates, namely XSL
+templates, which gives the code generator the flexibility to generate code in
+multiple languages.</p>
+
+<p>The basic approach is to set the code generator to generate an XML, and
+parse it with a template to generate the code file. The following figure
+describes how this shows up in the architecture of the tool.</p>
+
+<p><img src="images/archi-guide/CodegenArchitecture-new.gif" name="Graphic6"
+alt="" align="bottom" border="0"></p>
+
+<p>The fact here is that it is the same information that is extracted from
+the WSDL no matter what code is generated. First, an AxisService is populated
+from a WSDL. Then the code generator extracts information from the
+AxisService and creates an XML, which is language independent. This emitted
+XML is then parsed with the relevant XSL to generate code for the relevant
+language. No matter what the output language is, the process is the same
+except for the template that is being used.</p>
+<a name="bmDB" id="bmDB"></a>
+
+<h2>Data Binding</h2>
+
+<h3>Integration with the Code Generation Engine</h3>
+
+<p>Databinding for Axis2 is implemented in an interesting manner. Databinding
+has not been included in the core deliberately, and hence the code generation
+allows different data binding frameworks to be plugged in. This is done
+through an extension mechanism where the codegen engine first calls the
+extensions and then executes the core emitter. The extensions populate a map
+of QNames vs. class names that is passed to the code generator on which the
+emitter operates on.</p>
+
+<p><strong>The following diagram shows the structure:</strong></p>
+
+<p><img src="images/codegen.gif" name="Graphic7" align="bottom"
+border="0"></p>
+
+<p><strong>The following databinding extensions are available:</strong></p>
+<ol>
+ <li><strong>ADB</strong> - ADB (Axis Data Binding ) is a simple framework
+ that allows simple schemas to be compiled. It is lightweight and simple,
+ works off StAX and fairly performant. However, it does not support the
+ complete set of schema constructs and is likely to complain for certain
+ schemas!</li>
+ <li><strong>XMLBeans</strong> - XMLbeans claims that it supports the
+ complete schema specification, and it is preferred if full schema support
+ is needed!</li>
+ <li><strong>JAX-Me</strong> - JaxMe support has been added in a similar
+ manner to XMLbeans and serves as another option for the user</li>
+ <li><strong>JibX</strong> - This is the most recent addition to the family
+ of databinding extensions, and it is also another option the users have
+ for data binding.</li>
+</ol>
+<a name="serial" id="serial"></a>
+
+<h3>Serialization and De-Serialization of Data bound classes</h3>
+
+<p>AXIOM is based on a StAX API (Streaming API for XML). Xml-beans supports
+StAX API. Data binding in Axis2 is achieved through interfacing the AXIOM
+with the Xml-beans using the StAX API, which is supported by both parties. At
+the time of code generation, there will be utility methods generated inside
+the stub (or the message receiver) that can de-serialize from AXIOM to data
+bound object and serialize from data bound object to AXIOM. For example, if
+the WSDL has an operation called "echoString", once the code is generated,
+the following methods will be generated inside the relevant classes.</p>
+<pre>public static
+org.apache.axiom.om.OMElement toOM(org.soapinterop.xsd.EchoStringParamDocument
+param)// This method will handle the serialization.
+
+public static org.apache.xmlbeans.XmlObject
+fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) //This
+method will handle the de-serialization.</pre>
+</body>
+</html>
Added: 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.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/WS_policy.html Fri May 25 01:09:03 2007
@@ -0,0 +1,187 @@
+<!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>
Added: 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.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-advanced.html Fri May 25 01:09:03 2007
@@ -0,0 +1,122 @@
+<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>
Added: 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.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-codegen-integration.html Fri May 25 01:09:03 2007
@@ -0,0 +1,93 @@
+<!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>
+ <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>
+<p>This document will assist you in writing an extension using the
+integrator in order to integrate ADB with Axis2.</p>
+<h2>Content</h2>
+<ul>
+<li><a href="#intro">Introduction</a></li>
+<li><a href="#select_modes">Selection of Generation Modes for
+ADB</a></li>
+<li><a href="#remember">Things to Remember</a></li>
+</ul>
+<h2><a name="intro" id="intro">Introduction</a></h2>
+<p>ADB Integration with Axis2 is simple and straightforward. Given
+the extension mechanism of the Axis2 code generator, the obvious
+choice for the 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>
+<a name="select_modes" id="select_modes"></a>
+<h2>Selection of Generation Modes for ADB</h2>
+<p>The extension sets the options for the code generator via the
+CompilerOptions, depending on the user's settings. The following
+table summarizes the use of options. Please refer to the <a href=
+"adb-howto.html" target="_blank">ADB-How to document</a> for the
+different generation modes and their descriptions.</p>
+<table border="1">
+<tbody>
+<tr>
+<td><strong>User parameters</strong></td>
+<td><strong>Selected code generation parameters</strong></td>
+</tr>
+<tr>
+<td>None (no parameter other than mandatory ones)</td>
+<td>wrapClasses=false,writeClasses=false</td>
+</tr>
+<tr>
+<td>-ss (server side)</td>
+<td>wrapClasses=false,writeClasses=true</td>
+</tr>
+<tr>
+<td>-u (unwrap classes)</td>
+<td>wrapClasses=false,writeClasses=true</td>
+</tr>
+</tbody>
+</table>
+<p>The following parameters (prefixed with -E) can be used to
+override these settings manually:</p>
+<table border="1">
+<tbody>
+<tr>
+<td><strong>Parameter Name</strong></td>
+<td><strong>Allowed values</strong></td>
+<td><strong>Description</strong></td>
+</tr>
+<tr>
+<td>r</td>
+<td>true, false</td>
+<td>Sets the write flag. If set to true the classes will be written
+by ADB</td>
+</tr>
+<tr>
+<td>w</td>
+<td>true, false</td>
+<td>Sets the 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>
+<pre>
+WSDL2Java .... -Er true
+</pre>
+<a name="remember" id="remember"></a>
+<h2>Things to Remember</h2>
+<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
+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>
+<hr />
+</body>
+</html>
Added: 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.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-howto.html Fri May 25 01:09:03 2007
@@ -0,0 +1,407 @@
+<!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>
Added: 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.html?view=auto&rev=541579
==============================================================================
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/adb-tweaking.html Fri May 25 01:09:03 2007
@@ -0,0 +1,112 @@
+<!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>
+ <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
+languages.</p>
+<h2>Content</h2>
+<ul>
+<li><a href="#intro">Introduction</a></li>
+<li><a href="#config">Know the Configuration</a></li>
+<li><a href="#first_tweak">The First Tweak - Generate Plain Java
+Beans</a></li>
+<li><a href="#advanced_tweak">A More Advanced Tweak - Generate Code
+for Another Language</a></li>
+</ul>
+<a name="intro" 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
+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>
+<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 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
+QName to Class name string mapping.</p>
+</li>
+</ul>
+<a name="first_tweak" id="first_tweak"></a>
+<h2>The First Tweak - Generate Plain Java Beans</h2>
+<p>The first, most simple tweak for the code generator could be to
+switch to plain bean generation. The default behavior of the ADB
+framework is to generate ADBBeans, but most users, if they want to
+use ADB as a standalone compiler, would prefer 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>
+<a name="advanced_tweak" id="advanced_tweak"></a>
+<h2>A More Advanced Tweak - Generate Code for Another Language</h2>
+<p>To generate code for another language, there are two main
+components that need 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 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
+<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 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>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adb/images/ADB.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adb/images/ADB.jpg?view=auto&rev=541579
==============================================================================
Binary file - no diff available.
Propchange: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/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