You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2005/02/21 09:12:17 UTC
svn commit: r154653 [3/3] - in webservices/axis/trunk/java/xdocs:
Axis2ArchitectureGuide.html ClientAPI.html navigation.xml schemas.html
userguide.html
Modified: webservices/axis/trunk/java/xdocs/ClientAPI.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/ClientAPI.html?view=diff&r1=154652&r2=154653
==============================================================================
--- webservices/axis/trunk/java/xdocs/ClientAPI.html (original)
+++ webservices/axis/trunk/java/xdocs/ClientAPI.html Mon Feb 21 00:12:14 2005
@@ -3,32 +3,40 @@
</head>
<body>
<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 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 how they are supported in Apache Axis 2.</p>
-<p>Note: Through out the tutorial the words Client and the Service are used to represent Web Service Client and the Web Service respectively.</p>
+<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>
<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 transport protocol used</li>
+ <li>The Protocol used to send the SOAP Message</li>
<li>The type of the service method</li>
</ul>
<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 its 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 will be a huge drawback in the client side performance, if the operation takes considerable amount of time.</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, with the isComplete(). If isComplete() returns true, client get the result, if any, through getResult() which returns an AsyncResult object.
+<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>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>
-<h2>Transport Protocol Used</h2>
-<p>Transport protocols can be categorized mainly in to two types.</p>
+<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 state or a fault (if any). With reference to HTTP the HTTP 202 header status will act as the acceptance state and it will also be used to send a fault (if any) to the client using the same 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 state 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>
<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>
@@ -45,7 +53,7 @@
<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 align="center"> <img height=315 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image002.jpg" width=576 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image002.jpg"></p>
+<p align="center"> <img height=315 src="images/image002.jpg" width=576 DESIGNTIMEURL="images/image002.jpg"></p>
<p align=center>Figure 1 Axis Client Architecture</p>
<h3>Client </h3>
<p>This is the web service client that actually utilizes the service.</p>
@@ -84,7 +92,7 @@
<p>c -> Send the SOAP message</p>
<div align="center">
<pre>
-<img height=149 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image004.jpg" width=416 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image004.jpg"></pre>
+<img height=149 src="images/image004.jpg" width=416 DESIGNTIMEURL="images/image004.jpg"></pre>
</div>
<p align=center>Figure 2- Sequence diagram corresponding to send ()</p>
<h3>Fire and Forget Invocation</h3>
@@ -94,7 +102,7 @@
<p> call.sendAsync(SOAPEnvelope) </p></source>
<p><strong>Message Path and Sequence Diagram</strong></p>
<pre>a -> call.send(SOAPEnvelope)</pre><pre>b -> engine.send( ..)</pre><pre>c -> Send the SOAP message</pre>
-<p align=center><img height=147 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image006.jpg" width=434 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image006.jpg"></p>
+<p align=center><img height=147 src="images/image006.jpg" width=434 DESIGNTIMEURL="images/image006.jpg"></p>
<p align=center>Figure 3 Sequence diagram corresponds to sendAsync()</p>
<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>
@@ -104,7 +112,7 @@
<p> SOAPEnvelope env=call.sendReceive(SOAPEnvelope)</p>
<p><strong>Message Path and Sequence Diagram</strong></p>
a -> call.sendReceive(SOAPEnvelope)<pre>b- > engine.send (..)</pre><pre>c -> Send the SOAP message</pre><pre>d -> Receive the response over the synchronous transport</pre><pre>w -> ProviderX will be called as the last step in engine.receive(..) </pre><pre>e -> provider returns </pre><pre>f -> Call hand over the response to the client</pre>
-<p align=center><img height=199 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image008.jpg" width=439 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image008.jpg"></p>
+<p align=center><img height=199 src="images/image008.jpg" width=439 DESIGNTIMEURL="images/image008.jpg"></p>
<p align=center>Figure 4 Sequence diagram corresponds to sendRecieve()</p>
<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>
@@ -115,8 +123,7 @@
<p><strong>Message Path and Sequence Diagram</strong></p>
<pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)</pre><pre>p -> correlator.addCorrelationInfor(msgID,allbackObjRef)</pre><pre>b- > engine.send (..)</pre><pre>c -> Send the SOAP message</pre><pre>d -> Receive the response over the synchronous transport</pre><pre>w -> ProviderX will be called as the last step in engine.receive(..) </pre><pre>q -> correlator.getCorrelationInfo(msgID)</pre><pre>g -> callbackObj.onComplet()</pre>
<div align="center">
- <pre>
-<img height=225 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg" width=643 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image010.jpg"></pre>
+ <pre><img height=225 src="images/image010.jpg" width=643 DESIGNTIMEURL="images/image010.jpg"></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>
@@ -127,18 +134,23 @@
<p><strong><u> </u></strong></p>
<p><strong>Message Path and Sequence Diagram</strong></p>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)<p>p -> correlator.addCorrelationInfor(msgID,allbackObjRef)</p>
<pre>b- > engine.send (..)</pre><pre>c -> Send the SOAP message</pre><pre>r -> Receive the response by the listener</pre><pre>s -> engine.receive(..)</pre><pre>w -> ProviderX will be called as the last step in engine.receive(..) </pre><pre>q -> correlator.getCorrelationInfo(msgID)</pre><pre>g -> callbackObj.onComplet()</pre>
-<p align=center><img height=234 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image012.jpg" width=648 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image012.jpg"></p>
+<p align=center><img height=234 src="images/image012.jpg" width=648 DESIGNTIMEURL="images/image012.jpg"></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><pre>call.setTO(EPR)</pre><pre>call.setAction(String)</pre><pre>call.setListenerTransport(http, false)</pre><pre>call.sendReceiveAsync(SOAPEnvelope, Callback)</pre>
<h3>Message paths</h3><pre>a -> call.sendReceiveAsync (SOAPEnvelope, callbackObj)</pre><pre>p -> correlator.addCorrelationInfor(msgID,allbackObjRef)</pre><pre>b- > engine.send (..)</pre><pre>c -> Send the SOAP message</pre><pre>r -> Receive the response by the listener</pre><pre>s -> engine.receive(..)</pre><pre>w -> ProviderX will be called as the last step in engine.receive(..) </pre><pre>q -> correlator.getCorrelationInfo(msgID)</pre><pre>g -> callbackObj.onComplet()</pre>
-<p align=center><img height=234 src="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image013.jpg" width=648 DESIGNTIMEURL="Axis2%20supports%20both%20synchronous%20and%20asynchronous%20web%20service%20invocation%20with%20following%20five%20types%20of%20client%20programming%20model_files/image013.jpg"></p>
+<p align=center><img height=234 src="images/image013.jpg" width=648 DESIGNTIMEURL="images/image013.jpg"></p>
<p align=center>Figure 6 Sequence diagram corresponds to sendRecieveAync with one way transport.</p>
<h2>What is supported in M1</h2>
-<p>From the above interaction patterns for M1, we only support following two
-types.</p>
+<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>
-<h2> </h2></body></html>
\ No newline at end of file
+<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>
+<h2><span style="font-weight: 400"><font size="3">It is our intention to support
+all the required interaction patterns and will be available in the next release.</font></span></h2></body></html>
\ No newline at end of file
Modified: webservices/axis/trunk/java/xdocs/navigation.xml
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/navigation.xml?view=diff&r1=154652&r2=154653
==============================================================================
--- webservices/axis/trunk/java/xdocs/navigation.xml (original)
+++ webservices/axis/trunk/java/xdocs/navigation.xml Mon Feb 21 00:12:14 2005
@@ -2,8 +2,7 @@
<project name="Axis2.0">
<title>Axis 2.0</title>
<body>
- <search/>
-
+
<menu name="Axis 2.0">
<item name="Introduction" href="intro.html"/>
Modified: webservices/axis/trunk/java/xdocs/schemas.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/schemas.html?view=diff&r1=154652&r2=154653
==============================================================================
--- webservices/axis/trunk/java/xdocs/schemas.html (original)
+++ webservices/axis/trunk/java/xdocs/schemas.html Mon Feb 21 00:12:14 2005
@@ -15,11 +15,11 @@
<h1><span class="style1">Schemas
</span></h1>
<h2>Server.xml </h2>
-<p>This will describe the contents that should go in the server.xml of Axis 2.0. <a href="schemas/server.xsd">Schema</a> </p>
+<p>This will describe the contents that should go in the server.xml of Axis 2.0. <a href="schemas/server.xsd" target="_blank">Schema</a> </p>
<h2>Service.xml</h2>
-<p>This contain information that should be provided with a new service deployment to Axis 2.0. <a href="schemas/service.xsd">Scheme</a></p>
+<p>This contain information that should be provided with a new service deployment to Axis 2.0. <a href="schemas/service.xsd" target="_blank">Scheme</a></p>
<h2>Module.xml</h2>
-<p>This contain information that should be provided with a new module deployment to Axis 2.0. <a href="schemas/module.xsd">Scheme</a></p>
+<p>This contain information that should be provided with a new module deployment to Axis 2.0. <a href="schemas/module.xsd" target="_blank">Scheme</a></p>
<h2>Common.xml</h2>
<p>This provide a schemas for following elements; </p>
<p>1. Parameter
@@ -27,8 +27,8 @@
<br>3. Inflow
<br>4. OutFlow
<br>5. FaultFlow </p>
-<p><a href="schemas/common.xsd">Schema</a></p>
+<p><a href="schemas/common.xsd" target="_blank">Schema</a></p>
<h2>Java-Elt.xml</h2>
-<p> Format of the java implementation class element which is used in service.xml <a href="schemas/java-elt.xsd">Schema</a></p>
+<p> Format of the java implementation class element which is used in service.xml <a href="schemas/java-elt.xsd" target="_blank">Schema</a></p>
</body>
</html>
Modified: webservices/axis/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/xdocs/userguide.html?view=diff&r1=154652&r2=154653
==============================================================================
--- webservices/axis/trunk/java/xdocs/userguide.html (original)
+++ webservices/axis/trunk/java/xdocs/userguide.html Mon Feb 21 00:12:14 2005
@@ -4,34 +4,16 @@
<head>
<title>Axis 2.0 User's Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<style type="text/css">
-<!--
-.style1 {
- font-family: "Courier New", Courier, mono;
- font-size: 14px;
-}
-.style2 {
- color: #990000;
- font-weight: bold;
-}
-.style9 {color: #990000}
-.style10 {
- font-family: "Courier New", Courier, mono;
- font-size: 14px;
- color: #990000;
- font-weight: bold;
-}
-.style11 {font-family: "Courier New", Courier, mono; font-size: 14px; color: #990000; }
--->
-</style>
+
</head>
<body>
<h1 align="center"><a name="_Toc96697849">Axis 2.0 User's Guide </a></h1>
-<h1 align="left"><a name="_Toc96697851">Introduction </a></h1>
+<p> </p>
+<h2><a name="_Toc96698076"></a><a name="_Toc96697851">Introduction </a></h2>
<p>Welcome to Axis 2.0, the next generation of Apache Axis !!! This User Guide will help you to understand what you will get from Axis 2.0 and how to get started. </p>
<p>We hope you will benefit from the power of Axis 2.0. </p>
-<h1><a name="_Toc96698077"></a><a name="_Toc96697852">What is Axis 2.0 ? </a></h1>
+<h2><a name="_Toc96698077"></a><a name="_Toc96697852">What is Axis 2.0 ? </a></h2>
<p>Before we start, its highly recommended to read <a href="http://ws.apache.org/axis/java/user-guide.html">Axis 1.x User's guide </a>, if you are new to Axis. </p>
<p>Axis 2.0 is the next generation of Apache Axis. In late August 2004, during the Axis Summit held in Colombo, Sri Lanka, a new architecture was introduced to have a much more flexible, efficient and configurable Axis. Even though the architecture is new, some of the well established concepts from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes with lots of new features, enhancements and new industry specification implementations. </p>
<p>After months of continued discussion and coding effort in this direction, Axis 2.0 now delivers the following key features: </p>
@@ -48,9 +30,9 @@
<li><strong>WSDL support.</strong> Axis 2.0 supports the <a href="http://www.w3.org/TR/wsdl">Web Service Description Language </a>, version 1.1 and 2.0, which allows you to easily build stubs to access remote services, and also to automatically export machine-readable descriptions of your deployed services from Axis. </li>
</ul>
<p>We hope you enjoy using Axis. Please note that this is an open-source effort - if you feel the code could use some new features or fixes, please get involved and lend a hand! The Axis developer community welcomes your participation . </p>
-<strong>Let us know what you think! </strong>
+<h5>Let us know what you think! </h5>
<p>Please send feedback about the package to " <a href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org </a>" and make sure to prefix the subject of the mail with [Axis2]. </p>
-<h1><a name="_Toc96698078"></a><a name="_Toc96697853">What's in this release? </a></h1>
+<h2><a name="_Toc96698078"></a><a name="_Toc96697853">What's in this release? </a></h2>
<p>This release includes the following features: </p>
<ul>
<li>SOAP 1.1/1.2 compliant engine </li>
@@ -63,7 +45,7 @@
<li>WSDL 1.1 and 2.0 compliant Component Model </li>
<li>Examples, including a client and server for the one-way, two-way and synchronous, asynchronous web services invocation </li>
</ul>
-<h1><a name="_Toc96698079"></a><a name="_Toc96697854">What's still to do? </a></h1>
+<h2><a name="_Toc96698079"></a><a name="_Toc96697854">What's still to do? </a></h2>
<p>Please see a list of what we think needs doing - and please consider helping out if you're interested & able! </p>
<ul>
<li>Encoding/data binding </li>
@@ -75,7 +57,7 @@
</ul>
<h1><a name="_Toc96698080"></a><a name="_Toc96697855">Installation Guide </a></h1>
<h2><a name="_Toc96698081"></a><a name="_Toc96697856">Introduction </a></h2>
-<p>Axis 2.0 can be downloaded as a <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/releases.html">zipped binary </a> or the <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/sources.html">source </a>. This section describes how Axis2 can be installed either as a standalone server or as part of a J2EE compliant servlet container. </p>
+<p>Axis 2.0 can be downloaded as a <a href="releases.html">zipped binary </a> or the <a href="cvs-usage.html">source </a>. This section describes how Axis2 can be installed either as a standalone server or as part of a J2EE compliant servlet container. </p>
<h2><a name="_Toc96698082"></a><a name="_Toc96697857">Prerequisites </a></h2>
<p>Axis 2 requires the Java Runtime Environment to be properly installed. Axis is developed to be run on JRE 1.4 and upwards but it has not been fully tested with the latest JRE 1.5. Hence it is safe to run Axis with Java 1.4. If the JRE is not already in place it must be installed to proceed further. For instructions on setting up the JRE in different operating systems, please visit <a href="http://java.sun.com/">http://java.sun.com </a>. </p>
<p>All the required jars are shipped with the binary distribution and if the source distribution is used, running the maven build will automatically download the required jars for you. </p>
@@ -90,7 +72,7 @@
<p>For Linux users the tar ball or the zip archive is the best options. (Unfortunately there is no rpm as such that can be easily installed) Once the archive is downloaded expand it to a directory of choice and set the environment variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well. More instructions for installing Maven in UNIX based operating systems can be found <a href="http://maven.apache.org/start/install.html">here </a>. </p>
<p>Once maven is properly installed it's all that is needed to start building Axis2. </p>
<h3><a name="_Toc96698085"></a><a name="_Toc96697860">The Axis source distribution </a></h3>
-<p>The <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/sources.html">source distribution </a> is available as a zipped archive or a tar ball. All the necessary build scripts are included with the source distribution. Once the source archive is expanded into a directory of choice, moving to the particular directory and typing maven will build the axis jar file. </p>
+<p>The <a href="cvs-usage.html">source distribution </a> is available as a zipped archive or a tar ball. All the necessary build scripts are included with the source distribution. Once the source archive is expanded into a directory of choice, moving to the particular directory and typing maven will build the axis jar file. </p>
<p align="center"><img width="540" height="292" src="images/clip_image004.jpg"></p>
<p>Once the command completes, the binaries (jar files in this case) can be found at a newly created target directory. </p>
<p><strong>Note For the first Maven build (if the maven repository is not built first) it will take a while since required jars need to be downloaded. However this is a once only process and will not affect any successive builds. </strong></p>
@@ -115,13 +97,37 @@
<h1><a name="_Toc96697863"></a><a name="_Toc96698088">Samples </a></h1>
<p>There are three sample programs, which are listed below, that will be explained in this user guide and the relevant code can be found in the source directory under src\samples\userguide\sample1. </p>
<ol>
- <li>Echo Synchronous call. </li>
- <li> Echo Synchronous call with a phased handler. </li>
- <li>Echo Asynchronous call at the client side. </li>
+ <li>Case1: Echo Synchronous call. </li>
+ <li>Case2: Echo Synchronous call with a phased handler. </li>
+ <li>Case3: Echo Asynchronous call at the client side. </li>
</ol>
+<p>For the above three cases the sample will make use of two web services(namely sample1, sample1WithHandler) and two client applications. The diagram shows how the two services and the two client applications are used to come up with the three cases mentioned above.</p>
+<p align="center"><img src="images/cases.jpg"></p>
+
+<p> Axis2 M1 currently does not support the data binding, thus in the samples the operation that will be supported will be the echoing of xml without data binding. The message that will be sent and echoed will be the following.</p>
+<p class="style1 style2"><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+xmlns:sample1="http://sample1.org/sample1"></p>
+
+<p class="style1 style2"> <soapenv:Header/></p>
+
+<p class="style1 style2"> <soapenv:Body></p>
+
+<p class="style1 style2">
+<sample1:echo></p>
+
+<p class="style1 style2">
+<sample1:Text>Axis2
+Echo String</sample1:Text></p>
+
+<p class="style1 style2">
+</sample1:echo></p>
+
+<p class="style1 style2"> </soapenv:Body></p>
+
+<p class="style1 style2"></soapenv:Envelope></p>
<p>The Sample1 can be located at the src/samples/userguide/sample1 directory and it will have (or eventually have after the build) the following files. </p>
<p> </p>
-<table width="756" align="center" cellpadding="0" cellspacing="0">
+<table width="756" align="center" border="1" cellpadding="0" cellspacing="0">
<tr>
<td width="138" align="center" valign="top"><p align="center">Directory </p></td>
<td width="245" valign="top"><p align="center">File </p></td>
@@ -168,12 +174,22 @@
<td valign="top"><p>The callback that will be called after the completion of the Asynchronous call. </p></td>
</tr>
<tr>
+ <td valign="top"><p> </p></td>
+ <td valign="top"><p>ClientUtil.java </p></td>
+ <td valign="top"><p>A client Utility class that will generate a SOAPEnvelope.</p></td>
+ </tr>
+ <tr>
<td colspan="3" valign="top"><p> </p></td>
</tr>
<tr>
- <td valign="top"><p>conf/WEB-INF </p></td>
+ <td valign="top"><p>conf </p></td>
<td valign="top"><p>service.xml </p></td>
- <td valign="top"><p>The deployment descriptor for the service. </p></td>
+ <td valign="top"><p>The deployment descriptor for the service sample1. </p></td>
+ </tr>
+ <tr>
+ <td valign="top"></td>
+ <td valign="top"><p>service4withhandler.xml </p></td>
+ <td valign="top"><p>The deployment descriptor for the service sample1WithHandler. </p></td>
</tr>
<tr>
<td valign="top"><p>build/services </p></td>
@@ -181,6 +197,11 @@
<td valign="top"><p>The deployable jar that is created after building the sample. </p></td>
</tr>
<tr>
+ <td valign="top"></td>
+ <td valign="top"><p>sample1WithHandler.jar </p></td>
+ <td valign="top"><p>The deployable jar of the web service sample1WithHandler that is created after building this sample.</p></td>
+ </tr>
+ <tr>
<td valign="top"><p>lib </p></td>
<td valign="top"><p>sample1-all.jar </p></td>
<td valign="top"><p>The jar that bundles the server side and client side code. </p></td>
@@ -190,15 +211,11 @@
<p>Axis2 should be installed (see the Installation guide above). For simplicity samples will assume the servlet container is Tomcat. </p>
<p>AXIS_HOME environment variable be set. (Rationale: The compile time and runtime libraries required in the classpath for the samples will be picked up form the deployed asix2.) </p>
<p align="center"><img width="384" height="430" src="images/clip_image014.jpg"></p>
-<p>Apache Ant should be installed and should be available in the path. </p>
-<h2><a name="_Toc96698090"></a><a name="_Toc96697865">Deployment Mechanism </a></h2>
-<p>Axis2 supports hot deployment and a service can be deployed by packing the following files in a jar archive and simply dropping it into the Axis2 jar drop location which is AXIS_HOME/services directory in the servlet container. </p>
-<p>./<compiled class files> <br>
-./META-INF/service.xml </p>
-<p>Service.xml file describes axis specific functionality of the web service and should follow the schema listed in <a href="http://wiki.apache.org/ws/FrontPage/Architecture/Deployment">http://wiki.apache.org/ws/FrontPage/Architecture/Deployment </a> location. Please refer Appendix A for further information on writing your own service.xml. </p>
-<p>Once the built jar is dropped to AXIS_HOME/services of the running servlet container the user can immediately check weather the service is deployed using the web interface provided. The link would be http://<hostname>:<port>/<axis2 war dropped directory>/axis2/index.html (if axis2.war was dropped at the webapps directory of the servlet container running locally then the link would be <a href="http://127.0.0.1:8080/axis2/index.html">http://127.0.0.1:8080/axis2/index.html </a> )and click on the List available services link. </p>
-<h2><a name="_Toc96698091"></a><a name="_Toc96697866">Sample1 : Echo Synchronous call </a></h2>
-<p>The sample1: Echo synchronous call is intended to demonstrate the synchronous web service call in Axis2 with both the client side and client side running Axis2. In the next few steps the user will be walked through in: </p>
+<p>Apache Ant should be installed and should be available in the path. It can be checked weather Ant is properly installed by simply typing ant in the command prompt. Please refer<a href="http://ant.apache.org/"> http://ant.apache.org/</a>.</p>
+<p align="center"><img src="images/ant.jpg"></p>
+
+<h2><a name="_Toc96698091"></a><a name="_Toc96697866">Sample1- Case1 : Echo Synchronous call </a></h2>
+<p>The sample1 - Case1: Echo synchronous call is intended to demonstrate the synchronous web service call in Axis2 with both the client side and client side running Axis2. In the next few steps the user will be walked through in: </p>
<ul>
<li>Compiling and building a web service </li>
<li>Deploying </li>
@@ -232,8 +249,8 @@
<p><strong>The service will be deployed with the packaged jar file name. If the jar file is sample1.jar the service will be deployed with the name sample1. </strong></p>
<p>Point to note here is that above ant task is going to deploy two services </p>
<ol>
- <li>sample1 Required for this(Echo Sync call) and the EchoAsync Call examples. </li>
- <li>sample1WithHandler required for Echo Synchronous call with a phased handler. </li>
+ <li>sample1 Required for this(Echo Sync call) and the EchoAsync Call examples(Case1 and Case3). </li>
+ <li>sample1WithHandler required for Echo Synchronous call with a phased handler(Case2). </li>
</ol>
<p>If the servlet container is now running the user can go check to see weather the above services are deployed. Please refer the installation guide for further information on checking the deployed services. </p>
<p align="center"><img width="647" height="434" src="images/clip_image020.jpg"></p>
@@ -324,7 +341,7 @@
<p>The service <strong>sample1withhandler </strong> will run its logging handler as it gets called and it will log the call as the handler gets called in the inflow. This logged information can be found in the server logs. </p>
<h2><a name="_Toc96698093"></a><a name="_Toc96697868">Sample3 : Echo Asynchronous call. </a></h2>
<p>In this case the example focuses on calling a synchronous web service in an asynchronous manner in the client side. If this example is compared with the first example, which is <strong>Echo Synchronous call </strong>, the server side is identical for both the cases. The difference will be in the web service client that will be used. </p>
-<p>In this case the client will make a web service call and it will register a call back handler and sends the message out. The difference will be that the client application that is doing the web service call will not hang till the response. Rather it will get returned and once the response returns the client will get notified by way of the registered callback (This is one of the two methods this can be done in Axis 2.0. Refer <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/clientAPI.html">client api tutorial </a> for more information). </p>
+<p>In this case the client will make a web service call and it will register a call back handler and sends the message out. The difference will be that the client application that is doing the web service call will not hang till the response. Rather it will get returned and once the response returns the client will get notified by way of the registered callback (This is one of the two methods this can be done in Axis 2.0. Refer <a href="ClientAPI.html">client api tutorial </a> for more information). </p>
<p>The callback handler that will be used is ClientEchoCallbackHandler.java and the client program is AsynchronousClient.java. </p>
<h3><strong>Building the sample </strong></h3>
<p>Building the sample once will build all required classes and jars for all three cases. The ant task would be ant Compile. Please refer the building of the <strong>Echo Synchronous call </strong> above. </p>
@@ -345,7 +362,7 @@
<p>Writing a new Web Service in Axis2-M1 requires you to do following steps </p>
<p><strong>• Writing a new Web Service implementation class </strong></p>
<p>Axis2 M1 does not support data binding and supports only the XML level messaging. The default provider (do not worry about this if you do not know what it is) only supports the java methods having the return type as OMElement and only parameter as an OMElement. </p>
-<p>The OMElement is a Streaming representation of XML Message Element Information Item (Even though the user sees the OMElement as a tree based DOM/JDOM like node, it reads the information from the stream only when its absolutely required.). For more information refer the <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/OMTutorial.html">OM Tutorial </a>. </p>
+<p>The OMElement is a Streaming representation of XML Message Element Information Item (Even though the user sees the OMElement as a tree based DOM/JDOM like node, it reads the information from the stream only when its absolutely required.). For more information refer the <a href="OMTutorial.html">OM Tutorial </a>. </p>
<p>public class <class-name>{ </p>
<p>public OMElelemnt <method-name>(OMEllemnt){ </p>
<p><business logic> </p>
@@ -369,7 +386,7 @@
<p>Axis2 M1 supports HTTP transport only. Axis2-M1 supports the following interaction patterns. </p>
<p>• Blocking invocation of type in-out (request/response) </p>
<p>• Non blocking invocation of type in-out (Without a separate Listener) </p>
-<p>for more information about the interaction patterns, visit the <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/clientAPI.html">Client API Tutorial </a>. </p>
+<p>for more information about the interaction patterns, visit the <a href="ClientAPI.html">Client API Tutorial </a>. </p>
<p>To invoke the web service, user needs to build the the SOAPEnvelope himself. The SOAPEnvelope can be built by the following code. </p>
<p>OMFactory fac = OMFactory.newInstance(); </p>
<p>SOAPEnvelope envelope = fac.getDefaultEnvelope(); </p>
@@ -387,7 +404,7 @@
<p class="style1">XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file)); <br>
OMXMLParserWrapper builder = OMXMLBuilderFactory.createStAXOMBuilder(OMFactory.newInstance(), parser); </p>
<p class="style1">builder.getDocumentElement(); </p>
-<p class="style1">for more information in handling the OM objects please read the <a href="file:///E|/projects/dev/scratch/prototype2/xdocs/OMTutorial.html">OM Tutorial </a>. </p>
+<p class="style1">for more information in handling the OM objects please read the <a href="OMTutorial.html">OM Tutorial </a>. </p>
<h3><a name="_Toc96698097"></a><a name="_Toc96697872">Synchronous Client </a></h3>
<p>Invoking the synchronous web service call can be done with the following code. </p>
<p class="style1">EndpointReference targetEPR = <strong>new </strong>EndpointReference(AddressingConstants.WSA_TO, "http://127.0.0.1:" + (EngineUtils.TESTING_PORT) + "/axis/services/echo" ); </p>