You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2007/02/06 11:54:29 UTC
svn commit: r504072 -
/webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html
Author: chatra
Date: Tue Feb 6 02:54:28 2007
New Revision: 504072
URL: http://svn.apache.org/viewvc?view=rev&rev=504072
Log:
Reviewed and committed patch in JIRA AXIS2-2117
Modified:
webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html
Modified: webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html?view=diff&rev=504072&r1=504071&r2=504072
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/Axis2ArchitectureGuide.html Tue Feb 6 02:54:28 2007
@@ -4,19 +4,21 @@
<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" />
+ <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>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">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>
+subject with [Axis2]. You can also <a
+href="http://ws.apache.org/axis2/mail-lists.html">subscribe</a> to the
+mailing lists.</p>
<h2>Contents</h2>
<ul>
@@ -39,7 +41,8 @@
</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>
+ <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>
@@ -67,7 +70,7 @@
</ul>
</li>
<li><a href="#bmTransports">Transports</a></li>
- <li><p><a href="#bmWSDL">Code generation</a></p>
+ <li><p><a href="#bmWSDL">Code Generation</a></p>
</li>
<li><a href="#bmDB">Data Binding</a>
<ul>
@@ -81,11 +84,12 @@
</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
+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>
@@ -98,15 +102,16 @@
<h2>Requirement of Axis2</h2>
-<p>In the SOAP terminology, a participant who is taking part in a Web service
+<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 SOAP Sender and received by SOAP Receiver. A single SOAP
-delivery is the most basic unit that builds the Web service interaction.</p>
+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, the Web services allow them to interoperate. This
-is possible because on the wire each Web service interaction is done via
+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"
@@ -114,11 +119,11 @@
<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
+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
+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
@@ -130,83 +135,93 @@
<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 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> & <a href="http://www.w3.org/Submission/WS-Policy/">WS-Policy</a> are layered on top
-of the Core Architecture.</p>
+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 is stateless inside Axis2. This allows code to be
- executed freely by parallel threads.</p>
+ 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 system to
- be suspended and resumed.</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 which collectively make up the core architecture of Axis2, and
-non-core/other modules are layered on top of this core modules/architecture.</p>
+<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 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><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
+ <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>
+ 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 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
+ <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 may write or plug-in
- new ones if and when it is needed.</p>
+ 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 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><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">
@@ -222,6 +237,7 @@
<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
@@ -238,22 +254,22 @@
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>
+more than one instance (e.g.Message Context).</p>
-<p>These two hierarchies creates a model that provides the ability to search
+<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 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>
+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>
@@ -266,13 +282,13 @@
<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 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>
+ modules, parameters, and services etc.</p>
</td>
</tr>
<tr>
@@ -295,11 +311,12 @@
</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>
+ 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>Hold the Operations and the service level
+ <td width="336"><p>Holds the Operations and the service level
configurations</p>
</td>
</tr>
@@ -324,7 +341,8 @@
</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 width="336"><p>Holds message level static information like the
+ schema of the particular message.</p>
</td>
</tr>
</tbody>
@@ -333,8 +351,13 @@
<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>
+<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=""
@@ -342,21 +365,21 @@
<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
+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 would
+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>
+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
@@ -366,24 +389,26 @@
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 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 the Axis2 slang those are named 'phases'. A Handler
+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
+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
+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>
@@ -391,103 +416,113 @@
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>
+ 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 - 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><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>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>
+<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 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>
+
+<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 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>
+ 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
- tries to find the correct service and operation this particular message
- is destined to.<br>
+ 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 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>
+ 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
+ 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>
+<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 SOAP Processing Model</h3>
-<p>Above we discussed the default processing model of Axis2. Now let us
+<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 much on
+whole effort of making this SOAP engine/processing model was focused 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>.
+<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>
+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>
+ <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>
+
+<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
@@ -495,28 +530,29 @@
<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>
+</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
+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, 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>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 can not be added (no hot deployment) while the Axis2 engine is
+<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>
@@ -529,11 +565,11 @@
<h3>The axis2.xml file</h3>
<p>This file holds the global configuration for the client and server, and
-provide following information:</p>
+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>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>
@@ -541,17 +577,18 @@
<h3>Service Archive</h3>
-<p>Service archive must have a <em>META-INF/<a
+<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 following
-information.</p>
+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 service level</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
@@ -559,13 +596,13 @@
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>
+<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>
@@ -574,42 +611,44 @@
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>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>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>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
+<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>
+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>
+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 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>
+ <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
@@ -618,20 +657,20 @@
<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>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>
+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
+<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
+<p>Transport Senders and Transport Receivers contain the following
information.</p>
<ol>
<li>Transport Sender for Out Configuration</li>
@@ -639,20 +678,21 @@
<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>Each and every transport out configuration defines a transport sender. The
+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>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 support the following transports:</p>
+<p>Axis2 presently supports the following transports:</p>
<ol>
- <li>HTTP - In HTTP transport the transport listener is a servlet or
+ <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>
+ 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>
@@ -663,11 +703,11 @@
<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
+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
+<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>
@@ -677,21 +717,22 @@
<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
+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>
+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 Code Generation Engine</h3>
+<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 geneation
+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
+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>
@@ -707,25 +748,25 @@
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>
+ 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
+ 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>
+
+<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
+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
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org