You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ws.apache.org by ch...@apache.org on 2006/01/05 09:58:37 UTC
svn commit: r366125 [1/6] - in /webservices/site/trunk/targets/axis2: ./
0_93/ 0_93/adb/ 0_93/adb/images/ 0_93/sec-conf/ 0_93/tools/ M1/ adb/ api/
sec-conf/ tools/
Author: chinthaka
Date: Thu Jan 5 00:55:38 2006
New Revision: 366125
URL: http://svn.apache.org/viewcvs?rev=366125&view=rev
Log:
Site re-structuring.
Added:
webservices/site/trunk/targets/axis2/0_93/
webservices/site/trunk/targets/axis2/0_93/Axis2ArchitectureGuide.html
webservices/site/trunk/targets/axis2/0_93/ClientAPI.html
webservices/site/trunk/targets/axis2/0_93/CodegenToolReference.html
webservices/site/trunk/targets/axis2/0_93/CodegenToolReference.pdf (with props)
webservices/site/trunk/targets/axis2/0_93/CodegenTools-EclipsePlugin.html
webservices/site/trunk/targets/axis2/0_93/OMTutorial.html
webservices/site/trunk/targets/axis2/0_93/ServiceArchiveToolReference.html
webservices/site/trunk/targets/axis2/0_93/adb/
webservices/site/trunk/targets/axis2/0_93/adb/adb-codegen-integration.html
webservices/site/trunk/targets/axis2/0_93/adb/adb-howto.html
webservices/site/trunk/targets/axis2/0_93/adb/adb-tweaking.html
webservices/site/trunk/targets/axis2/0_93/adb/images/
webservices/site/trunk/targets/axis2/0_93/adb/images/ADB.jpg (with props)
webservices/site/trunk/targets/axis2/0_93/axis2config.html
webservices/site/trunk/targets/axis2/0_93/axis2tools.html
webservices/site/trunk/targets/axis2/0_93/http-transport.html
webservices/site/trunk/targets/axis2/0_93/installationguide.html
webservices/site/trunk/targets/axis2/0_93/mail-configuration.html
webservices/site/trunk/targets/axis2/0_93/mail-transport.html
webservices/site/trunk/targets/axis2/0_93/migration.html
webservices/site/trunk/targets/axis2/0_93/mtom-guide.html
webservices/site/trunk/targets/axis2/0_93/rest-ws.html
webservices/site/trunk/targets/axis2/0_93/sec-conf/
- copied from r366069, webservices/site/trunk/targets/axis2/sec-conf/
webservices/site/trunk/targets/axis2/0_93/security-module.html
webservices/site/trunk/targets/axis2/0_93/tcp-transport.html
webservices/site/trunk/targets/axis2/0_93/tools/
- copied from r366069, webservices/site/trunk/targets/axis2/tools/
webservices/site/trunk/targets/axis2/0_93/transport_howto.html
webservices/site/trunk/targets/axis2/0_93/userguide.html
webservices/site/trunk/targets/axis2/0_93/webadminguide.html
Removed:
webservices/site/trunk/targets/axis2/Axis2ArchitectureGuide.html
webservices/site/trunk/targets/axis2/ClientAPI.html
webservices/site/trunk/targets/axis2/CodegenToolReference.html
webservices/site/trunk/targets/axis2/CodegenToolReference.pdf
webservices/site/trunk/targets/axis2/CodegenTools-EclipsePlugin.html
webservices/site/trunk/targets/axis2/M1/
webservices/site/trunk/targets/axis2/OMTutorial.html
webservices/site/trunk/targets/axis2/ServiceArchiveToolReference.html
webservices/site/trunk/targets/axis2/adb/
webservices/site/trunk/targets/axis2/api/
webservices/site/trunk/targets/axis2/axis2config.html
webservices/site/trunk/targets/axis2/cvs-usage.html
webservices/site/trunk/targets/axis2/docs.html
webservices/site/trunk/targets/axis2/http-transport.html
webservices/site/trunk/targets/axis2/installationguide.htm
webservices/site/trunk/targets/axis2/installationguide.html
webservices/site/trunk/targets/axis2/mail-configuration.html
webservices/site/trunk/targets/axis2/mail-transport.html
webservices/site/trunk/targets/axis2/migration.html
webservices/site/trunk/targets/axis2/mtom-guide.html
webservices/site/trunk/targets/axis2/otherTutorials.html
webservices/site/trunk/targets/axis2/rest-ws.html
webservices/site/trunk/targets/axis2/sec-conf/
webservices/site/trunk/targets/axis2/security-module.html
webservices/site/trunk/targets/axis2/tcp-transport.html
webservices/site/trunk/targets/axis2/tools/
webservices/site/trunk/targets/axis2/transport_howto.html
webservices/site/trunk/targets/axis2/userguide.html
webservices/site/trunk/targets/axis2/webadminguide.htm
webservices/site/trunk/targets/axis2/webadminguide.html
Added: webservices/site/trunk/targets/axis2/0_93/Axis2ArchitectureGuide.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_93/Axis2ArchitectureGuide.html?rev=366125&view=auto
==============================================================================
--- webservices/site/trunk/targets/axis2/0_93/Axis2ArchitectureGuide.html (added)
+++ webservices/site/trunk/targets/axis2/0_93/Axis2ArchitectureGuide.html Thu Jan 5 00:55:38 2006
@@ -0,0 +1,471 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2 Architecture Guide - Axis 2.0</title><style type="text/css" media="all">
+ @import url("./style/maven-base.css");
+
+ @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">Last published: 20 December 2005
+ <span class="separator">|</span> Doc for 0.94-dev
+ </div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Download Axis2</a><ul><li class="none"><a href="download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2
Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="adb/adb-howto.html">ADB How-to</a></li><li class="none"><a href="security-module.html">WS-Security How-to</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</a><ul><li class="none"><a href="svn.html">Checkout the Source</a></li><li class="none"><a href="siteHowT
o.html">Build the Site</a></li><li class="none"><a href="guidelines.html">Developer Guidelines</a></li><li class="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="faq.html">FAQ</a></li><li class="none"><a href="thanks.html">Thanks</a></li></ul></li><li class="expanded"><a href="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens in a new window</li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><
a name="Axis2_Architecture_Guide"></a><h2>Axis2 Architecture Guide</h2><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
+ <li><p><a href="#bmBP">The Big Picture</a></p>
+ </li>
+ <li><p><a href="#bmInfoMod">Information Model</a></p>
+ </li>
+ <li><p><a href="#bmXML">XML Processing Model</a></p>
+ </li>
+ <li><p><a href="#bmSOAPPM">SOAP Processing Model</a></p>
+ </li>
+ <li><p><a href="#bmDeployment">Deployment</a></p>
+ </li>
+ <li><p><a href="#bmWSDL">WSDL and code generation</a></p>
+ </li>
+ <li><p><a href="#bmDB">Data Binding</a></p>
+ </li>
+ <li><p><a href="#bmClientAPI">Client API</a></p>
+ </li>
+ <li><p><a href="#bmTransports">Transports</a></p>
+ </li>
+</ul><p><br></br>
+<br></br>
+</p></div><div class="subsection"><a name="The_Big_Picture"></a><h3>The Big Picture</h3><p>Any architecture is a result of what that architecture should yield, the
+success of an architecture should be evaluated based on the requirements the
+architecture should meet. Let us start our journey into Axis2 looking at the
+requirements that are expected from Axis2.</p></div><div class="subsection"><a name="Requirement_of_Axis2"></a><h3>Requirement of Axis2</h3><p>In the SOAP terminology, a participant who is taking part in a Web Service
+interaction is known as a SOAP Node. Delivery of a single SOAP Message is
+defined based on two participants, SOAP Sender and SOAP Receiver. Each SOAP
+Message is sent by SOAP Sender and received by SOAP Receiver, and single SOAP
+delivery is the most basic unit that builds the Web Service interactions.</p><p>Each SOAP Node may be written in specific programming language, may it be
+Java, C++, .NET or Perl, the Web Services allow them to inter operate. This
+is possible because 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" name="Graphic1" align="bottom" width="691" height="319" border="0" alt=""></img></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>
+ <p style="margin-bottom: 0in">Provide a framework to process the SOAP
+ messages. The framework should be extensible and the users should be able
+ to extend the SOAP processing per service or per operation basis. Furthermore
+ it should be able to model different Message Exchange Patterns (MEP) using the
+ processing framework.</p>
+ </li>
+ <li>Ability to deploy a Web Services (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, WSDL, SOAP and WS-Addressing. Other
+specifications like JAX-RPC and SAAJ are layered on top of the Core
+Architecture. The WS-Policy might join the core specifications in the near
+future.</p></div><div class="subsection"><a name="Axis2__the_Architecture"></a><h3>Axis2, the Architecture</h3><p>Now that we have looked at the requirements of the Axis2 we can direct our
+attention to the Architecture.</p><p>Axis2 architecture lays out some principals to preserve the uniformity of
+the architecture. They are as follows.</p><ul>
+ <li><p style="margin-bottom: 0in">Axis2 architecture separates the logic
+ and the states. The code that does the processing is stateless inside Axis2.
+ This allows the code to be executed freely by parallel threads.</p>
+ </li>
+ <li>All the information is kept in one information model, this allows
+ the system to be suspended and resumed.</li>
+</ul><p>Axis2 architecture is modular and is broken down into
+seven modules.</p><ol>
+ <li><p style="margin-bottom: 0in">Information Model</p>
+ </li>
+ <li>XML processing Model</li>
+ <li>SOAP Processing Model</li>
+ <li>Deployment</li>
+ <li>WSDL and Code Generation</li>
+ <li>Client API</li>
+ <li>Transports</li>
+</ol><p><img src="images/archi-guide/all.png" name="Graphic2" width="426" height="189" border="0" align="bottom" usemap="#Graphic2Map" alt=""></img>
+ <map name="Graphic2Map">
+ <area shape="rect" coords="123,31,222,97" href="#bmInfoMod"></area>
+ <area shape="rect" coords="239,62,319,134" href="#bmXML"></area>
+ <area shape="rect" coords="127,112,218,177" href="#bmSOAPPM"></area>
+ <area shape="rect" coords="12,39,89,95" href="#bmDeployment"></area>
+ <area shape="rect" coords="0,108,94,156" href="#bmWSDL"></area>
+ <area shape="rect" coords="350,31,426,86" href="#bmClientAPI"></area>
+ <area shape="rect" coords="350,114,421,164" href="#bmTransports"></area>
+ </map>
+</p><p>Let us look in to the rationale behind each Module, and what each does.</p><p>Axis2 defines a model to handle the information and all the states are
+kept in this model. The model has a hierarchy for the information and the
+system manages the life cycle of the objects in this hierarchy.</p><p>Handling the SOAP Message is the most important and the most complex task,
+the efficiency of this is the single most important factor that decides the
+performance. It makes sense to delegate this task to a separate module, and
+that module(AXIOM) provides a simple API for SOAP and XML info-set while
+hiding the complexities of the efficient XML processing within the
+implementation.</p><p>SOAP Processing Model controls the execution of the processing, the model
+defines different phases the execution would walk through, and the user can
+extend the Processing Model at some specific places.</p><p>Axis2 define a transport framework that enables the user to use 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 new ones if and when it is needed.</p><p>Axis2 deployment model allows the user to deploy services, configure the
+transports, extend the SOAP Processing model per system basis, per service
+basis, and per operation basis.</p><p>Finally Axis2 provides a code generation tool that will generate server
+side and client side code along with a test case. The generated code would
+simplify the service deployment and the service invocation. This would make
+the Axis2 easier to use.</p></div><div class="subsection"><a name="Information_Model"></a><h3>Information Model</h3><p>Information Model has two main hierarchies, the Contexts and
+Descriptions.</p><p><img src="images/archi-guide/contexts.png" name="Graphic3" align="bottom" width="400" height="443" border="0" alt=""></img></p><p>This uses UML notations ( A ----<> B means B has 1 or more objects
+of A. A------>B means the given relationship holds between A and B.)</p><p>The two hierarchies are connected as shown in the above figure. The
+Description hierarchy represents the static data. This data may be loaded from
+a configuration file that exists throughout the lifetime of
+Axis2. Examples for such data would be deployed Web Services, operations,
+etc. On the other hand, the context hierarchy holds more dynamic information
+about 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 overrides the values in the upper levels.
+For an example when a value is looked up at the Message Context and it is
+not found, it would be looked up at the Operation Context etc, up the
+hierarchy. The Search is first done up the hierarchy, and if starting point
+is a Context then it is search in the Description hierarchy as well.</p><p>This allows the user to declare and override values, result being a very
+flexible configuration model. The flexibility could be the Achilles heel for
+the system, as the search, specially for something that does not exist is
+expensive, yet in the final analysis developers believe that the flexibility
+would serve better in this instant.</p><table class="bodyTable">
+ <col width="112"></col><col width="371"></col><col width="103"></col><col width="336"></col><tbody>
+ <tr class="a">
+ <td width="112"><p>Configuration Context</p>
+ </td>
+ <td width="371"><p>Holds the current state of execution. A deep copy of
+ this would essentially make a copy of Axis2.</p>
+ </td>
+ <td width="103"><p>Axis Configuration</p>
+ </td>
+ <td width="336"><p>Holds all global configurations. Transports, global
+ modules, parameters and Services.</p>
+ </td>
+ </tr>
+ <tr class="b">
+ <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(in
+ the same service group) in a single interaction.</p>
+ </td>
+ <td width="103"><p>ServiceGroup Description</p>
+ </td>
+ <td width="336"><p>Holds deployment time information about a particular
+ service group.</p>
+ </td>
+ </tr>
+ <tr class="a">
+ <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 that belong to the same service, within a single
+ interaction.</p>
+ </td>
+ <td width="103"><p>Service Description</p>
+ </td>
+ <td width="336"><p>Hold the Operations and the service level
+ configurations</p>
+ </td>
+ </tr>
+ <tr class="b">
+ <td width="112"><p>Operation Context</p>
+ </td>
+ <td width="371"><p>Holds the information about the current MEP
+ instance, maintain the Messages in the current MEP etc.</p>
+ </td>
+ <td width="103"><p>Operation Description</p>
+ </td>
+ <td width="336"><p>Holds the operation level configurations</p>
+ </td>
+ </tr>
+ <tr class="a">
+ <td width="112"><p><a name="messageContext"></a>Message Context</p>
+ </td>
+ <td width="371"><p>Holds all the information about the Message
+ currently being executed.</p>
+ </td>
+ <td width="103"><p>Message Description</p>
+ </td>
+ <td width="336"><p>Do not hold any information as yet, but can be used
+ as a future extension point.</p>
+ </td>
+ </tr>
+ </tbody>
+</table></div><div class="subsection"><a name="XML_Processing_Model"></a><h3>XML Processing Model</h3><p>Please refer to the <a href="OMTutorial.html">OM Tutorial</a></p></div><div class="subsection"><a name="SOAP_Processing_Model"></a><h3>SOAP Processing Model</h3><p><img src="images/archi-guide/soap-processing.gif" name="Graphic4" align="bottom" width="755" height="348" border="0" alt=""></img></p><p>The architecture identified two basic actions a SOAP processor should
+perform, sending and receiving SOAP messages. The architecture provides two
+Pipes (also named 'Flows'), to perform these two basic actions. Axis Engine
+or the driver of Axis2 defines two methods send() and receive() to implement
+these two Pipes. The two pipes are named <i>In Pipe</i> and <i>Out Pipe</i>,
+and the complex Message Exchange Patterns 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 In Pipe 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 of 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><p>Following figure shows the two pipes with their predefined Phases, the
+user defined Phases would fit in to the User Phases.</p><p><img src="images/archi-guide/phases.png" name="Graphic5" align="bottom" width="525" height="226" border="0" alt=""></img></p></div><div class="subsection"><a name="Axis2_Default_Processing_Model"></a><h3>Axis2 Default Processing Model</h3><p>Axis2 has the, some inbuilt Handlers that run in inbuilt Phases and they
+create the default configuration for the Axis2, we will be looking more in to
+how to extend the default processing Model in the next section.</p><p>There are four special handlers defined in Axis2.</p><ol>
+ <li>
+ <p style="margin-bottom: 0in">Dispatchers - Finds the service and the operation the SOAP
+ message is directed to, always run on the In-Pipe and inside the Dispatch
+ Phase. The in-built dispatchers dispatches to a particular operation depending on various conditions like WS-Addressing information, URI information, SOAP action information, etc., </p>
+ </li>
+ <li><p style="margin-bottom: 0in"><a name="mr"></a>Message Receiver -
+ Consume the SOAP Message and run on the Message Processing Phase in the
+ inflow</p>
+ </li>
+ <li><p>Transport Sender - Send the SOAP message to the SOAP endpoint the
+ message is destined to. Always runs on the</p>
+ </li>
+</ol></div><div class="subsection"><a name="Processing_an_Incoming_SOAP_Message"></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 is arrived the transport Headers
+are parsed and a <a href="#messageContext">Message Context</a> is created for
+the incoming SOAP Message. The the <i>In Pipe</i> is executed with the
+Message Context. Let us see what would happen at the each Phase of the
+execution, this process my happen in either in the server or the Client,
+there is a special case of using the two way transport where the first four
+phases in the In-Phase most likely to do nothing.</p><ol>
+ <li><p style="margin-bottom: 0in">Transport Phase - The Handlers in the
+ transport Phase are taken from the transport configuration associated,
+ they are executed according to the Phase rules.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Pre-Dispatch Phase- The Handlers that
+ goes there must be engaged globally (for all services) as the Service
+ does not known at this point. The best example for them would be,
+ Addressing Handlers and may be security Handlers if the Addressing
+ Headers are encrypted.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Dispatch Phase - The Dispatchers are run
+ in this Phases and find the Service if the service is not found
+ already.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Post-Dispatch Phase - This phase check
+ weather the service is found, if the service has not found by this point
+ the execution will halt and send a "service not found error". Policy
+ Determination Phase - This Phase does nothing for the time being, this is
+ placed for the implementing the Policy</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User Defined Phases - User defined Phases
+ are executed here.</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Message Validation Phase - Once the user
+ level execution is taken place, this Phase will validates has the SOAP
+ Message Processing has taken place correctly. For an example the must
+ understand processing would happen here.</p>
+ </li>
+ <li><p>Message Processing Phase - The Business logic of the SOAP message,
+ executed here, the a <a href="#mr">Message Receiver</a> is registered
+ with a each Operation. The Message receiver associated with the each
+ operation would be executed as the last Handler of this Phase.</p>
+ </li>
+</ol><p>There may be other handlers in the any of the these Phases, users may
+employ custom Handlers to override the mechanics in the each of these Phases.
+If there is a response message, that would be initiated by the <a href="#mr">Message Receiver</a>, yet the architecture is not aware of the
+response message and merely invoke the <a href="#mr">Message Receiver</a>.</p></div><div class="subsection"><a name="Processing_of_the_Outgoing_Message"></a><h3>Processing of the Outgoing Message</h3><p>Out pipe is simpler because the Service and the Operation to dispatch is
+known by the time the pipe is executed. The Out pipe may be initiated by the
+<a href="#mr">Message Receiver</a> or the Client API implementation.</p><ol>
+ <li><p style="margin-bottom: 0in">Message Initialize Phase - Fist Phase of
+ the out pipe, this serves as the placeholder for the custom Handlers</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Policy Determination Phase - Just like in
+ the in-pipe this is not implemented and suppose to serve as a extension
+ point</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User Phases - This executes Handlers in
+ user define Phases</p>
+ </li>
+ <li><p>Transports Phase - Execute any transport Handlers taken from the
+ associated transport configuration and the last handler would be a
+ transport Sender which would send the SOAP message to the target end
+ point</p>
+ </li>
+</ol></div><div class="subsection"><a name="Extending_SOAP_Processing_Model"></a><h3>Extending SOAP Processing Model</h3><p>We discussed the default processing model of the Axis2, ability to extend
+the model has been the whole point of spending the energy on the SOAP
+processing model. We shall discuss the extension mechanism for the SOAP
+processing model now.</p><p>Idea behind making each step of the SOAP processing in terms of Handlers
+(inbuilt ones we discuss earlier) and placing them in the Phases is to allow
+Handlers to be placed between those Handlers and to override or affect the
+default mechanics. There are two ways the to extend the SOAP Processing
+Model.</p></div><div class="subsection"><a name="Extending_the_SOAP_Processing_Model_with_Handlers"></a><h3>Extending the SOAP Processing Model with Handlers</h3><p>The Handlers can specify the Phase they need to be run, further more they
+can specify the there location inside a phase via the following
+information.</p><ol>
+ <li><p style="margin-bottom: 0in">Handler should run as the first in the
+ phases</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Handler should run as the last in the
+ Phases</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Handler should run before a given
+ Handlers</p>
+ </li>
+ <li><p>Handler should run after a Given Handler</p>
+ </li>
+</ol></div><div class="subsection"><a name="Extending_the_SOAP_Processing_Model_with_Modules"></a><h3>Extending the SOAP Processing Model with Modules</h3><p>SOAP processing Model defines a logical entity called a module that
+encapsulates two entities, Handlers and Web Service Operations. The Handlers
+will act in the same way as explained in the first method.</p><p>Apart from the extension mechanism based on the Handlers, the WS-*
+specifications suggest a requirement for add new Operations using modules.
+For an example once a user add a Reliable Messaging capability to a Service,
+the "Create Sequence" operation needs to be available to the service end
+point. This can be implemented by letting the Modules define the operations
+and once the module is engaged to a service the operations will be added to
+that service.</p><p>A service, operations or the system may engage a module, once the module
+is engaged the handlers and the operations defined in the module are added to
+the entity that engages them. Modules can not be added while the Axis2 is
+running but later they will be available once the system is restarted.</p></div><div class="subsection"><a name="Deployment"></a><h3>Deployment</h3><p>There deployment Model provides a concrete mechanism to configure Axis2.
+Deployment Model has four entities that provide the configuration.</p></div><div class="subsection"><a name="The__file"></a><h3>The file</h3><p>This file holds the global configuration for the client and server, and
+provide following information.</p><ol>
+ <li><p style="margin-bottom: 0in">The global parameters</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Registered transports in and transport
+ outs</p>
+ </li>
+ <li><p style="margin-bottom: 0in">User defined Phase names</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modules that are engaged globally</p>
+ </li>
+ <li><p>Globally defines <a href="#mr">Message Receiver</a>s</p>
+ </li>
+</ol></div><div class="subsection"><a name="Service_Archive"></a><h3>Service Archive</h3><p>Service archive must have a <em>META-INF/services.xml</em> file and may
+contain the dependent classes. the <em>services.xml</em> file has following
+information.</p><ol>
+ <li><p style="margin-bottom: 0in">Service level parameters</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Modules that are engaged Service level</p>
+ </li>
+ <li><p>Operations inside the Service</p>
+ </li>
+</ol></div><div class="subsection"><a name="Module_Archive"></a><h3>Module Archive</h3><p>Module archive must have a <em>META-INF/module.xml</em> file and dependent
+classes the <em>module.xml</em> file has Module parameters and the Operations
+defined in the module.</p><p>When the system started up the Axis2 ask the deployment model to create a
+Axis Configuration, the Deployment Model first find a <em>axis2.xml</em> file
+and build the global configuration. Then the Deployment check for the Module
+archives and then for the service archives, the corresponding services and
+Modules are added to the Axis Configuration. System will build Contexts on
+top of the Axis Configurations and the Axis2 is ready to send or receive the
+SOAP Message. The Hot deployment is allowed only for the Service and in that
+case a thread will check the repository repeatedly, and add the Service
+corresponds to the new found Service archives to the repository.</p></div><div class="subsection"><a name="WSDL_and_code_generation"></a><h3>WSDL and code generation</h3><p>Although the basic objective of the code generation tool has not changed,
+the Code generation module of Axis2 has taken a different approach to
+generate code. Primarily the change is in the use of templates, namely XSL
+templates which gives the code generator the flexibility to generate code in
+multiple languages.</p><p>The basic approach is to set the code generator to generate an XML and
+parse it with a template to generate the code file. The following figure
+shows how this shows up in the architecture of the tool.</p><p><img src="images/archi-guide/CodegenArchitecture.jpg" name="Graphic6" align="bottom" width="478" height="218" border="0" alt=""></img></p><p>The fact here is that it is the same information that is extracted from
+the WSDL no matter what code is generated. Code generator uses the WOM (WSDL
+Object Model) internally to manipulate the WSDL and passes that information
+to the emitter which emits an XML. the XML is then parsed with the relevant
+XSL to generate the code. No matter what the language, the process is the
+same except for the template that is being used</p></div><div class="subsection"><a name="Data_Binding"></a><h3>Data Binding</h3></div><div class="subsection"><a name="Integration_with_the_code_generation_engine"></a><h3>Integration with the code generation engine</h3><p>Axis2 M2 was released with code generation support but without data
+binding. The version 0.9 was shipped with data binding support with complete
+schema support. Such claim is made possible because of the fact that the data
+binding tool, xml-beans, has the full schema support. The original
+architecture of the code generation framework did not undergo significant
+changes because of the way that the code generation framework was originally
+designed. Data binding was incorporated as a pluggable extension to the code
+generation engine. Version 0.91 did not does not support SOAP encoding. It
+only supports RPC literal or document literal massages.</p><p><img src="images/codegen.gif" name="Graphic7" align="bottom" width="406" height="467" border="0" alt=""></img></p></div><div class="subsection"><a name="Serialization_and_De-Serialization"></a><h3>Serialization and De-Serialization</h3><p>Xml-beans supports StAX API and AXIOM is based on a StAX API. Data binding
+in Axis2 is achieved through interfacing the AXIOM with the Xml-beans using
+the StAX API which is supported by both parties. At the time of the code
+generation there will be supporter classes for each WSDL operation that will
+have the utility methods that can de-serialize the from AXIOM to data bound
+object and serialize from data bound object to AXIOM. For example if the WSDL
+has an operation called "echoString", once the code is generated there will
+be an echoStringDatabindingSupporter.java class generated that will have
+methods that will look like the following.</p><p>public static org.apache.axis2.om.OMElement
+toOM(org.soapinterop.xsd.EchoStringParamDocument param) : This method will
+handle the serialization.</p><p>public static org.apache.xmlbeans.XmlObject
+fromOM(org.apache.axis2.om.OMElement param, java.lang.Class type) : This
+method will handle the de-serialization.</p><p>public static org.apache.xmlbeans.XmlObject getTestObject(java.lang.Class
+type) : This will be a utility method that can be used to create sample
+objects of the given data bound object.</p></div><div class="subsection"><a name="Client_API"></a><h3>Client API</h3><p>There are three parameters that decide the nature of the Web Service
+interaction.</p><ol>
+ <li><p style="margin-bottom: 0in">Message Exchange Pattern</p>
+ </li>
+ <li><p style="margin-bottom: 0in">The Behavior of the transport. Does it
+ act one-way or two way</p>
+ </li>
+ <li><p>Synchronous/ Asynchronous behavior of the Client API</p>
+ </li>
+</ol><p>Variations of the three parameters can result in indefinite number of
+scenarios, even though Axis2 is built on a core that support any messaging
+interaction, the developers were compelled to support only two most widely
+used Message Exchange Patterns.</p><p>Two supported transports are One-Way and the Request-Response scenarios in
+the Client API, the implementation is based on a class called
+<code>MEPClient</code> and there are extensions for each Message Exchange
+Pattern that Axis2 Client API supports.</p></div><div class="subsection"><a name="One_Way_Messaging_Support"></a><h3>One Way Messaging Support</h3><p>The One-Way support is provided by the <code>InOnlyMEPClient</code> and
+Axis2 provides a class called <code>MessageSender</code> that provides a much simpler
+interface for the user. The Axis2 supports HTTP/SMTP and TCP transports, in
+the case of the HTTP transport the return channel is not used and the HTTP
+202 OK is returned in the return Channel.</p></div><div class="subsection"><a name="Request_Response_Messaging_Support"></a><h3>Request Response Messaging Support</h3><p>The Request-Response support is provided by the
+<code>InOutMEPClient</code> and Axis2 provides a class called
+<code>Call</code> that provides a much simpler interface for the
+user. The Client API has four ways to configure a given Message Exchange</p><ol>
+ <li><p style="margin-bottom: 0in">Blocking or Non-Blocking nature - this
+ can be decided by using <code>invokeBlocking()</code> or
+ <code>invokeNonBlocking()</code> methods</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Sender transport - transport use to send
+ the SOAP Message</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Listener transport - transport the
+ Response is received</p>
+ </li>
+ <li><p>Use Separate Channel - does the response is send over a separate
+ transport connection or not, this can be false only when sender an
+ listener transport is same and is a two way transport.</p>
+ </li>
+</ol><p>Depend on the values for the above four parameter, Axis2 behave
+differently</p></div><div class="subsection"><a name="Transports"></a><h3>Transports</h3><p>Axis2 has two basic constructs for transports, named as Transport In
+Configuration and Transport Out Configuration. The <a href="#messageContext">Message Context</a> has two fields to put the input
+and the out put transport to be used. Axis behaves according to the transport
+that is specified in each of the fields.</p><p>SOAP Message is arrived at the Server side, the incoming transport is
+decided by the Transport Listener that accepts the incoming SOAP Message. The
+transports for the subsequent SOAP Messages that are related to the first
+message, are decided based on the addressing parameters.</p><p>At the Client Side the user is free to specify the transport to be used,
+as in the Server side the transport for the subsequent SOAP Messages are
+decided by the addressing.</p><p>There Transport In Configuration and the Transport Out Configuration
+contains following information.</p><ol>
+ <li><p style="margin-bottom: 0in">Transport Sender in Out Configuration,
+ Transport Listener in the TransportIn Configuration</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Parameters of the transport</p>
+ </li>
+ <li><p>Transport Handlers</p>
+ </li>
+</ol><p>Transport Sender send the SOAP Message over a given transport, each and
+every transport Out Configuration should define a transport Sender that send
+the transport.</p><p>Transport Receiver waits for the SOAP Messages and for each SOAP Message
+that arrives, uses the <i>In Pipe</i> to process the SOAP Message.</p><p>Axis2 Presently support the following transports</p><ol>
+ <li><p style="margin-bottom: 0in">HTTP - The HTTP transport, the transport
+ Listener is a Servlet or a Simple HTTP server provided by Axis2. The
+ transport Sender uses sockets to connect and send the SOAP Message.
+ Currently we have the commons-HTTP-client based HTTP Transport sender as
+ the default transport</p>
+ </li>
+ <li><p style="margin-bottom: 0in">TCP - This is the most simplest
+ transport, but needed the addressing support to be functional.</p>
+ </li>
+ <li><p>SMTP - This work off a single email account, Transport Receiver is a
+ tread that checks for emails in fixed time intervals.</p>
+ </li>
+</ol></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/site/trunk/targets/axis2/0_93/ClientAPI.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/0_93/ClientAPI.html?rev=366125&view=auto
==============================================================================
--- webservices/site/trunk/targets/axis2/0_93/ClientAPI.html (added)
+++ webservices/site/trunk/targets/axis2/0_93/ClientAPI.html Thu Jan 5 00:55:38 2006
@@ -0,0 +1,148 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis 2.0 - Axis 2.0 Client API</title><style type="text/css" media="all">
+ @import url("./style/maven-base.css");
+
+ @import url("./style/maven-theme.css");</style><link rel="stylesheet" href="./style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/" id="projectLogo"><img alt="Axis2.0" src="http://ws.apache.org/axis/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 28 March 2005
+ | Doc for M1</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="index.html">Home</a></li><li class="expanded"><a href="">Get Invloved</a><ul><li class="none"><a href="overview.html">Overview</a></li><li class="none"><a href="svn.html">SVN Repository</a></li><li class="none"><a href="guidelines.html">Guide Lines</a></li><li class="none"><a href="refLib.html">Reference Library</a></li><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="siteHowTo.html">How to build site</a></li></ul></li><li class="expanded"><a href="">References</a><ul><li class="none"><a href="docs.html">Documentation</a></li><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a>
</li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="ClientAPI.html">Client API Tutorial</a></li><li class="none"><a href="api/index.html">Complete API</a></li></ul></li><li class="expanded"><a href="">Downloads</a><ul><li class="none"><a href="releases.html">Releases</a></li><li class="none"><a href="interim.html">Interim Drops</a></li><li class="none"><a href="cvs-usage.html">Source Code</a></li></ul></li><li class="expanded"><a href="">Modules</a><ul><li class="none"><a href="multiproject/axis2-core/index.html">Core</a></li><li class="none"><a href="multiproject/axis2-deployment/index.html">Deployment</a></li><li class="none"><a href="multiproject/axis2-om/index.html">OM</a></li><li class="none"><a href="multiproject/axis2-wsdl/index.html">WSDL</a></li><li class="none"><a href="multiproject/axis2-samples/index.html">Samples</a></li></ul></li><li class="expanded"><a hre
f="">Project Information</a><ul><li class="none"><a href="mail-lists.html">Mailing Lists</a></li><li class="none"><a href="team-list.html">Project Team</a></li><li class="none"><a href="issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Introduction"></a><h2>Introduction</h2><p>Invocation of web service will lead to an exchange of messages between two or more parties. If we consider the general scenario where
+a client invokes a single service, the communication between them can be either one way or two-way. Depending on the way the client handles the invocation at the API level, whether the transport protocol used is unidirectional or bi-directional and the type of the service method, one can derive many interaction patterns between client and the service. Rest of the document will focus on identifying these possible break ups and
+on how they are supported in Apache Axis 2.</p><p>Note: Please note that through out the tutorial the words "Client" and the "Service" are used to represent
+"Web Service Client" and the "Web Service" respectively.</p></div><div class="section"><a name="Axis_2_Client_API"></a><h2>Axis 2 Client API</h2><p>Followings will decide the interaction patterns between client and the service.</p><ul>
+ <li>Client API </li>
+ <li>The Protocol used to send the SOAP Message</li>
+ <li>The type of the service method</li>
+</ul></div><div class="section"><a name="Client_API"></a><h2>Client API</h2><p>Clients can consume services which take almost no time to complete and the services take considerable amount of time to complete. So it?s important that the SOAP engine provides both blocking and non-blocking APIs for the client. This can be easily done in the API level. </p><p>With a blocking API client will hang till the operation completes. In other words once invoked, the client will keep blocking till it gets the response (if any) from the service.
+This is very useful method when invoking web services that do not take long time
+to complete and the hanging in the client side is negligible. This will be a huge drawback in the client side performance, if the operation takes considerable amount of time.</p><p>A non blocking API will provide the client to use a Callback mechanism (or polling mechanism) to get the responses (if any) for a service invocation. Client gets this response it two ways. Both ways client has to register a call back with the SOAP engine.</p><ul>
+<li>Client keep on polling the call back object it registers with the SOAP engine,
+using the isComplete(). If isComplete() returns true, client get the result, if any, through getResult() which returns an AsyncResult object.
+</li><li>Upon receipt of the response, if any, SOAPEngine calls the onComplete(AsyncResult) of the call back object. </li></ul><p>Note that client can adopt any one of the above two methods, independent of the way service has been implemented.</p></div><div class="section"><a name="The_Protocol_Use_to_Send_the_SOAP_Message"></a><h2>The Protocol Use to Send the SOAP Message</h2><p>The protocol used to send the SOAP message can be categorized mainly in to two types.</p><ol>
+ <li>Unidirectional </li>
+ <li>Bi-Directional</li>
+</ol><p>With a unidirectional protocol (e.g. SMTP), client can simply invoke a service which has no response(s) to be sent in the same connection. But if the service is request/response in nature, it is required to use two separate connections of unidirectional protocol. However if the client needs only to send information, unidirectional is useful for that.</p><p>With a bidirectional protocol the client can retrieve the service response (if any) using the same connection. In this context HTTP is the most common bidirectional transport protocol. However the main drawback is the possibility of the timeouts that can happen. If the service takes some time to complete then there is a possibility of time out in the connection.</p><p>Bi-directional transport can be used to invoke one-way services as well. In this case the return path of the communication channel is not used. However since we are using a bi-directional protocol the return path can be used to carry the acceptance st
ate or a fault (if any). With reference to HTTP the
+"HTTP 202 Ok" header status will act as the acceptance state. The faults (if
+any) is also sent using the response path of the HTTP connection.</p></div><div class="section"><a name="Type_of_the_Service_Method"></a><h2>Type of the Service Method</h2><p>According to the WSDL definitions, there can be various Message Exchange Patterns defined for web services. These require the client to use possible invocation mechanism to handle the service invocations. For example if the client is invoking a service method which is defined as IN-ONLY operation, then the client should be able to use a method in the client API which is capable of handling this type of requests.</p><p>All these variations give rise to several Client API methods which will ultimately ease the service invocation for a web service client. For Axis 2, currently we are providing following methods in the Call API provided</p><ol>
+<li>Robust Invocation
+</li><li>Fire and Forget invocation
+</li><li>Blocking Invocation of type In-Out
+</li><li>Non Blocking Invocation of type In-Out </li>
+<ul>
+ <li> Method 1: Without a Client Side Listener</li>
+ <li> Method 2: With a Client Side Listener</li>
+</ul>
+</ol></div><div class="section"><a name="Architecture"></a><h2>Architecture</h2><p>Following architecture was derived for the Axis 2 client side, to support the above patterns the. A description of each component is given below.</p><p align="center">
+</p><p align="center"> <img height="315" src="images/image002.jpg" width="576" designtimeurl="images/image002.jpg" alt=""></img></p><p align="center">Figure 1 ? Axis Client Architecture</p><div class="subsection"><a name="Client"></a><h3>Client</h3><p>This is the web service client that actually utilizes the service.</p></div><div class="subsection"><a name="Call"></a><h3>Call</h3><p>This is the API that the Axis client should use to invoke the web services. Followings are the methods that the client can use in this API.</p>
+ <div class="source"><pre>
+<pre class="style1">public void setTo(EndpointReference EPR)
+public void getTO() </pre><pre class="style1">public void setTransportType(String transport)
+public void setListenerTransport(String Listenertransport, boolean useSeparateListener)
+public void setAction(String action)</pre>
+ <pre class="style1">public void sendAsync(SOAPEnvelope envelope) throws AxisFault
+ public void send(SOAPEnvelope envelope) throws AxisFault
+ public SOAPEnvelope sendReceive(SOAPEnvelope envelope) throws AxisFault
+ public void sendReceiveAsync(SOAPEnvelope envelope,final Callback callback) throws AxisFault
+ </pre>
+</pre></div>
+ </div><div class="subsection"><a name="Engine"></a><h3>Engine</h3><p>This is Axis 2 engine and it does not make any difference whether the engine is used in the client side or the server side. </p></div><div class="subsection"><a name="Correlator"></a><h3>Correlator</h3><p>Correlator is required when client uses the non-blocking API to invoke a web service. Its stores callback object with a key field as messageID. This is a singleton class which consists of following two methods. </p>
+ <div class="source"><pre>
+ public Callback getCorrelationInfo(String MessageID)
+</pre></div>
+ </div><div class="subsection"><a name="Listener"></a><h3>Listener</h3><p>A separate listener is required to provide the asynchronous communication between the client and the service. That is, when the client retrieves the response (if any) using a separate transport connection, listener will act as an addressable end point to the service so that it can send the service responses directly to the listener.</p></div><div class="subsection"><a name="ClientProvider"></a><h3>ClientProvider</h3><p>This is provider used in the client side.(The name should be changed later). This is only used when the client uses asynchronous web service invocation pattern, that is when a separate listener is used to retrieve the response. The service response is received using the same way that the axis engine receives a request. So the ProviderX will represent the end of the execution chain of the engine and it will set the response to the callback object.</p><p> </p></div></div><div class="sect
ion"><a name="How_Axis_2_Architecture_Supports_the_above_Message_Patterns"></a><h2>How Axis 2 Architecture Supports the above Message Patterns</h2><div class="subsection"><a name="Robust_Invocation"></a><h3>Robust Invocation</h3><p>This invocation is mainly a one way operation. However it supports the returning faults from the service. The transport protocol used in this message pattern should be bi-directional. The following code snippet shows how the client can use above method of invocation and the sequence diagram shows the complete message. </p><p><strong>Code Snippet</strong></p>
+ <div class="source"><pre>call.setTo(EPR)
+ call.setAction(String)
+call.setTransportType(String)
+call.send(SOAPEnvelope)
+ </pre></div>
+ <p><strong>Message Path and Sequence Diagram</strong></p>
+ <div class="source"><pre>a -> call.send(SOAPEnvelope)
+b -> engine.send( ..)
+c -> Send the SOAP message
+ </pre></div>
+ <div align="center">
+ <pre>
+<img height="149" src="images/image004.jpg" width="416" designtimeurl="images/image004.jpg" alt=""></img></pre>
+</div><p align="center">Figure 2- Sequence diagram corresponding to send ()</p></div><div class="subsection"><a name="Fire_and_Forget_Invocation"></a><h3>Fire and Forget Invocation</h3><p>This method of invocation does not wait for any kind of response, not even for a fault. Once the request is written to the wire the method immediately returns to the client. Transport can be either unidirectional or bi-directional. Following code snippet shows how the client can use above API method and the sequence diagram shows the complete message. </p><p><strong>Code Snippet</strong></p>
+ <div class="source"><pre>call.setTo(EPR)
+call.setAction(String)
+call.setTransportType(String)
+call.sendAsync(SOAPEnvelope)
+</pre></div>
+ <p><strong>Message Path and Sequence Diagram</strong></p>
+ <div class="source"><pre>a -> call.send(SOAPEnvelope)
+b -> engine.send( ..)
+c -> Send the SOAP message
+</pre></div>
+ <p align="center"><img height="147" src="images/image006.jpg" width="434" designtimeurl="images/image006.jpg" alt=""></img></p><p align="center">Figure 3 ? Sequence diagram corresponds to sendAsync()</p></div><div class="subsection"><a name="Blocking_Invocation_of_type_In-Out"></a><h3>Blocking Invocation of type In-Out</h3><p>This invocation pattern lets the client to invoke a web service and wait till the response is received before proceeding to the next line of invocation. This is very much similar to the Call.invoke() with response types in Axis 1.1. In this approach, the transport specified should be a bi-directional transport and the response is retrieved using the same transport connection. The client will hang till the entire communication completes.</p><p><strong>Code Snippet </strong></p>
+ <div class="source"><pre> call.setAction(String)
+call.setTransportType(String)
+SOAPEnvelope env=call.sendReceive(SOAPEnvelope)
+</pre></div>
+ <p><strong>Message Path and Sequence Diagram</strong></p>
+ <div class="source"><pre>a -> call.sendReceive(SOAPEnvelope)
+b- > engine.send (..)
+c -> Send the SOAP message
+d -> Receive the response over the synchronous transport
+w -> ProviderX will be called as the last step in engine.receive(..)
+e -> provider returns
+f -> Call hand over the response to the client
+</pre></div>
+ <p align="center"><img height="199" src="images/image008.jpg" width="439" designtimeurl="images/image008.jpg" alt=""></img></p><p align="center">Figure 4 ? Sequence diagram corresponds to sendRecieve()</p></div><div class="subsection"><a name="Non_Blocking_Invocation_of_type_In-Out"></a><h3>Non Blocking Invocation of type In-Out</h3><p>Using this method client can access In-Out type web service operations. There are two ways that the client can use this invocation pattern.</p><p><strong>Method 1: Without a Client Side Listener</strong></p><p>The communication happens using a single transport connection. With respect to the transport protocol used, the web service response is received using the same connection. However the client will not block till it receive the response. Instead it can proceed to the next line of execution by registering a Callback object. The following code snippet shows how the client can use above API method and the sequence diagram shows the comple
te message. To use this pattern client should use the value ?<strong>true</strong>? for the parameter ?useSeparateListener? in the setListenerTransport(..) method.</p><p><strong>Code Snippet</strong></p>
+ <div class="source"><pre>call.setTO(EPR)
+call.setAction(String)
+call.setTransportType(String)
+call.setListenerTransport(String transportType,boolean useSeparateListener)
+call.sendReceiveAsync (SOAPEnvelope, Callback)
+</pre></div>
+ <p><strong>Message Path and Sequence Diagram</strong></p>
+ <div class="source"><pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)
+p -> correlator.addCorrelationInfor(msgID,allbackObjRef)
+b- > engine.send (..)
+c -> Send the SOAP message
+d -> Receive the response over the synchronous transport
+w -> ProviderX will be called as the last step in engine.receive(..)
+q -> correlator.getCorrelationInfo(msgID)
+g -> callbackObj.onComplete()
+</pre></div>
+ <div align="center">
+ <pre><img height="225" src="images/image010.jpg" width="643" designtimeurl="images/image010.jpg" alt=""></img></pre>
+</div><p align="center">Figure 5 ? Sequence diagram corresponds to sendRecieveAysn with two way transport</p><p><strong>Method 2: With a Client Side Listener</strong></p><p>In this method client will have the usage of non-blocking API with a separate listener to accept the service response asynchronously. Outgoing transport does not wait for the response. Instead corresponding incoming message is processed by different transport, which is created by call object while it is sending the request. The correlation between the request and the response messages is achieved using a similar message ID mechanism as in WS-Addressing. Once the WS-Addressing support is implemented the client will only use <wsa:MessageID> and the <was:RelatesTo> headers to achieve the correlation. </p><p>The following code snippet shows how the client can use that above API method and the sequence diagram shows the complete message. To use this pattern client should use the value ?<strong>fals
e</strong>? for the parameter ?useSeparateListener? in the setListenerTransport(..) method.</p><p><strong>Code Snippet</strong></p>
+ <div class="source"><pre>call.setTO(EPR)
+call.setAction(String)
+call.setTransportType(String)
+call.setListenerTransport(String transportType,boolean useSeparateListener)
+call.sendReceiveAsync (SOAPEnvelope, Callback)
+</pre></div>
+ <p><strong>Message Path and Sequence Diagram</strong></p>
+ <div class="source"><pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)
+ p -> correlator.addCorrelationInfor(msgID,allbackObjRef)
+b- > engine.send (..)
+ c -> Send the SOAP message
+ r -> Receive the response by the listener
+ s -> engine.receive(..)
+ w -> ProviderX will be called as the last step in engine.receive(..)
+ q -> correlator.getCorrelationInfo(msgID)
+g -> callbackObj.onComplete()
+</pre></div>
+ <p align="center"><img height="234" src="images/image012.jpg" width="648" designtimeurl="images/image012.jpg" alt=""></img></p><p align="center">Figure 6 ? Sequence diagram corresponds to sendRecieveAync with one way transport.</p><p><strong><u>Asynchronous invocation with one way transport</u></strong></p><p>The programming model almost similar to asynchronous invocation with two way transport. Only difference is that for outgoing and incoming messages, it uses two engine instances, and outgoing transport dose not wait for response. Instead, corresponding incoming message is processed by different transport which is created by call object while it is sending the request. Here the Listener is the newly created transport, which is running to get the incoming message. Corresponding sequence diagram is shown in Figure 6, code snippet and message paths are described below. </p></div><div class="subsection"><a name="Code_Snippet"></a><h3>Code Snippet</h3>
+ <div class="source"><pre>call.setTO(EPR)
+ call.setAction(String)
+call.setListenerTransport(?http?, false)
+call.sendReceiveAsync(SOAPEnvelope, Callback)
+</pre></div>
+ </div><div class="subsection"><a name="Message_paths"></a><h3>Message paths</h3>
+ <div class="source"><pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj) p -> correlator.addCorrelationInfor(msgID,allbackObjRef)
+b- > engine.send (..)
+c -> Send the SOAP message
+r -> Receive the response by the listener
+s -> engine.receive(..)
+w -> ProviderX will be called as the last step in engine.receive(..)
+ q -> correlator.getCorrelationInfo(msgID)
+g -> callbackObj.onComplete()
+</pre></div>
+ <p align="center"><img height="234" src="images/image013.jpg" width="648" designtimeurl="images/image013.jpg" alt=""></img></p><p align="center">Figure 6 ? Sequence diagram corresponds to sendRecieveAync with one way transport.</p></div></div><div class="section"><a name="What_is_supported_in_M1"></a><h2>What is supported in M1</h2><p>From the above interaction patterns for Milestone1, we have only implemented
+the following two types. </p><ul>
+ <li>Blocking Invocation of type In-Out</li>
+ <li>Non Blocking Invocation of type In-Out --> Method 1: Without a Client Side Listener</li>
+</ul><p>However from the client's point of view the other interaction patterns are
+also implemented except the Non Blocking Invocation of type In-Out with a client
+side listener, but still we could not test them since we need complete server
+implementation to test them.</p></div><div class="section"></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file