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 2006/11/13 14:28:23 UTC
svn commit: r474303 -
/webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html
Author: chatra
Date: Mon Nov 13 05:28:22 2006
New Revision: 474303
URL: http://svn.apache.org/viewvc?view=rev&rev=474303
Log:
completed review
Modified:
webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html?view=diff&rev=474303&r1=474302&r2=474303
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/Axis2ArchitectureGuide.html Mon Nov 13 05:28:22 2006
@@ -1,734 +1,738 @@
-<!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">Apache Axis2 Architecture Guide</h1>
-
-<p>This document will give 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">axis-dev@ws.apache.org</a></i>. Prefix
-subject with [Axis2]. To subscribe to mailing list see <a
-href="http://ws.apache.org/axis2/mail-lists.html">here.</a></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 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>
-
-<h2><a name="bmBP">The Big Picture</a></h2>
-
-<p>A new architecture for Axis was introduced during the August 2004 Summit
-in Colombo, Sri Lanka. This new architecture Axis2 is based on 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 the 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 SOAP Sender and received by 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, the Web services allow them to inter operate. 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
-the life of the 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 it's components via 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- WSDL, SOAP and WS-Addressing. Other specifications like
-JAX-RPC, SAAJ & WS-Policy are layered on top of the Core Architecture.</p>
-
-<h2><a name="thearchi">Axis2 Architecture</a></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 is stateless 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 system to
- be suspended and resumed.</li>
-</ul>
-
-<p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of
-core modules which collectively make up the core architecture of Axis2, and
-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 has a
- hierarchy for the 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 itself, under Web
- services project, allowing that sub-project (AXIOM) to provide a simple
- API for SOAP and XML info-set. And 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 some specific places.</li>
- <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model
- allows the user to deploy services, configure the transports, 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 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 those can be used to construct any other MEP. (Please note that even if client api has in-built support for the above named MEPs, it does not, in any means, limit Axis2's flexibility to support custom MEPs.)</li>
- <li><p><a href="#bmTransports">Transports</a>- Axis2 define 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 may 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 will generate 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 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>
-
-<h2><a name="bmInfoMod">Information Model</a></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 instances (e.g.Message Context).</p>
-
-<p>These two hierarchies creates 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 starting point is a Context
-then it is search in the Description hierarchy as well.</p>
-
-<p>This allows the user to declare and override values, 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. Life cycle depends on the scope of the service.</p>
- </td>
- <td width="103"><p>AxisService</p>
- </td>
- <td width="336"><p>Hold 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>Hold message level static information like schema of the particular message.</p>
- </td>
- </tr>
- </tbody>
-</table>
-<a name="bmXML"></a>
-
-<h2>XML Processing Model</h2>
-
-<p>As we mentioned above, XML processing model of Axis2 has becomes a separate sub-project, called <a href="http://ws.apache.org/commons/axiom/index.html">Apache Axiom</a>, in Apache Web services project. Please refer to the <a href="OMTutorial.html">OM Tutorial</a> for more information. </p>
-
-<h2><a name="bmSOAPPM">SOAP Processing Model</a></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. 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 would
-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>Above explained processing happens for each and every SOAP message
-exchanged. After processing one message Axis2 may decide to create other SOAP
-messages, in which case more complex message patterns emerge. However Axis2
-always view 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 the Axis2 slang those 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>
-
-<h3><a name="default">Axis2 Default Processing Model</a></h3>
-
-<p>Axis2 has some inbuilt handlers that run in inbuilt phases and they create
-the default configuration for the 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 <a href="http://www.wso2.net/tutorials/axis2/java/2006/06/18/operation-service-message-is-destined-to">here</a> for more information on Dispatching)</li>
-</ol>
-<ul>
- <li><a name="mr">Message Receiver - Consume the SOAP Message and hands that
- over to application , Message receiver is the last handler of the
- in-pipe</a></li>
- <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
- message is destined to. Always runs as last handler in the out-pipe</p>
- </li>
-</ul>
-
-<h3><a name="incomingsoap">Processing an Incoming SOAP Message</a></h3>
-
-<p>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</p>
-<a href="#messageContext">Message Context</a> is created from the incoming
-SOAP Message. This message context encpsulates 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>Let us see what happens at each phase of the execution. This process may
-happen either in the server or in the Client.</p>
-<ol>
- <li><strong>Transport Phase</strong> - The handlers are in the phase meant
- to process transport specific information such as validating incoming
- message by looking at various transport headers, add 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 in order to do the
- dispatching. As an example, processing of addressing headers of the SOAP
- message, if any, happen 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
- tries to find the correct service and operation this particular message
- is destined to.<br>
- The post condition of the dispatch phase (any phase can contain a post
- condition) checks whether a service and an operation was found by the
- dispatchers. If not the execution will halt and throws out a "service not
- found error".</li>
- <li><strong>User Defined Phases</strong> - Users are allowed to engage
- their custom handlers here.</li>
- <li>Message Validation Phase - 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>
-
-<h3><a name="outgoing">Processing of the Outgoing Message</a></h3>
-
-<p><em>Out Pipe</em> is simpler because the service and operation to dispatch
-is 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>Message Initialize Phase - First phase of the <em>Out Pipe</em>. Serves
- as the placeholder for the custom handlers</li>
- <li>User Phases - This executes handlers in user defined phases</li>
- <li>Transports Phase - Execute any transport handlers taken from the
- associated transport configuration. The last handler would be a transport
- sender which would send the SOAP message to the target endpoint.</li>
-</ol>
-
-<h3><a name="extending">Extending SOAP Processing Model</a></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 much on
-making it extendable.</p>
-
-<p>Idea behind introducing step wise processing of the SOAP message in terms
-of handlers & 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 on the default processing behavior.
-SOAP Processing Model can be extended with <a
-href="#extendingwithhandlers">handler</a> or <a
-href="#extendingwithmodules">modules</a>.
-
-<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>or as the last handler in a phase.</li>
- <li>or before a given handler</li>
- <li>or after a given handler</li>
-</ol>
-
-<h4><a name="extendingwithmodules">Extending the SOAP Processing Model with
-Modules</a></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 add 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, operations 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 can not 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
-provide 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>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 following
-information.</p>
-<ol>
- <li>Service level parameters</li>
- <li>Modules that are engaged service level</li>
- <li>Service Specific <a href="#mr">Message Receivers</a></li>
- <li>Operations inside the service</li>
-</ol>
-
-<h3><a name="modulearchive">Module Archive</a></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 is starting up, Axis2 asks the deployment model to create an
-Axis Configuration. 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. System will build contexts on top of the
-Axis Configuration. After this, Axis2 is ready to send or receive the 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 indefinite number of
-scenarios, even though Axis2 is built on a core that support any messaging
-interaction, the developers were compelled to provie in-built support for only two most widely
-used Message Exchange Patterns (MEPs).</p>
-
-<p>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>
-
-<h3><a name="oneway">One Way Messaging Support</a></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 much 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 used to send the SOAP Message</li>
- <li>Listener transport - transport the Response is received</li>
- <li>Use Separate Channel - determines whether the response is send over a
- separate transport connection or not. This can be false only when 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 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 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.
-Transport sender sends the SOAP message, depending on its configuration.</p>
-
-<p>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 support 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 most 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, the process is the same except
-for the template that is being used.</p>
-
-<h2><a name="bmDB" id="bmDB">Data Binding</a></h2>
-
-<h3>Integration with 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 geneation
-allows different data binding frameworks to be plugged in. This is done
-through an extension mechanism where the codegen engine calls extensions
-first 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 the choice, 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>
-
-<h3><a name="serial" id="serial">Serialization and De-Serialization of Data
-bound classes</a></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 the 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>
+<!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">Apache Axis2 Architecture Guide</h1>
+
+<p>This document will give 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">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></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 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 Axis2 is based on 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 the 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 SOAP Sender and received by 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, 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
+the life of the 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 it's components via 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> & <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 is stateless 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 system to
+ be suspended and resumed.</li>
+</ul>
+
+<p>Axis2 architecture is modular. Therefore Axis2 Framework is built up of
+core modules which collectively make up the core architecture of Axis2, and
+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 has a
+ hierarchy for the 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 itself, under 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. And 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 some specific places.</li>
+ <li><p><a href="#bmDeployment">Deployment Model</a>- Axis2 deployment model
+ allows the user to deploy services, configure the transports, 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 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 those can be used to construct any other MEP. (Please note that even if client API has in-built support for the above named MEPs, it does not, in any means, limit Axis2's flexibility to support custom MEPs.)</li>
+ <li><p><a href="#bmTransports">Transports</a>- Axis2 define 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 may 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 will generate 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 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 instances (e.g.Message Context).</p>
+
+<p>These two hierarchies creates 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 starting point is a Context
+then it is search in the Description hierarchy as well.</p>
+
+<p>This allows the user to declare and override values, 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. Life cycle depends on the scope of the service.</p>
+ </td>
+ <td width="103"><p>AxisService</p>
+ </td>
+ <td width="336"><p>Hold 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>Hold message level static information like schema of the particular message.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+<a name="bmXML"></a>
+
+<h2>XML Processing Model</h2>
+
+<p>As we mentioned above, XML processing model of Axis2 has becomes a separate sub-project, called <a href="http://ws.apache.org/commons/axiom/index.html">Apache Axiom</a>, in 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. 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 would
+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>Above explained processing happens for each and every SOAP message
+exchanged. After processing one message Axis2 may decide to create other SOAP
+messages, in which case more complex message patterns emerge. However Axis2
+always view 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 the Axis2 slang those 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 the 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 <a href="http://www.wso2.net/tutorials/axis2/java/2006/06/18/operation-service-message-is-destined-to">here</a> for more information on Dispatching)</li>
+</ol>
+<ul>
+ <li><a name="mr"></a>Message Receiver - Consume the SOAP Message and hands that
+ over to application , Message receiver is the last handler of the
+ in-pipe</li>
+ <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
+ message is destined to. Always runs as last handler in the out-pipe</p>
+ </li>
+</ul>
+<a name="incomingsoap"></a>
+<h3>Processing an Incoming SOAP Message</h3>
+
+<p>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</p>
+<a href="#messageContext">Message Context</a> is created from the incoming
+SOAP Message. This message context encpsulates 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>Let us see what happens at each phase of the execution. This process may
+happen either in the server or in the Client.</p>
+<ol>
+ <li><strong>Transport Phase</strong> - The handlers are in the phase meant
+ to process transport specific information such as validating incoming
+ message by looking at various transport headers, add 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 in order to do the
+ dispatching. As an example, processing of addressing headers of the SOAP
+ message, if any, happen 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
+ tries to find the correct service and operation this particular message
+ is destined to.<br>
+ The post condition of the dispatch phase (any phase can contain a post
+ condition) checks whether a service and an operation was found by the
+ dispatchers. If not the execution will halt and throws out a "service not
+ found error".</li>
+ <li><strong>User Defined Phases</strong> - Users are allowed to engage
+ their custom handlers here.</li>
+ <li>Message Validation Phase - 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><em>Out Pipe</em> is simpler because the service and operation to dispatch
+is 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>Message Initialize Phase - First phase of the <em>Out Pipe</em>. Serves
+ as the placeholder for the custom handlers</li>
+ <li>User Phases - This executes handlers in user defined phases</li>
+ <li>Transports Phase - Execute any transport handlers taken from the
+ associated transport configuration. The last handler would be a transport
+ sender which would send the SOAP message to the target endpoint.</li>
+</ol>
+<a name="extending"></a>
+<h3>Extending 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 much on
+making it extendable.</p>
+
+<p>Idea behind introducing step wise processing of the SOAP message in terms
+of handlers & 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 on the default processing behavior.
+SOAP Processing Model can be extended with <a
+href="#extendingwithhandlers">handler</a> or <a
+href="#extendingwithmodules">modules</a>.
+
+<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>or as the last handler in a phase.</li>
+ <li>or 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 add 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, operations 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 can not 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
+provide 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>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 following
+information.</p>
+<ol>
+ <li>Service level parameters</li>
+ <li>Modules that are engaged 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 is starting up, Axis2 asks the deployment model to create an
+Axis Configuration. 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. System will build contexts on top of the
+Axis Configuration. After this, Axis2 is ready to send or receive the 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 indefinite number of
+scenarios, even though Axis2 is built on a core that support any messaging
+interaction, the developers were compelled to provie in-built support for only two most widely
+used Message Exchange Patterns (MEPs).</p>
+
+<p>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 much 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 used to send the SOAP Message</li>
+ <li>Listener transport - transport the Response is received</li>
+ <li>Use Separate Channel - determines whether the response is send over a
+ separate transport connection or not. This can be false only when 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 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 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.
+Transport sender sends the SOAP message, depending on its configuration.</p>
+
+<p>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 support 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 most 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, 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 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 geneation
+allows different data binding frameworks to be plugged in. This is done
+through an extension mechanism where the codegen engine calls extensions
+first 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 the choice, 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 the 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>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org