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