| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2017-05-06 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="Date-Revision-yyyymmdd" content="20170506" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Apache Axis2 – Axis2 Architecture Guide</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> |
| <meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" /><meta content="20050916;22455288" /> </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2017-05-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 1.7.5<span class="divider">|</span></li> |
| <li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li> |
| <li class="active ">Axis2 Architecture Guide</li> |
| </ul> |
| </div> |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Axis2/Java</li> |
| <li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li> |
| <li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li> |
| <li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a> |
| <ul class="nav nav-list"> |
| <li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li> |
| <li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li> |
| <li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li> |
| <li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li> |
| <li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li> |
| <li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li> |
| <li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li> |
| <li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li> |
| <li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li> |
| <li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li> |
| </ul> |
| </li> |
| <li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li> |
| <li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li> |
| <li class="nav-header">Documentation</li> |
| <li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li> |
| <li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> |
| <li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li> |
| <li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li> |
| <li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li> |
| <li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li> |
| <li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li> |
| <li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li> |
| <li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li> |
| <li class="nav-header">Resources</li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> |
| <li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li> |
| <li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li> |
| <li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li> |
| <li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li> |
| <li class="nav-header">Get Involved</li> |
| <li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li> |
| <li><a href="../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> |
| <li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> |
| <li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li> |
| <li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li> |
| <li class="nav-header">Project Information</li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> |
| <li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li> |
| <li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li> |
| <li class="nav-header">Apache</li> |
| <li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> |
| <li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li> |
| </ul> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </div> |
| <div id="bodyColumn" class="span10" > |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| |
| |
| <h1 align="center">Apache Axis2 Architecture Guide</h1> |
| |
| <p>This document gives an introduction to Axis2's modular |
| architecture with explanations on every module.</p> |
| |
| <div class="section"> |
| <h2><a name="Contents"></a>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 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 <i>axis2.xml</i> 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" id="bmBP"></a> |
| |
| <div class="section"> |
| <h2><a name="The_Big_Picture"></a>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 class="externalLink" 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" id="requirements"></a> |
| |
| <div class="section"> |
| <h2><a name="Requirement_of_Axis2"></a>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 src="images/archi-guide/soap.gif" alt="" align="bottom" width="691" height="319" border="0" id="Graphic1" /></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 style="list-style-type: decimal"> |
| |
| <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 class="externalLink" href="http://www.w3.org/TR/wsdl">WSDL</a>, <a class="externalLink" href="http://www.w3.org/TR/soap/">SOAP</a> and <a class="externalLink" href="http://www.w3.org/Submission/ws-addressing/">WS-Addressing</a>. |
| Other specifications like JAX-RPC, <a class="externalLink" href="http://java.sun.com/webservices/saaj/index.jsp">SAAJ</a> and |
| <a class="externalLink" href="http://www.w3.org/Submission/WS-Policy/">WS-Policy</a> are |
| layered on top of the Core Architecture.</p> |
| <a name="thearchi" id="thearchi"></a> |
| |
| <div class="section"> |
| <h2><a name="Axis2_Architecture"></a>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 |
| these core modules.</p> |
| <a name="bmcore" id="bmcore"></a> |
| |
| <div class="section"> |
| <h3><a name="Core_Modules:"></a>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 class="externalLink" href="http://ws.apache.org/axiom/">AXIOM</a> or AXis |
| Object Model) to provide a simple API for SOAP and XML info-set. It |
| hides the complexities of efficient XML processing within its |
| 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 class="externalLink" 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" id="bmother"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Other_Modules:"></a>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 |
| simplifies the service deployment and the service invocation, |
| increasing 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, whereas data |
| binding extends it to make it more convenient to 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" width="426" alt="" height="189" border="0" align="bottom" usemap="#Graphic2Map" id="Graphic2" /></p> |
| <a name="bmInfoMod" id="bmInfoMod"></a> |
| </div> |
| <div class="section"> |
| <h2><a name="Information_Model"></a>Information Model</h2> |
| |
| <p>The 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" align="bottom" alt="" width="400" height="443" border="0" id="Graphic3" /></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 objects that can have more than one instance |
| (e.g., Message Contexts).</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. This flexibility |
| could be the <i>Achilles heel</i> for the system, however, as |
| searches are expensive, especially for parameters that turn out not |
| to exist. Yet in the final analysis, the Axis Team believes that |
| this flexibility serves developers better overall.</p> |
| |
| <table border="0" class="table table-striped" width="955"> |
| <col width="112" /> |
| <col width="371" /> |
| <col width="103" /> |
| <col width="336" /> |
| <tbody> |
| |
| <tr class="a"> |
| |
| <td><b>Context</b></td> |
| |
| <td><b>Description</b></td> |
| |
| <td><b>Configuration</b></td> |
| |
| <td><b>Description</b></td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <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, services, etc.</p> |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <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 belongs 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 class="b"> |
| |
| <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 class="a"> |
| |
| <td width="112"> |
| |
| <p>Operation Context</p> |
| </td> |
| |
| <td width="371"> |
| |
| <p>Holds the information about the current MEP instance, maintains |
| 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 class="b"> |
| |
| <td width="112"><a name="messageContext" id="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" id="bmXML"></a> |
| |
| <div class="section"> |
| <h2><a name="XML_Processing_Model"></a>XML Processing Model</h2> |
| |
| <p>As mentioned above, the XML processing model of Axis2 has become |
| a separate sub-project, called <a class="externalLink" href="http://ws.apache.org/axiom/">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" id="bmSOAPPM"></a> |
| |
| <div class="section"> |
| <h2><a name="SOAP_Processing_Model"></a>SOAP Processing Model</h2> |
| |
| <p><img src="images/archi-guide/soap-processing.gif" alt="" align="bottom" width="755" height="348" border="0" id="Graphic4" /></p> |
| |
| <p>The architecture identified two basic actions a SOAP processor |
| should perform, sending and receiving SOAP messages. The |
| architecture provides two pipes (or 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 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 scope 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> activates. The <i>Out Pipe</i> will invoke 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 <i>In Pipe</i> |
| 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 do 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 called 'phases' within Axis2. A Handler |
| always runs inside a specific 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" id="default"></a> |
| |
| <div class="section"> |
| <h3><a name="Axis2_Default_Processing_Model"></a>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 style="list-style-type: decimal"> |
| |
| <li>Dispatchers - Finds the service and the operation the SOAP |
| message is directed to. Dispatchers always run on the |
| <i>In-Pipe</i> 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 class="externalLink" href="http://wso2.org/library/176"> |
| Dispatching</a>)</li> |
| </ol> |
| |
| <ul> |
| |
| <li><a name="mr" id="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" id="incomingsoap"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Processing_an_Incoming_SOAP_Message"></a>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 style="list-style-type: decimal"> |
| |
| <li><b>Transport Phase</b> - 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 contexts, etc.</li> |
| |
| <li><b>Pre-Dispatch Phase</b>- 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><b>Dispatch Phase</b> - 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 |
| return a "service not found' error.</li> |
| |
| <li><b>User Defined Phases</b> - Users can engage their |
| custom handlers here.</li> |
| |
| <li><b>Message Validation Phase</b> - Once the user level |
| execution has taken place, this phase validates whether SOAP |
| Message Processing has taken place correctly.</li> |
| |
| <li><b>Message Processing Phase</b> - 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 processing logic in each of |
| these phases.</p> |
| <a name="outgoing" id="outgoing"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Processing_of_the_Outgoing_Message"></a>Processing of the Outgoing Message</h3> |
| |
| <p>The <i>Out Pipe</i> is simpler because the service and the |
| operation to dispatch are known by the time the pipe is executed. |
| The <i>Out Pipe</i> may be initiated by the</p> |
| <a href="#mr">Message Receiver</a> or the Client API |
| implementation. Phases of the <i>Out Pipe</i> are described |
| below: |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li><b>Message Initialize Phase</b> - First phase of the |
| <i>Out Pipe</i>. Serves as the placeholder for the custom |
| handlers.</li> |
| |
| <li><b>User Phases</b> - Executes handlers in |
| user-defined phases.</li> |
| |
| <li><b>Transports Phase</b> - 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" id="extending"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Extending_the_SOAP_Processing_Model"></a>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> |
| |
| <div class="section"> |
| <h4><a name="Extending_the_SOAP_Processing_Model_with_Handlers"></a>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 style="list-style-type: decimal"> |
| |
| <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" id="extendingwithmodules"></a> |
| </div> |
| <div class="section"> |
| <h4><a name="Extending_the_SOAP_Processing_Model_with_Modules"></a>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" id="bmDeployment"></a> |
| </div></div> |
| <div class="section"> |
| <h2><a name="Deployment"></a>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" id="xmlfile"></a> |
| |
| <div class="section"> |
| <h3><a name="The_axis2.xml_file"></a>The axis2.xml file</h3> |
| |
| <p>This file holds the global configuration for the client and |
| server, and provides the following information:</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <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" id="servicearchive"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Service_Archive"></a>Service Archive</h3> |
| |
| <p>The Service archive must have a <i>META-INF/services.xml</i> file and may |
| contain the dependent classes. Please see modules/kernel/resources/services.xsd in |
| the source distribution for the schema for services.xml. The <i>services.xml</i> file has |
| the following information.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <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" id="modulearchive"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Module_Archive"></a>Module Archive</h3> |
| |
| <p>Module archive must have a META-INF/<a href="../schemas/module.xsd">module.xml</a> file and dependent |
| classes. The <i>module.xml</i> 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" id="bmClientAPI"></a> |
| </div> |
| <div class="section"> |
| <h2><a name="Client_API"></a>Client API</h2> |
| |
| <p>There are three parameters that decide the nature of the Web |
| service interaction.</p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <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 built-in support for only the 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 <tt>ServiceClient</tt> and there are |
| extensions for each MEP that Axis2 Client API supports.</p> |
| <a name="oneway" id="oneway"></a> |
| |
| <div class="section"> |
| <h3><a name="One_Way_Messaging_Support"></a>One Way Messaging Support</h3> |
| |
| <p>The One-Way support is provided by the |
| <tt>fireAndForget</tt> method of <tt>ServiceClient</tt>. |
| 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" id="requestresponse"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="In-Out_Request_Response_Messaging_Support"></a>In-Out (Request Response) Messaging Support</h3> |
| |
| <p>The In-Out support is provided by the <tt>sendReceive()</tt> |
| 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 style="list-style-type: decimal"> |
| |
| <li>Blocking or Non-Blocking nature - this can be decided by using |
| <tt>sendReceive()</tt> or <tt>sendReceiveNonBlocking()</tt> |
| 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" id="bmTransports"></a> |
| </div> |
| <div class="section"> |
| <h2><a name="Transports"></a>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 output stream |
| 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 style="list-style-type: decimal"> |
| |
| <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 style="list-style-type: decimal"> |
| |
| <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>Local - This transport can be used for in-VM communication.</li> |
| |
| <li>Transports for TCP, SMTP, JMS and other protocols are available |
| from the <a class="externalLink" href="http://ws.apache.org/commons/transport/">WS-Commons Transport</a> |
| project.</li> |
| </ol> |
| <a name="bmWSDL" id="bmWSDL"></a> |
| |
| <div class="section"> |
| <h2><a name="Code_Generation"></a>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" alt="" align="bottom" border="0" id="Graphic6" /></p> |
| |
| <p>The fact here is that it is the same information that is |
| extracted from the WSDL no matter what output 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 in the desired output |
| language. No matter what the output language is, the process is the |
| same except for the XSL template that is used.</p> |
| <a name="bmDB" id="bmDB"></a> |
| |
| <div class="section"> |
| <h2><a name="Data_Binding"></a>Data Binding</h2> |
| |
| <div class="section"> |
| <h3><a name="Integration_with_the_Code_Generation_Engine"></a>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><b>The following diagram shows the structure:</b></p> |
| |
| <p><img src="images/codegen.gif" align="bottom" border="0" id="Graphic7" alt="" /></p> |
| |
| <p><b>The following databinding extensions are |
| available:</b></p> |
| |
| <ol style="list-style-type: decimal"> |
| |
| <li><b>ADB</b> - 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><b>XMLBeans</b> - XMLbeans claims that it supports |
| the complete schema specification, and it is preferred if full |
| schema support is needed!</li> |
| |
| <li><b>JAXB-RI</b> - JAXB2 support has been added in a |
| similar manner to XMLbeans and serves as another option for the |
| user</li> |
| |
| <li><b>JibX</b> - This is the most recent addition to the |
| family of databinding extensions, and it is also another option |
| users have for data binding.</li> |
| </ol> |
| <a name="serial" id="serial"></a> |
| </div> |
| <div class="section"> |
| <h3><a name="Serialization_and_De-Serialization_of_Data_bound_classes"></a>Serialization and De-Serialization of Data bound classes</h3> |
| |
| <p>AXIOM is based on the StAX API (Streaming API for XML). |
| Xml-beans also supports this API. Data binding in Axis2 is achieved |
| through interfacing the AXIOM with the Xml-beans using the StAX |
| API. 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 a data bound object and serialize from a |
| 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> |
| |
| <div> |
| <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></div> |
| </div> |
| </html> |
| </div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p>Copyright ©2004–2017 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |