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 2005/12/01 06:18:42 UTC
svn commit: r350168 - in /webservices/axis2/trunk/java:
modules/core/src/org/apache/axis2/client/
modules/core/src/org/apache/axis2/context/ xdocs/
Author: chinthaka
Date: Wed Nov 30 21:18:29 2005
New Revision: 350168
URL: http://svn.apache.org/viewcvs?rev=350168&view=rev
Log:
- I missed one. I haven't set the properties of InOnlyMEPClient to the operation context. My fault and fixing that.
- started to look in to architectture guide. Some more to come from documents.
(I added some code to AbstractContext, which is yet to be tested. So I commented them out for the time being. Please bear with me until I fix that and commit.)
Modified:
webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/InOnlyMEPClient.java
webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/Options.java
webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/context/AbstractContext.java
webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
Modified: webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/InOnlyMEPClient.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/InOnlyMEPClient.java?rev=350168&r1=350167&r2=350168&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/InOnlyMEPClient.java (original)
+++ webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/InOnlyMEPClient.java Wed Nov 30 21:18:29 2005
@@ -19,6 +19,7 @@
import org.apache.axis2.AxisFault;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.MessageContext;
+import org.apache.axis2.context.OperationContext;
import org.apache.axis2.context.ServiceContext;
import org.apache.axis2.description.AxisOperation;
import org.apache.axis2.description.TransportOutDescription;
@@ -48,13 +49,12 @@
*/
public void send(AxisOperation axisop, final MessageContext msgctx) throws AxisFault {
prepareInvocation(axisop, msgctx);
- if(msgctx.getMessageID() == null){
- String messageID = String.valueOf("uuid:"+ UUIDGenerator.getUUID());
+ if (msgctx.getMessageID() == null) {
+ String messageID = String.valueOf("uuid:" + UUIDGenerator.getUUID());
msgctx.setMessageID(messageID);
}
msgctx.setServiceContext(serviceContext);
-
//if the transport to use for sending is not specified, try to find it from the URL
TransportOutDescription senderTransport = clientOptions.getSenderTransport();
if (senderTransport == null) {
@@ -65,7 +65,9 @@
//initialize and set the Operation Context
ConfigurationContext sysContext = serviceContext.getConfigurationContext();
- msgctx.setOperationContext(axisop.findOperationContext(msgctx, serviceContext));
+ OperationContext operationContext = axisop.findOperationContext(msgctx, serviceContext);
+ msgctx.setOperationContext(operationContext);
+ operationContext.setProperties(clientOptions.getProperties());
AxisEngine engine = new AxisEngine(sysContext);
engine.send(msgctx);
Modified: webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/Options.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/Options.java?rev=350168&r1=350167&r2=350168&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/Options.java (original)
+++ webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/Options.java Wed Nov 30 21:18:29 2005
@@ -40,6 +40,7 @@
*/
public class Options {
+
private Map properties = new HashMap();
// ==========================================================================
@@ -76,6 +77,8 @@
// ==========================================================================
// Constants
// ==========================================================================
+ public static final String COPY_PROPERTIES = "CopyProperties";
+
private static final int DEFAULT_TIMEOUT_MILLISECONDS = 2000;
// ==========================================================================
@@ -103,6 +106,14 @@
return properties;
}
+ /**
+ * This will set the properties to the context. But in setting that one may need to "copy" all
+ * the properties from the source properties to the target properties. To enable this we introduced
+ * a property (org.apache.axis2.client.Options#COPY_PROPERTIES) so that if set to Boolean(true),
+ * this code will copy the whole thing, without just referencing to the source.
+ *
+ * @param properties
+ */
public void setProperties(Map properties) {
this.properties = properties;
}
Modified: webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/context/AbstractContext.java
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/context/AbstractContext.java?rev=350168&r1=350167&r2=350168&view=diff
==============================================================================
--- webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/context/AbstractContext.java (original)
+++ webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/context/AbstractContext.java Wed Nov 30 21:18:29 2005
@@ -82,8 +82,35 @@
return properties;
}
- public void setProperties(Map properties) {
- this.properties = properties;
- }
+// /**
+// * This will set the properties to the context. But in setting that one may need to "copy" all
+// * the properties from the source properties to the target properties. To enable this we introduced
+// * a property (org.apache.axis2.client.Options#COPY_PROPERTIES) so that if set to true, this code
+// * will copy the whole thing, without just referencing to the source.
+// *
+// * @param properties
+// * @see org.apache.axis2.client.Options#COPY_PROPERTIES
+// */
+// public void setProperties(Map properties) {
+// properties = new HashMap();
+// if (properties == null) {
+// this.properties = null;
+// } else {
+// Boolean copyProperties = ((Boolean) properties.get(Options.COPY_PROPERTIES));
+// if (copyProperties != null && copyProperties.booleanValue()) {
+// Iterator iterator = properties.keySet().iterator();
+// while (iterator.hasNext()) {
+// Object key = iterator.next();
+// this.properties.put(key, properties.get(key));
+// }
+// } else {
+// this.properties = properties;
+// }
+// }
+// }
+
+ public void setProperties(Map properties) {
+ this.properties = properties;
+ }
}
Modified: webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html?rev=350168&r1=350167&r2=350168&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html (original)
+++ webservices/axis2/trunk/java/xdocs/Axis2ArchitectureGuide.html Wed Nov 30 21:18:29 2005
@@ -1,715 +1,709 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
- <meta http-equiv="content-type" content="text/html; charset=windows-1252">
- <title>Axis2 Architecture Guide</title>
- <meta name="CREATED" content="20050916;22455288">
- <meta name="CHANGEDBY" content="Chamikara Jayalath">
- <meta name="CHANGED" content="20050918;22493797">
-</head>
-
-<body lang="en-US" dir="ltr">
-<h1>Axis2 Architecture Guide</h1>
-
-<h2>Contents</h2>
-<ul>
- <li><p><a href="#bmBP">The Big Picture</a></p>
- </li>
- <li><p><a href="#bmInfoMod">Information Model</a></p>
- </li>
- <li><p><a href="#bmXML">XML Processing Model</a></p>
- </li>
- <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
- </li>
- <li><p><a href="#bmDeployment">Deployment</a></p>
- </li>
- <li><p><a href="#bmWSDL">WSDL and code generation</a></p>
- </li>
- <li><p><a href="#bmDB">Data Binding</a></p>
- </li>
- <li><p><a href="#bmClientAPI">Client API</a></p>
- </li>
- <li><p><a href="#bmTransports">Transports</a></p>
- </li>
-</ul>
-
-<p><br>
-<br>
-</p>
-
-<h2><a name="bmBP"></a>The Big Picture</h2>
-
-<p>Any architecture is a result of what that architecture should yield, the
-success of an architecture should be evaluated bases on the requirements the
-architecture should meet. Let us start our journey in to Axis2 looking at the
-requirements that are expected from Axis2.</p>
-
-<h3>Requirement of Axis2</h3>
-
-<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, and single SOAP
-delivery is the most basic unit that builds the Web Service interactions.</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 at the wire each Web Service interaction is done via
-SOAP, which is common to every SOAP Node.</p>
-
-<p><img src="images/archi-guide/soap.gif" name="Graphic1" align="bottom"
-width="691" height="319" border="0"></p>
-
-<p>Web Service middleware handles the complexity SOAP messaging and let the
-users to work with the programming language they are accustomed to. Axis2
-allows the java users to invoke the Web Services using java representations
-and handles the SOAP messaging behind the curtain.</p>
-
-<p>Axis2 handles SOAP processing, along with numerous other functionalities
-that make the life of the Web Service developer convenient. Following are the
-identified requirements:</p>
-<ol>
- <li><p style="margin-bottom: 0in">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 operation basis. Furthermore
- it should be able to model different Message Exchange Patterns using the
- processing framework.</p>
- </li>
- <li><p style="margin-bottom: 0in">Ability to deploy the Web Services (with
- or without WSDL)</p>
- </li>
- <li><p style="margin-bottom: 0in">Provide a Client API that can be used to
- invoke Web Services, the API should supports both the Synchronous and
- Asynchronous programming models.</p>
- </li>
- <li><p style="margin-bottom: 0in">Ability to configure Axis2 and it's
- components via the deployment</p>
- </li>
- <li><p>Ability to send and receive SOAP messages with different
- transports</p>
- </li>
-</ol>
-
-<p>Apart from the above functionalities, performance, both in the 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 and SAAJ are layered on top of the Core
-Architecture. The WS-Policy might join the core specifications in the near
-future.</p>
-
-<h3>Axis2, the Architecture</h3>
-
-<p>Now having look at the requirements of the Axis2 we can direct our
-attention to the Architecture.</p>
-
-<p>Axis2 architecture lay out few Principals to preserve the uniformity of
-the architecture, they are as follows.</p>
-<ul>
- <li><p style="margin-bottom: 0in">Axis2 Architecture separates the logic
- and the states, the code that process the logic is usually stateless.
- This allows the code to be executed freely by parallel threads.</p>
- </li>
- <li><p>All the information is kept in a one Information model, this allows
- the system to be stored and resumed</p>
- </li>
-</ul>
-
-<p>Axis2 architecture is modular, the architecture broke the Axis2 in to
-Seven modules.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Information Model</p>
- </li>
- <li><p style="margin-bottom: 0in">XML processing Model</p>
- </li>
- <li><p style="margin-bottom: 0in">SOAP Processing Model</p>
- </li>
- <li><p style="margin-bottom: 0in">Deployment</p>
- </li>
- <li><p style="margin-bottom: 0in">WSDL and Code Generation</p>
- </li>
- <li><p style="margin-bottom: 0in">Client API</p>
- </li>
- <li><p>Transports</p>
- </li>
-</ol>
-
-<p><img src="images/archi-guide/all.png" name="Graphic2" align="bottom"
-width="426" height="189" border="0"></p>
-
-<p>Let us look in to the rationale for each Module, and what each does?</p>
-
-<p>Axis2 defines a model to handle the information and all the states are
-kept in this model. The model has a hierarchy for the information and the
-system manages the life cycle of the objects in this hierarchy.</p>
-
-<p>Handling the SOAP Message is the most important and the most complex task,
-the efficiency of this is the single most important factor that decides the
-performance. It make sense to delegate this task to a separate module, and
-that module, AXIOM provide a simple API for SOAP and XML info-set and while
-hiding the complexities of the efficient XML processing with in the
-implementation.</p>
-
-<p>SOAP Processing Model controls the execution of the processing, the Model
-defines different phases the execution would walk though, and the user can
-extend the Processing Model at some specific places.</p>
-
-<p>Axis2 define a transport framework that enables user to use different
-transports, the transports match in to the specific places in the SOAP
-processing model. The implementation provide few common transports and user
-may write new ones if he wishes.</p>
-
-<p>Axis2 deployment model allows the user to deploy services, configure the
-transports, extend the SOAP Processing model per system basis, per service
-basis, and per operation basis.</p>
-
-<p>Finally Axis2 provides a code generation tool that will generate server
-side and client side code along a test case. The generated code would
-simplify the service deployment and the service invocation. This would make
-the Axis2 easier to use.</p>
-
-<h2><a name="bmInfoMod"></a>Information Model</h2>
-
-<p>Information Model has two main hierarchies, the Contexts and
-Descriptions.</p>
-
-<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
-width="400" height="443" border="0"></p>
-
-<p>This uses UML notations ( A ----<> B means B has 1 or more objects
-of A. A------>B means 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 data that exists throughout the lifetime of
-Axis2. Examples for such data would be deployed Web Services, operations,
-etc. On the other hand, the context hierarchy holds more dynamic information
-about things that has more than one instances (e.g.Message Context).</p>
-
-<p>These two hierarchies created 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 in the level until a match is found. In the
-resulting model the lower levels overrides the values in the upper levels.
-For and example when a value is looked up at the Message Context and it is
-not found, it would be looked up at 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 user to declare and override values, and result in very
-flexible configuration model. The flexibility could be the Achilles heel for
-the system, as the search, specially for something that does not exist is
-expensive, yet in the final analysis developers believe that the flexibility
-would serve better in this instants and opt for the flexibility.</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 width="112"><p>Configuration Context</p>
- </td>
- <td width="371"><p>Holds the current state of execution. 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.</p>
- </td>
- </tr>
- <tr>
- <td width="112"><p>Service Group Context</p>
- </td>
- <td width="371"><p>Holds information about a perticular usage of the
- respective service group. The life of a Service Group Context start
- when a user start to interact with a service that belong to this
- service group. This can be used to share information between service
- usages in a single interaction, for services that belong to the same
- group.</p>
- </td>
- <td width="103"><p>ServiceGroup Description</p>
- </td>
- <td width="336"><p>Holds deployment time information about a perticular
- service group.</p>
- </td>
- </tr>
- <tr>
- <td width="112"><p>Service Context</p>
- </td>
- <td width="371"><p>This context is avaliable throughout a usage of the
- respective service. This can be used to share information between
- several MAPs that belong to the same service, within a single
- interaction.</p>
- </td>
- <td width="103"><p>Service Description</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>Operation Description</p>
- </td>
- <td width="336"><p>Holds the operation level configurations</p>
- </td>
- </tr>
- <tr>
- <td width="112"><p><a name="messageContext"></a>Message Context</p>
- </td>
- <td width="371"><p>Holds all the information about the Message
- currently being executed.</p>
- </td>
- <td width="103"><p>Message Description</p>
- </td>
- <td width="336"><p>Do not hold any information as yet, but can be used
- as future extension point.</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p><br>
-<br>
-</p>
-
-<p>All context classes implement readObject, writeObject methods that allows
-to serialize and de-serialize them correctly. Serializing the current
-Configuration Context object would essentially serialize the whole context
-hierarchy. To restore it, the user has to fist perform the de-serialization
-of the ConfigurationContext object. He can restore the description hierarchy
-by calling the init (axisConfiguration) method of the de-serialized
-ConfigurationContext object.</p>
-
-<h2><a name="bmXML"></a>XML Processing Model</h2>
-
-<p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p>
-
-<h2><a name="bmSOAPPM"></a>SOAP Processing Model</h2>
-
-<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4"
-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 (also named '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>In Pipe</i> and <i>Out Pipe</i>,
-the complex Message Exchange Patterns are constructed by combining these two
-pipes.</p>
-
-<p>Extensibility of the SOAP processing model is provided through the
-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 the 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 send from the Client API, a <i>Out Pipe</i> would
-begin, the <i>Out Pipe</i> invokes the Handlers and ends 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 In Pipe consists of Handlers
-and ends with a <a href="#mr">Message Receiver</a>, which consumes the SOAP
-message.</p>
-
-<p>Above explained processing happens for each and every SOAP message
-exchanged. Processing that follows may decide to give birth for the other
-SOAP messages, in which case the more complex patterns emerge. But Axis2
-always view the SOAP message in terms of processing of a single message where
-as 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. Each pipe is a set of Handlers, the different areas 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 has built in
-Phases, and both define the areas for 'User Phases' which can be defined by
-the user.</p>
-
-<p>Following figure shows the two pipes with their pre-defined Phases, the
-user defined Phases would be fit in to the User Phases.</p>
-
-<p><img src="images/archi-guide/phases.png" name="Graphic5" align="bottom"
-width="525" height="226" border="0"></p>
-
-<h3>Axis2 Default Processing Model</h3>
-
-<p>Axis2 has the, 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>
-
-<p>There are four special handlers defined in Axis2.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Dispatchers - Find the Service the SOAP
- message is directed to, always run on the In-Pipe and inside the Dispatch
- Phase. There is a inbuilt Dispatcher, that run in any case and user may
- override it by placing the dispatchers before the inbuilt Dispatcher.</p>
- </li>
- <li><p style="margin-bottom: 0in"><a name="mr"></a>Message Receiver -
- Consume the SOAP Message and run on the Message Processing Phase in the
- inflow</p>
- </li>
- <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
- message is destined to. Always runs on the</p>
- </li>
-</ol>
-
-<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 is arrived the transport Headers
-are parsed and a <a href="#messageContext">Message Context</a> is created for
-the incoming SOAP Message. The the <i>In Pipe</i> is executed with the
-Message Context. Let us see what would happen at the each Phase of the
-execution, this process my happen in either in the server or the Client,
-there is a special case of using the two way transport where the first four
-phases in the In-Phase most likely to do nothing.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Transport Phase - The Handlers in the
- transport Phase are taken from the transport configuration associated,
- they are executed according to the Phase rules.</p>
- </li>
- <li><p style="margin-bottom: 0in">Pre-Dispatch Phase- The Handlers that
- goes there must be engaged globally (for all services) as the Service
- does not known at this point. The best example for them would be,
- Addressing Handlers and may be security Handlers if the Addressing
- Headers are encrypted.</p>
- </li>
- <li><p style="margin-bottom: 0in">Dispatch Phase - The Dispatchers are run
- in this Phases and find the Service if the service is not found
- already.</p>
- </li>
- <li><p style="margin-bottom: 0in">Post-Dispatch Phase - This phase check
- weather the service is found, if the service has not found by this point
- the execution will halt and send a "service not found error". Policy
- Determination Phase - This Phase does nothing for the time being, this is
- placed for the implementing the Policy</p>
- </li>
- <li><p style="margin-bottom: 0in">User Defined Phases - User defined Phases
- are executed here.</p>
- </li>
- <li><p style="margin-bottom: 0in">Message Validation Phase - Once the user
- level execution is taken place, this Phase will validates has the SOAP
- Message Processing has taken place correctly. For an example the must
- understand processing would happen here.</p>
- </li>
- <li><p>Message Processing Phase - The Business logic of the SOAP message,
- executed here, the a <a href="#mr">Message Receiver</a> is registered
- with a each Operation. The Message receiver associated with the each
- operation would be executed as the last Handler of this Phase.</p>
- </li>
-</ol>
-
-<p>There may be other handlers in the any of the these Phases, users may
-employ custom Handlers to override the mechanics in the each of these Phases.
-If there is a response message, that would be initiated by the <a
-href="#mr">Message Receiver</a>, yet the architecture is not aware of the
-response message and merely invoke the <a href="#mr">Message Receiver</a>.</p>
-
-<h3>Processing of the Outgoing Message</h3>
-
-<p>Out pipe is simpler because the Service and the Operation to dispatch is
-known by the time the pipe is executed. The Out pipe may be initiated by the
-<a href="#mr">Message Receiver</a> or the Client API implementation.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Message Initialize Phase - Fist Phase of
- the out pipe, this serves as the placeholder for the custom Handlers</p>
- </li>
- <li><p style="margin-bottom: 0in">Policy Determination Phase - Just like in
- the in-pipe this is not implemented and suppose to serve as a extension
- point</p>
- </li>
- <li><p style="margin-bottom: 0in">User Phases - This executes Handlers in
- user define Phases</p>
- </li>
- <li><p>Transports Phase - Execute any transport Handlers taken from the
- associated transport configuration and the last handler would be a
- transport Sender which would send the SOAP message to the target end
- point</p>
- </li>
-</ol>
-
-<h3>Extending SOAP Processing Model</h3>
-
-<p>We discussed the default processing model of the Axis2, ability to extend
-the model has been the whole point of spending the energy on the SOAP
-processing model. We shall discuss the extension mechanism for the SOAP
-processing model now.</p>
-
-<p>Idea behind making each step of the SOAP processing in terms of Handlers
-(inbuilt ones we discuss earlier) and placing them in the Phases is to allow
-Handlers to be placed between those Handlers and to override or affect the
-default mechanics. There are two ways the to extend the SOAP Processing
-Model.</p>
-
-<h4>Extending the SOAP Processing Model with Handlers</h4>
-
-<p>The Handlers can specify the Phase they need to be run, further more they
-can specify the there location inside a phase via the following
-information.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Handler should run as the first in the
- phases</p>
- </li>
- <li><p style="margin-bottom: 0in">Handler should run as the last in the
- Phases</p>
- </li>
- <li><p style="margin-bottom: 0in">Handler should run before a given
- Handlers</p>
- </li>
- <li><p>Handler should run after a Given Handler</p>
- </li>
-</ol>
-
-<h4>Extending the SOAP Processing Model with Modules</h4>
-
-<p>SOAP processing Model defines a logical entity called a module that
-encapsulates two entities, Handlers and Web Service Operations. The Handlers
-will act in the same way as explained in the first method.</p>
-
-<p>Apart from the extension mechanism based on the Handlers, the WS-*
-specifications suggest a requirement for add new Operations using modules.
-For an example once a user add a Reliable Messaging capability to a Service,
-the "Create Sequence" operation needs to be available to the service end
-point. This can be implemented by letting the Modules define the operations
-and once the module is engaged to a service the 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 engages them. Modules can not be added while the Axis2 is
-running but later they will be available once the system is restarted.</p>
-
-<h2><a name="bmDeployment"></a>Deployment</h2>
-
-<p>There deployment Model provides a concrete mechanism to configure Axis2.
-Deployment Model has four entities that provide the configuration.</p>
-
-<h3>The <em>axis2.xml</em> file</h3>
-
-<p>This file holds the global configuration for the client and server, and
-provide following information.</p>
-<ol>
- <li><p style="margin-bottom: 0in">The global parameters</p>
- </li>
- <li><p style="margin-bottom: 0in">Registered transports in and transport
- outs</p>
- </li>
- <li><p style="margin-bottom: 0in">User defined Phase names</p>
- </li>
- <li><p style="margin-bottom: 0in">Modules that are engaged globally</p>
- </li>
- <li><p>Globally defines <a href="#mr">Message Receiver</a>s</p>
- </li>
-</ol>
-
-<h3>Service Archive</h3>
-
-<p>Service archive must have a <em>META-INF/services.xml</em> file and may
-contain the dependent classes. the <em>services.xml</em> file has following
-information.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Service level parameters</p>
- </li>
- <li><p style="margin-bottom: 0in">Modules that are engaged Service level</p>
- </li>
- <li><p>Operations inside the Service</p>
- </li>
-</ol>
-
-<h3>Module Archive</h3>
-
-<p>Module archive must have a <em>META-INF/module.xml</em> 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 started up the Axis2 ask the deployment model to create a
-Axis Configuration, the Deployment Model first find a <em>axis2.xml</em> file
-and build the global configuration. Then the Deployment check for the Module
-archives and then for the service archives, the corresponding services and
-Modules are added to the Axis Configuration. System will build Contexts on
-top of the Axis Configurations and the Axis2 is ready to send or receive the
-SOAP Message. The Hot deployment is allowed only for the Service and in that
-case a thread will check the repository repeatedly, and add the Service
-corresponds to the new found Service archives to the repository.</p>
-
-<h2><a name="bmWSDL"></a>WSDL and code generation</h2>
-
-<p>Although the basic objective of the code generation tool 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
-shows how this shows up in the architecture of the tool.</p>
-
-<p><img src="images/archi-guide/CodegenArchitecture.jpg" name="Graphic6"
-align="bottom" width="478" height="218" 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. Code generator uses the WOM (WSDL
-Object Model) internally to manipulate the WSDL and passes that information
-to the emitter which emits an XML. the XML is then parsed with the relevant
-XSL to generate the code. No matter what the language, the process is the
-same except for the template that is being used</p>
-
-<h2><a name="bmDB"></a>Data Binding</h2>
-
-<h3>Integration with the code generation engine</h3>
-
-<p>Axis2 M2 was released with code generation support but without data
-binding. The version 0.9 was shipped with data binding support with complete
-schema support. Such claim is made possible because of the fact that the data
-binding tool, xml-beans, has the full schema support. The original
-architecture of the code generation framework did not undergo significant
-changes because of the way that the code generation framework was originally
-designed. Data binding was incorporated as a pluggable extension to the code
-generation engine. Version 0.91 did not does not support SOAP encoding. It
-only supports RPC literal or document literal massages.</p>
-
-<p><img src="images/codegen.gif" name="Graphic7" align="bottom" width="406"
-height="467" border="0"></p>
-
-<h3>Serialization and De-Serialization</h3>
-
-<p>Xml-beans supports StAX API and AXIOM is based on a 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 supporter classes for each WSDL operation that will
-have the utility methods that can de-serialize the 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 there will
-be an echoStringDatabindingSupporter.java class generated that will have
-methods that will look like the following.</p>
-
-<p>public static org.apache.axis2.om.OMElement
-toOM(org.soapinterop.xsd.EchoStringParamDocument param) : This method will
-handle the serialization.</p>
-
-<p>public static org.apache.xmlbeans.XmlObject
-fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) : This
-method will handle the de-serialization.</p>
-
-<p>public static org.apache.xmlbeans.XmlObject getTestObject(java.lang.Class
-type) : This will be a utility method that can be used to create sample
-objects of the given data bound object.</p>
-
-<h2><a name="bmClientAPI"></a>Client API</h2>
-
-<p>There are three parameters that decide the nature of the Web Service
-interaction.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Message Exchange Pattern</p>
- </li>
- <li><p style="margin-bottom: 0in">The Behavior of the transport. Does it
- act one-way or two way</p>
- </li>
- <li><p>Synchronous/ Asynchronous behavior of the Client API</p>
- </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 support only two most widely
-used Message Exchange Patterns.</p>
-
-<p>Two supported transports are One-Way and the Request-Response scenarios in
-the Client API, the implementation is based on a class called
-<code>MEPClient</code> and there are extensions for each Message Exchange
-Pattern that Axis2 Client API supports.</p>
-
-<h3>One Way Messaging Support</h3>
-
-<p>The One-Way support is provided by the <code>InOnlyMEPClient</code> and
-Axis2 provides a class called <code>MessageSender</code> that provides a much simpler
-interface for the user. The Axis2 supports 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>
-
-<h3>Request Response Messaging Support</h3>
-
-<p>The Request-Response support is provided by the
-<code>InOutMEPClient</code> and Axis2 provides a class called
-<code>Call</code> that provides a much simpler interface for the
-user. The Client API has four ways to configure a given Message Exchange</p>
-<ol>
- <li><p style="margin-bottom: 0in">Blocking or Non-Blocking nature - this
- can be decided by using <code>invokeBlocking()</code> or
- <code>invokeNonBlocking()</code> methods</p>
- </li>
- <li><p style="margin-bottom: 0in">Sender transport - transport use to send
- the SOAP Message</p>
- </li>
- <li><p style="margin-bottom: 0in">Listener transport - transport the
- Response is received</p>
- </li>
- <li><p>Use Separate Channel - does the response is send over a separate
- transport connection or not, this can be false only when sender an
- listener transport is same and is a two way transport.</p>
- </li>
-</ol>
-
-<p>Depend on the values for the above four parameter, Axis2 behave
-differently</p>
-
-<h2><a name="bmTransports"></a>Transports</h2>
-
-<p>Axis2 has two basic constructs for transports, named as Transport In
-Configuration and Transport Out Configuration. The <a
-href="#messageContext">Message Context</a> has two fields to put the input
-and the out put transport to be used. Axis behaves according to the transport
-that is specified in each of the fields.</p>
-
-<p>SOAP Message is arrived at the Server side, the incoming transport is
-decided by the Transport Listener that accepts the incoming SOAP Message. The
-transports for the subsequent SOAP Messages that are related to the first
-message, are decided based on the addressing parameters.</p>
-
-<p>At the Client Side the user is free to specify the transport to be used,
-as in the Server side the transport for the subsequent SOAP Messages are
-decided by the addressing.</p>
-
-<p>There Transport In Configuration and the Transport Out Configuration
-contains following information.</p>
-<ol>
- <li><p style="margin-bottom: 0in">Transport Sender in Out Configuration,
- Transport Listener in the TransportIn Configuration</p>
- </li>
- <li><p style="margin-bottom: 0in">Parameters of the transport</p>
- </li>
- <li><p>Transport Handlers</p>
- </li>
-</ol>
-
-<p>Transport Sender send the SOAP Message over a given transport, each and
-every transport Out Configuration should define a transport Sender that send
-the transport.</p>
-
-<p>Transport Receiver waits for the SOAP Messages and for each SOAP Message
-that arrives, uses the <i>In Pipe</i> to process the SOAP Message.</p>
-
-<p>Axis2 Presently support the following transports</p>
-<ol>
- <li><p style="margin-bottom: 0in">HTTP - The HTTP transport, the transport
- Listener is a Servlet or a Simple HTTP server provided by Axis2. The
- transport Sender uses sockets to connect and send the SOAP Message.
- Currently we have the commons-HTTP-client based HTTP Transport sender as
- the default transport</p>
- </li>
- <li><p style="margin-bottom: 0in">TCP - This is the most simplest
- transport, but needed the addressing support to be functional.</p>
- </li>
- <li><p>SMTP - This work off a single email account, Transport Receiver is a
- tread that checks for emails in fixed time intervals.</p>
- </li>
-</ol>
-</body>
-</html>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=windows-1252">
+ <title>Axis2 Architecture Guide</title>
+ <meta name="CREATED" content="20050916;22455288">
+ <meta name="CHANGEDBY" content="Chamikara Jayalath">
+ <meta name="CHANGED" content="20050918;22493797">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1>Axis2 Architecture Guide</h1>
+
+<h2>Contents</h2>
+<ul>
+ <li><p><a href="#bmBP">The Big Picture</a></p>
+ </li>
+ <li><p><a href="#bmInfoMod">Information Model</a></p>
+ </li>
+ <li><p><a href="#bmXML">XML Processing Model</a></p>
+ </li>
+ <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
+ </li>
+ <li><p><a href="#bmDeployment">Deployment</a></p>
+ </li>
+ <li><p><a href="#bmWSDL">WSDL and code generation</a></p>
+ </li>
+ <li><p><a href="#bmDB">Data Binding</a></p>
+ </li>
+ <li><p><a href="#bmClientAPI">Client API</a></p>
+ </li>
+ <li><p><a href="#bmTransports">Transports</a></p>
+ </li>
+</ul>
+
+<p><br>
+<br>
+</p>
+
+<h2><a name="bmBP"></a>The Big Picture</h2>
+
+<p>Any architecture is a result of what that architecture should yield, the
+success of an architecture should be evaluated based on the requirements the
+architecture should meet. Let us start our journey in to Axis2 looking at the
+requirements that are expected from Axis2.</p>
+
+<h3>Requirement of Axis2</h3>
+
+<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, and single SOAP
+delivery is the most basic unit that builds the Web Service interactions.</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, at the wire, each Web Service interaction is done via
+SOAP, which is common to every SOAP Node.</p>
+
+<p><img 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 let the
+users to work with the programming language they are accustomed to. Axis2
+allows the java users to invoke the Web Services using java representations
+and handles the SOAP messaging behind the curtain.</p>
+
+<p>Axis2 handles SOAP processing, along with numerous other functionalities
+that make the life of the Web Service developer convenient. Following are the
+identified requirements:</p>
+<ol>
+ <li>
+ <p style="margin-bottom: 0in">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 (MEP) using the
+ processing framework.</p>
+ </li>
+ <li>Ability to deploy the Web Services (with
+ or without WSDL)</li>
+ <li>Provide a Client API that can be used to
+ invoke Web Services, the API should support both the Synchronous and
+ Asynchronous programming models.</li>
+ <li>Ability to configure Axis2 and it's
+ components via the deployment</li>
+ <li>Ability to send and receive SOAP messages with different
+ transports</li>
+</ol>
+
+<p>Apart from the above functionalities, performance, both in the 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 and SAAJ are layered on top of the Core
+Architecture. The WS-Policy might join the core specifications in the near
+future.</p>
+
+<h3>Axis2, the Architecture</h3>
+
+<p>Now having look at the requirements of the Axis2 we can direct our
+attention to the Architecture.</p>
+
+<p>Axis2 architecture lay out few principals to preserve the uniformity of
+the architecture, they are as follows.</p>
+<ul>
+ <li><p style="margin-bottom: 0in">Axis2 Architecture separates the logic
+ and the states, the code that process the logic is usually stateless.
+ This allows the code to be executed freely by parallel threads.</p>
+ </li>
+ <li>All the information is kept in a one information model, this allows
+ the system to be stored and resumed</li>
+</ul>
+
+<p>Axis2 architecture is modular, the architecture broke the Axis2 in to
+seven modules.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Information Model</p>
+ </li>
+ <li>XML processing Model</li>
+ <li>SOAP Processing Model</li>
+ <li>Deployment</li>
+ <li>WSDL and Code Generation</li>
+ <li>Client API</li>
+ <li>Transports</li>
+</ol>
+
+<p><img src="images/archi-guide/all.png" name="Graphic2"
+width="426" height="189" border="0" align="bottom" usemap="#Graphic2Map">
+ <map name="Graphic2Map">
+ <area shape="rect" coords="123,31,222,97" href="#bmInfoMod">
+ </map>
+</p>
+
+<p>Let us look in to the rationale for each Module, and what each does?</p>
+
+<p>Axis2 defines a model to handle the information and all the states are
+kept in this model. The model has a hierarchy for the information and the
+system manages the life cycle of the objects in this hierarchy.</p>
+
+<p>Handling the SOAP Message is the most important and the most complex task,
+the efficiency of this is the single most important factor that decides the
+performance. It make sense to delegate this task to a separate module, and
+that module, AXIOM provide a simple API for SOAP and XML info-set while
+hiding the complexities of the efficient XML processing within the
+implementation.</p>
+
+<p>SOAP Processing Model controls the execution of the processing, the model
+defines different phases the execution would walk though, and the user can
+extend the Processing Model at some specific places.</p>
+
+<p>Axis2 define a transport framework that enables user to use different
+transports, the transports match in to the specific places in the SOAP
+processing model. The implementation provide few common transports and user
+may write new ones if he wishes.</p>
+
+<p>Axis2 deployment model allows the user to deploy services, configure the
+transports, extend the SOAP Processing model per system basis, per service
+basis, and per operation basis.</p>
+
+<p>Finally Axis2 provides a code generation tool that will generate server
+side and client side code along a test case. The generated code would
+simplify the service deployment and the service invocation. This would make
+the Axis2 easier to use.</p>
+
+<h2><a name="bmInfoMod"></a>Information Model</h2>
+
+<p>Information Model has two main hierarchies, the Contexts and
+Descriptions.</p>
+
+<p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom"
+width="400" height="443" border="0"></p>
+
+<p>This uses UML notations ( A ----<> B means B has 1 or more objects
+of A. A------>B means 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 data that exists throughout the lifetime of
+Axis2. Examples for such data would be deployed Web Services, operations,
+etc. On the other hand, the context hierarchy holds more dynamic information
+about things that has more than one instances (e.g.Message Context).</p>
+
+<p>These two hierarchies created 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 in the level until a match is found. In the
+resulting model the lower levels overrides the values in the upper levels.
+For and example when a value is looked up at the Message Context and it is
+not found, it would be looked up at 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 user to declare and override values, and result in very
+flexible configuration model. The flexibility could be the Achilles heel for
+the system, as the search, specially for something that does not exist is
+expensive, yet in the final analysis developers believe that the flexibility
+would serve better in this instants and opt for the flexibility.</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 width="112"><p>Configuration Context</p>
+ </td>
+ <td width="371"><p>Holds the current state of execution. 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.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Group Context</p>
+ </td>
+ <td width="371"><p>Holds information about a perticular usage of the
+ respective service group. The life of a Service Group Context start
+ when a user start to interact with a service that belong to this
+ service group. This can be used to share information between service
+ usages in a single interaction, for services that belong to the same
+ group.</p>
+ </td>
+ <td width="103"><p>ServiceGroup Description</p>
+ </td>
+ <td width="336"><p>Holds deployment time information about a perticular
+ service group.</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p>Service Context</p>
+ </td>
+ <td width="371"><p>This context is avaliable throughout a usage of the
+ respective service. This can be used to share information between
+ several MAPs that belong to the same service, within a single
+ interaction.</p>
+ </td>
+ <td width="103"><p>Service Description</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>Operation Description</p>
+ </td>
+ <td width="336"><p>Holds the operation level configurations</p>
+ </td>
+ </tr>
+ <tr>
+ <td width="112"><p><a name="messageContext"></a>Message Context</p>
+ </td>
+ <td width="371"><p>Holds all the information about the Message
+ currently being executed.</p>
+ </td>
+ <td width="103"><p>Message Description</p>
+ </td>
+ <td width="336"><p>Do not hold any information as yet, but can be used
+ as future extension point.</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p><br>
+<br>
+</p>
+
+<p>All context classes implement readObject, writeObject methods that allows
+to serialize and de-serialize them correctly. Serializing the current
+Configuration Context object would essentially serialize the whole context
+hierarchy. To restore it, the user has to fist perform the de-serialization
+of the ConfigurationContext object. He can restore the description hierarchy
+by calling the init (axisConfiguration) method of the de-serialized
+ConfigurationContext object.</p>
+
+<h2><a name="bmXML"></a>XML Processing Model</h2>
+
+<p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p>
+
+<h2><a name="bmSOAPPM"></a>SOAP Processing Model</h2>
+
+<p><img src="images/archi-guide/soap-processing.gif" name="Graphic4"
+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 (also named '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>In Pipe</i> and <i>Out Pipe</i>,
+the complex Message Exchange Patterns are constructed by combining these two
+pipes.</p>
+
+<p>Extensibility of the SOAP processing model is provided through the
+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 the 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 send from the Client API, a <i>Out Pipe</i> would
+begin, the <i>Out Pipe</i> invokes the Handlers and ends 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 In Pipe consists of Handlers
+and ends with a <a href="#mr">Message Receiver</a>, which consumes the SOAP
+message.</p>
+
+<p>Above explained processing happens for each and every SOAP message
+exchanged. Processing that follows may decide to give birth for the other
+SOAP messages, in which case the more complex patterns emerge. But Axis2
+always view the SOAP message in terms of processing of a single message where
+as 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. Each pipe is a set of Handlers, the different areas 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 has built in
+Phases, and both define the areas for 'User Phases' which can be defined by
+the user.</p>
+
+<p>Following figure shows the two pipes with their pre-defined Phases, the
+user defined Phases would be fit in to the User Phases.</p>
+
+<p><img src="images/archi-guide/phases.png" name="Graphic5" align="bottom"
+width="525" height="226" border="0"></p>
+
+<h3>Axis2 Default Processing Model</h3>
+
+<p>Axis2 has the, 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>
+
+<p>There are four special handlers defined in Axis2.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Dispatchers - Find the Service the SOAP
+ message is directed to, always run on the In-Pipe and inside the Dispatch
+ Phase. There is a inbuilt Dispatcher, that run in any case and user may
+ override it by placing the dispatchers before the inbuilt Dispatcher.</p>
+ </li>
+ <li><p style="margin-bottom: 0in"><a name="mr"></a>Message Receiver -
+ Consume the SOAP Message and run on the Message Processing Phase in the
+ inflow</p>
+ </li>
+ <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
+ message is destined to. Always runs on the</p>
+ </li>
+</ol>
+
+<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 is arrived the transport Headers
+are parsed and a <a href="#messageContext">Message Context</a> is created for
+the incoming SOAP Message. The the <i>In Pipe</i> is executed with the
+Message Context. Let us see what would happen at the each Phase of the
+execution, this process my happen in either in the server or the Client,
+there is a special case of using the two way transport where the first four
+phases in the In-Phase most likely to do nothing.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Transport Phase - The Handlers in the
+ transport Phase are taken from the transport configuration associated,
+ they are executed according to the Phase rules.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Pre-Dispatch Phase- The Handlers that
+ goes there must be engaged globally (for all services) as the Service
+ does not known at this point. The best example for them would be,
+ Addressing Handlers and may be security Handlers if the Addressing
+ Headers are encrypted.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Dispatch Phase - The Dispatchers are run
+ in this Phases and find the Service if the service is not found
+ already.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Post-Dispatch Phase - This phase check
+ weather the service is found, if the service has not found by this point
+ the execution will halt and send a "service not found error". Policy
+ Determination Phase - This Phase does nothing for the time being, this is
+ placed for the implementing the Policy</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User Defined Phases - User defined Phases
+ are executed here.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Message Validation Phase - Once the user
+ level execution is taken place, this Phase will validates has the SOAP
+ Message Processing has taken place correctly. For an example the must
+ understand processing would happen here.</p>
+ </li>
+ <li><p>Message Processing Phase - The Business logic of the SOAP message,
+ executed here, the a <a href="#mr">Message Receiver</a> is registered
+ with a each Operation. The Message receiver associated with the each
+ operation would be executed as the last Handler of this Phase.</p>
+ </li>
+</ol>
+
+<p>There may be other handlers in the any of the these Phases, users may
+employ custom Handlers to override the mechanics in the each of these Phases.
+If there is a response message, that would be initiated by the <a
+href="#mr">Message Receiver</a>, yet the architecture is not aware of the
+response message and merely invoke the <a href="#mr">Message Receiver</a>.</p>
+
+<h3>Processing of the Outgoing Message</h3>
+
+<p>Out pipe is simpler because the Service and the Operation to dispatch is
+known by the time the pipe is executed. The Out pipe may be initiated by the
+<a href="#mr">Message Receiver</a> or the Client API implementation.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Message Initialize Phase - Fist Phase of
+ the out pipe, this serves as the placeholder for the custom Handlers</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Policy Determination Phase - Just like in
+ the in-pipe this is not implemented and suppose to serve as a extension
+ point</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User Phases - This executes Handlers in
+ user define Phases</p>
+ </li>
+ <li><p>Transports Phase - Execute any transport Handlers taken from the
+ associated transport configuration and the last handler would be a
+ transport Sender which would send the SOAP message to the target end
+ point</p>
+ </li>
+</ol>
+
+<h3>Extending SOAP Processing Model</h3>
+
+<p>We discussed the default processing model of the Axis2, ability to extend
+the model has been the whole point of spending the energy on the SOAP
+processing model. We shall discuss the extension mechanism for the SOAP
+processing model now.</p>
+
+<p>Idea behind making each step of the SOAP processing in terms of Handlers
+(inbuilt ones we discuss earlier) and placing them in the Phases is to allow
+Handlers to be placed between those Handlers and to override or affect the
+default mechanics. There are two ways the to extend the SOAP Processing
+Model.</p>
+
+<h4>Extending the SOAP Processing Model with Handlers</h4>
+
+<p>The Handlers can specify the Phase they need to be run, further more they
+can specify the there location inside a phase via the following
+information.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Handler should run as the first in the
+ phases</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Handler should run as the last in the
+ Phases</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Handler should run before a given
+ Handlers</p>
+ </li>
+ <li><p>Handler should run after a Given Handler</p>
+ </li>
+</ol>
+
+<h4>Extending the SOAP Processing Model with Modules</h4>
+
+<p>SOAP processing Model defines a logical entity called a module that
+encapsulates two entities, Handlers and Web Service Operations. The Handlers
+will act in the same way as explained in the first method.</p>
+
+<p>Apart from the extension mechanism based on the Handlers, the WS-*
+specifications suggest a requirement for add new Operations using modules.
+For an example once a user add a Reliable Messaging capability to a Service,
+the "Create Sequence" operation needs to be available to the service end
+point. This can be implemented by letting the Modules define the operations
+and once the module is engaged to a service the 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 engages them. Modules can not be added while the Axis2 is
+running but later they will be available once the system is restarted.</p>
+
+<h2><a name="bmDeployment"></a>Deployment</h2>
+
+<p>There deployment Model provides a concrete mechanism to configure Axis2.
+Deployment Model has four entities that provide the configuration.</p>
+
+<h3>The <em>axis2.xml</em> file</h3>
+
+<p>This file holds the global configuration for the client and server, and
+provide following information.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">The global parameters</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Registered transports in and transport
+ outs</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User defined Phase names</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modules that are engaged globally</p>
+ </li>
+ <li><p>Globally defines <a href="#mr">Message Receiver</a>s</p>
+ </li>
+</ol>
+
+<h3>Service Archive</h3>
+
+<p>Service archive must have a <em>META-INF/services.xml</em> file and may
+contain the dependent classes. the <em>services.xml</em> file has following
+information.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Service level parameters</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modules that are engaged Service level</p>
+ </li>
+ <li><p>Operations inside the Service</p>
+ </li>
+</ol>
+
+<h3>Module Archive</h3>
+
+<p>Module archive must have a <em>META-INF/module.xml</em> 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 started up the Axis2 ask the deployment model to create a
+Axis Configuration, the Deployment Model first find a <em>axis2.xml</em> file
+and build the global configuration. Then the Deployment check for the Module
+archives and then for the service archives, the corresponding services and
+Modules are added to the Axis Configuration. System will build Contexts on
+top of the Axis Configurations and the Axis2 is ready to send or receive the
+SOAP Message. The Hot deployment is allowed only for the Service and in that
+case a thread will check the repository repeatedly, and add the Service
+corresponds to the new found Service archives to the repository.</p>
+
+<h2><a name="bmWSDL"></a>WSDL and code generation</h2>
+
+<p>Although the basic objective of the code generation tool 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
+shows how this shows up in the architecture of the tool.</p>
+
+<p><img src="images/archi-guide/CodegenArchitecture.jpg" name="Graphic6"
+align="bottom" width="478" height="218" 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. Code generator uses the WOM (WSDL
+Object Model) internally to manipulate the WSDL and passes that information
+to the emitter which emits an XML. the XML is then parsed with the relevant
+XSL to generate the code. No matter what the language, the process is the
+same except for the template that is being used</p>
+
+<h2><a name="bmDB"></a>Data Binding</h2>
+
+<h3>Integration with the code generation engine</h3>
+
+<p>Axis2 M2 was released with code generation support but without data
+binding. The version 0.9 was shipped with data binding support with complete
+schema support. Such claim is made possible because of the fact that the data
+binding tool, xml-beans, has the full schema support. The original
+architecture of the code generation framework did not undergo significant
+changes because of the way that the code generation framework was originally
+designed. Data binding was incorporated as a pluggable extension to the code
+generation engine. Version 0.91 did not does not support SOAP encoding. It
+only supports RPC literal or document literal massages.</p>
+
+<p><img src="images/codegen.gif" name="Graphic7" align="bottom" width="406"
+height="467" border="0"></p>
+
+<h3>Serialization and De-Serialization</h3>
+
+<p>Xml-beans supports StAX API and AXIOM is based on a 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 supporter classes for each WSDL operation that will
+have the utility methods that can de-serialize the 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 there will
+be an echoStringDatabindingSupporter.java class generated that will have
+methods that will look like the following.</p>
+
+<p>public static org.apache.axis2.om.OMElement
+toOM(org.soapinterop.xsd.EchoStringParamDocument param) : This method will
+handle the serialization.</p>
+
+<p>public static org.apache.xmlbeans.XmlObject
+fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) : This
+method will handle the de-serialization.</p>
+
+<p>public static org.apache.xmlbeans.XmlObject getTestObject(java.lang.Class
+type) : This will be a utility method that can be used to create sample
+objects of the given data bound object.</p>
+
+<h2><a name="bmClientAPI"></a>Client API</h2>
+
+<p>There are three parameters that decide the nature of the Web Service
+interaction.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Message Exchange Pattern</p>
+ </li>
+ <li><p style="margin-bottom: 0in">The Behavior of the transport. Does it
+ act one-way or two way</p>
+ </li>
+ <li><p>Synchronous/ Asynchronous behavior of the Client API</p>
+ </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 support only two most widely
+used Message Exchange Patterns.</p>
+
+<p>Two supported transports are One-Way and the Request-Response scenarios in
+the Client API, the implementation is based on a class called
+<code>MEPClient</code> and there are extensions for each Message Exchange
+Pattern that Axis2 Client API supports.</p>
+
+<h3>One Way Messaging Support</h3>
+
+<p>The One-Way support is provided by the <code>InOnlyMEPClient</code> and
+Axis2 provides a class called <code>MessageSender</code> that provides a much simpler
+interface for the user. The Axis2 supports 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>
+
+<h3>Request Response Messaging Support</h3>
+
+<p>The Request-Response support is provided by the
+<code>InOutMEPClient</code> and Axis2 provides a class called
+<code>Call</code> that provides a much simpler interface for the
+user. The Client API has four ways to configure a given Message Exchange</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Blocking or Non-Blocking nature - this
+ can be decided by using <code>invokeBlocking()</code> or
+ <code>invokeNonBlocking()</code> methods</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Sender transport - transport use to send
+ the SOAP Message</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Listener transport - transport the
+ Response is received</p>
+ </li>
+ <li><p>Use Separate Channel - does the response is send over a separate
+ transport connection or not, this can be false only when sender an
+ listener transport is same and is a two way transport.</p>
+ </li>
+</ol>
+
+<p>Depend on the values for the above four parameter, Axis2 behave
+differently</p>
+
+<h2><a name="bmTransports"></a>Transports</h2>
+
+<p>Axis2 has two basic constructs for transports, named as Transport In
+Configuration and Transport Out Configuration. The <a
+href="#messageContext">Message Context</a> has two fields to put the input
+and the out put transport to be used. Axis behaves according to the transport
+that is specified in each of the fields.</p>
+
+<p>SOAP Message is arrived at the Server side, the incoming transport is
+decided by the Transport Listener that accepts the incoming SOAP Message. The
+transports for the subsequent SOAP Messages that are related to the first
+message, are decided based on the addressing parameters.</p>
+
+<p>At the Client Side the user is free to specify the transport to be used,
+as in the Server side the transport for the subsequent SOAP Messages are
+decided by the addressing.</p>
+
+<p>There Transport In Configuration and the Transport Out Configuration
+contains following information.</p>
+<ol>
+ <li><p style="margin-bottom: 0in">Transport Sender in Out Configuration,
+ Transport Listener in the TransportIn Configuration</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Parameters of the transport</p>
+ </li>
+ <li><p>Transport Handlers</p>
+ </li>
+</ol>
+
+<p>Transport Sender send the SOAP Message over a given transport, each and
+every transport Out Configuration should define a transport Sender that send
+the transport.</p>
+
+<p>Transport Receiver waits for the SOAP Messages and for each SOAP Message
+that arrives, uses the <i>In Pipe</i> to process the SOAP Message.</p>
+
+<p>Axis2 Presently support the following transports</p>
+<ol>
+ <li><p style="margin-bottom: 0in">HTTP - The HTTP transport, the transport
+ Listener is a Servlet or a Simple HTTP server provided by Axis2. The
+ transport Sender uses sockets to connect and send the SOAP Message.
+ Currently we have the commons-HTTP-client based HTTP Transport sender as
+ the default transport</p>
+ </li>
+ <li><p style="margin-bottom: 0in">TCP - This is the most simplest
+ transport, but needed the addressing support to be functional.</p>
+ </li>
+ <li><p>SMTP - This work off a single email account, Transport Receiver is a
+ tread that checks for emails in fixed time intervals.</p>
+ </li>
+</ol>
+</body>
+</html>