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