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 2006/01/18 12:14:04 UTC

svn commit: r370124 [1/2] - in /webservices/axis2/trunk/java/xdocs/0_94: WS_policy.html images/arrow_left.gif images/arrow_right.gif installationguide.html userguide1.html userguide2.html userguide3.html userguide4.html userguide5.html

Author: chinthaka
Date: Wed Jan 18 03:13:48 2006
New Revision: 370124

URL: http://svn.apache.org/viewcvs?rev=370124&view=rev
Log:
getting the changes done to the userguide in to 0.94 branch as well

Added:
    webservices/axis2/trunk/java/xdocs/0_94/WS_policy.html
    webservices/axis2/trunk/java/xdocs/0_94/images/arrow_left.gif   (with props)
    webservices/axis2/trunk/java/xdocs/0_94/images/arrow_right.gif   (with props)
    webservices/axis2/trunk/java/xdocs/0_94/userguide1.html
    webservices/axis2/trunk/java/xdocs/0_94/userguide2.html
    webservices/axis2/trunk/java/xdocs/0_94/userguide3.html
    webservices/axis2/trunk/java/xdocs/0_94/userguide4.html
    webservices/axis2/trunk/java/xdocs/0_94/userguide5.html
Modified:
    webservices/axis2/trunk/java/xdocs/0_94/installationguide.html

Added: webservices/axis2/trunk/java/xdocs/0_94/WS_policy.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/WS_policy.html?rev=370124&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/WS_policy.html (added)
+++ webservices/axis2/trunk/java/xdocs/0_94/WS_policy.html Wed Jan 18 03:13:48 2006
@@ -0,0 +1,61 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+      "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+  <title>WS Policy Support in Axis2</title>
+  <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en">
+<h1 align="center">Web Services Policy Support In Axis2</h1>
+
+<h2 align="center"><em>-Experimental Feature</em></h2>
+
+<p><em>Axis2 version 0.94</em></p>
+<i>E-mail comments/ suggestions to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>
+
+<h2>What is Web Services (WS) Policy?</h2>
+
+<p>To consume non trivial web services one must fully understand its xml
+contract (WSDL) along with any other additional requirements, capabilities or
+preferences which translates to the configuration of the service, and
+essentially becomes the policies of the service.</p>
+
+<p>WS Policy framework provides a way to express the policies of a service in
+a machine-readable way. Web services infrastructure can be enhanced to
+understand and enforce policies at runtime. For instance, a service author
+might write a policy requiring digital signature and encryption, while
+service consumers could use the policy information to reason out whether they
+can adhere to this policy information to use the service or not.</p>
+
+<p>Further more, web service infrastructure could be enhanced to enforce
+those requirements without requiring the service author to write even single
+line of code.</p>
+
+<h2>What's in this release?</h2>
+
+<p>In this current release Axis2 framework uses ws-commons/policy as an
+object model to manipulate policy documents. All its description builders
+store any policy information included in description documents (services.xml,
+axis2.xml, .. etc) in the appropriate description classes. This information
+is available at both deployment and run time via these description
+classes.</p>
+
+<p>When generating WSDL dynamically for each service, policy information in
+the description classes is included. For instance, if you declare a policy in
+axis2.xml then that policy is reflected in service elements of WSDL of every
+service. If a policy is declared in a services.xml, it is shown in the
+service element of WSDL for that particular service.</p>
+
+<p>Next step is to use that information to engage and configure required
+modules and allow the module to make use of this policy information.</p>
+
+<p>It is evident that a great deal of work is required to make axis2 a fully
+fledged ws-policy supported web service infrastructure. But it is encouraging
+to note that we've taken the first steps towards this goal. We appreciate any
+suggestions, patches etc you send us in this regard. Keep on
+contributing...!</p>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/0_94/images/arrow_left.gif
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/images/arrow_left.gif?rev=370124&view=auto
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/trunk/java/xdocs/0_94/images/arrow_left.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/trunk/java/xdocs/0_94/images/arrow_right.gif
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/images/arrow_right.gif?rev=370124&view=auto
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/trunk/java/xdocs/0_94/images/arrow_right.gif
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Modified: webservices/axis2/trunk/java/xdocs/0_94/installationguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/installationguide.html?rev=370124&r1=370123&r2=370124&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/installationguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/0_94/installationguide.html Wed Jan 18 03:13:48 2006
@@ -1,309 +1,309 @@
-<!-- saved from url=(0022)http://internet.e-mail -->
-<html>
-<head>
-  <meta http-equiv="content-type" content="">
-  <title>Axis2 Installation Guide</title>
-  <style type="text/css">
-<!--
-.style1 {
-	font-family: "Courier New", Courier, mono;
-	font-size: 14px;
-	font-style: italic;
-}
-.style2 {font-family: Arial, Helvetica, sans-serif}
--->
-  </style>
-</head>
-
-<body lang="en">
-<h1 align="center">Axis2 Installation Guide</h1>
-
-<p><i>Version 0.94</i></p>
-<i>Feedback: <a
-href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>
-
-<h3>Contents</h3>
-<ul>
-  <li><a href="#Download">Download Axis2</a></li>
-  <li><p><a href="#requirements">System Requirements</a></p>
-  </li>
-  <li><a href="#_Toc96698083">Setting up the Environment and tools</a>
-    <ul>
-      <li><p><a href="#_Toc96698084">Maven</a></p>
-      </li>
-      <li><a href="#_Toc96698085">The Axis2 source distribution</a></li>
-    </ul>
-  </li>
-  <li><p><a href="#_Toc96698086">Installing Axis2 in a Servlet
-    container</a></p>
-    <ul>
-      <li><a href="#upload">Uploading services</a></li>
-    </ul>
-  </li>
-</ul>
-
-<h3><a name="Download">Download Axis2</a></h3>
-
-<p>Axis2 is distributed in several convenient distribution packages and can be installed either as a
-standalone server or as part of a J2EE compliant servlet container. Axis2 is
-distributed under the Apache License, version 2.0. You can download Axis2 <a href="http://ws.apache.org/axis2/download.cgi">here</a>. Latest release of Axis2 is version 0.94. </p>
-<table width="940" border="1" cellpadding="1">
-  <tr>
-    <th width="83" scope="col">Distribution Name</th>
-    <th width="633" scope="col">Description</th>
-    <th width="202" scope="col">Items</th>
-  </tr>
-  <tr>
-    <td>Minimal Distribution - Binary </td>
-    <td>This distribution is aimed at advanced users who will be embedding Axis2. It will contain the minimal runtime required to act as a Web Service client and/or a server (axis2-core-0.94.jar will contain compiled versions of common, xml, wsdl and core modules.) </td>
-    <td><ul>
-      <li>axis2-core-0.94.jar, axis2-adb-0.94.jar</li>
-      <li>third party distributable libraries</li>
-      <li>README.TXT and release-notes.html </li>
-    </ul></td>
-  </tr>
-  <tr>
-    <td>Minimal Distribution - Source </td>
-    <td background="#_Toc96698083"><p>This will contain the sources of Axis2 minimal distribution. One can generate a binary distribution from this by typing  <span class="style1">$maven dist-min-bin. </span>(<a href="#_Toc96698083">Set up Axis2 environment</a> before running this command) </p></td>
-    <td><ul>
-      <li>sources of Axis2 common, xml, wsdl, adb and core modules </li>
-      <li>README.TXT and release-notes.html</li>
-    </ul></td>
-  </tr>
-  <tr>
-    <td>Standard Distribution - Binary </td>
-    <td>This is the complete version of Axis2 and will contain useful samples as well. Useful for some one to get familiar with Axis2. (Since WS-Addressing implementation module is engaged in to Axis2, by default, this distribution will contain addressing.mar. But  the other modules that are being developed within Axis2 will not be included here and are available to be downloaded separately from <a href="http://ws.apache.org/axis2/modules/index.html">here</a>.)</td>
-    <td><ul>
-      <li>all the content of minimal-binary distribution</li>
-      <li>Contents of codegen and DOOM modules</li>
-      <li>Samples</li>
-      <li>addressing.mar</li>
-    </ul></td>
-  </tr>
-  <tr>
-    <td>Standard Distribution - Source </td>
-    <td>This will contain the sources of Axis2 standard distribution. One can generate a binary distribution from this by typing <span class="style1">$maven dist-standard-bin. </span>(<a href="#_Toc96698083">Set up Axis2 environment</a> before running this command) </td>
-    <td><ul>
-      <li>all the content of minimal-source distribution</li>
-      <li>Contents of codegen and DOOM modules</li>
-      <li>Samples</li>
-      </ul></td>
-  </tr>
-  <tr>
-    <td>WAR (Web Archive) Distribution </td>
-    <td>This will be the web application of Axis2 which can be deployed in most of the servlet containers. </td>
-    <td><ul>
-      <li>
-        all the contents of the minimal distribution 
-      </li>
-      <li>
-        Admin web app
-      </li>
-    </ul></td>
-  </tr>
-  <tr>
-    <td>Documents Distribution </td>
-    <td>This will contain all the documentation in one package.</td>
-    <td><ul>
-      <li>xdocs</li>
-      <li>javadocs </li>
-    </ul></td>
-  </tr>
-  <tr>
-    <td>Plugin Distribution </td>
-    <td>This will contain the plugins that are created for Eclipse and IDEA.</td>
-    <td><ul>
-      <li>Intellij IDEA plugins</li>
-      <li>Eclipse plugins</li>
-    </ul></td>
-  </tr>
-</table>
-<h3><a name="requirements">System Requirements</a></h3>
-
-<table border="2">
-  <caption></caption>
-  <tbody>
-    <tr>
-      <td>Java Runtime
-
-        <p>Environment</p>
-      </td>
-      <td>1.4 (It has not been fully tested on the latest JRE 1.5)
-
-        <p>For instructions on setting up the JRE in different operating
-        systems, visit <a
-        href="http://java.sun.com/">http://java.sun.com</a></p>
-      </td>
-    </tr>
-    <tr>
-      <td>Maven</td>
-      <td>1.0.2 or higher (<a href="http://maven.apache.org/">download</a>)
-
-        <p>Required only for building Axis2 from source distribution</p>
-      </td>
-    </tr>
-    <tr>
-      <td>Memory</td>
-      <td>No minimum requirement</td>
-    </tr>
-    <tr>
-      <td>Disk</td>
-      <td>No minimum requirement.
-
-        <p>Approximately 20 MB will be used for war distribution</p>
-      </td>
-    </tr>
-    <tr>
-      <td>Operating system</td>
-      <td>Tested on Windows XP, Mac OS X, Fedora core, Ubuntu, Gentoo</td>
-    </tr>
-  </tbody>
-</table>
-
-<p></p>
-
-<p>All the required jars are shipped with the binary distribution.</p>
-
-<p>Running the Maven build will automatically download the required jars when
-using source distribution.</p>
-
-<h3><a name="_Toc96698083"></a>Setting up the Environment and Tools</h3>
-
-<h4><a name="_Toc96698084" id="_Toc96698084"></a>Maven</h4>
-
-<p>The Axis2 build is based on <a href="http://maven.apache.org/">Maven </a>.
-Hence the only prerequisite to build Axis2 from source distribution is to
-have Maven installed. Extensive instruction guides are available at the Maven
-site.This guide however contains the easiest path for quick environment
-setting. Advanced users who wish to know more about Maven can visit <a
-href="http://maven.apache.org/start/index.html">here </a>.</p>
-<ul>
-<li>Windows</li>
-<ol>
-  <li>Download and run the Windows installer package</li>
-  <li>Set the 'Environment Variables' ( create system variable MAVEN_HOME and
-    edit path. eg: "C:\Program Files\Apache Software Foundation\maven-2.0.1";
-    path %MAVEN_HOME%\bin)</li>
-  <li>Make sure that system variable JAVA_HOME is set to the location of your
-    JDK, eg. C:\Program Files\Java\jdk1.5.0_02</li>
-  <li>Run maven --version to verify that it is correctly installed.</li>
-</ol>
-
-
-<p align="center"><img alt="clip_image002 (15K)"
-src="images/clip_image002.jpg" height="211" width="477"></p>
-
-<li>Unix based OS (Linux etc)</li>
-
-<p>The tar ball or the zip archive is the best option. 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>
-
-</ul>
-<p>Once maven is properly installed you can start building Axis2.</p>
-
-<h4><a name="_Toc96698085"></a>The Axis2 source distribution</h4>
-
-<p>The <a href="http://ws.apache.org/axis2/download.cgi">source distribution </a> is available as a
-zipped archive. 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 running maven command will build the
-Axis2 jar file.</p>
-
-<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg"
-height="248" width="668"></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>
-
-<p><strong></strong>The default maven build will however build only the Axis2
-jar file. To obtain a WAR (Web Archive), "maven war" command should be
-issued. This will create a complete WAR with the name axis2.war inside the
-target directory.</p>
-
-<p>Once this build step is complete, the binaries are ready to be
-deployed.</p>
-
-<h3><a name="_Toc96698086"></a>Installing Axis2 in a Servlet container</h3>
-<ol>
-  <li>Download Axis2 war file</li>
-  <li>Drop the war in the webapps folder. Most servlet containers will
-    automatically install war. (some servlet containers may require a restart
-    in order to capture the new web application. Refer your servlet container
-    documentation for more information about this.)</li>
-  <li>Once the WAR is successfully installed, test it by pointing the web
-    browser to the <strong>http:// &lt;host :port&gt;/ axis2. </strong>It
-    should produce the following page.</li>
-
-  <p align="center"><strong><img src="images/clip_image006.jpg"></strong></p>
-
-  <p></p>
-  <li>Use validate link to ensure that everything is fine and smooth. If the
-    validation fails then the war has failed to install properly or some
-    essential jars are missing. At such a situation the documentation of the
-    particular servlet container should be consulted to find the problem. The
-    following page is a successful validation. Note the statement core Axis2
-    libraries are present.
-    <p></p>
-  </li>
-
-  <p align="center"><strong><img src="images/happyaxis.jpg"></strong></p>
-</ol>
-
-<p></p>
-
-<h4><a name="upload">Uploading services</a></h4>
-<ol>
-  <p>The Axis2 web application also provides an interface to upload services.
-  Once a service is created according to the service specification as
-  described in userguide that jar file can be uploaded using the upload
-  page.</p>
-
-  <p align="center"><strong><img src="images/clip_image010.jpg"
-  alt=""></strong></p>
-
-  <p>The uploaded jar files will be stored in the default service directory.
-  For Axis2 this will be the &lt;webapps&gt;/axis2/WEB-INF/services
-  directory. Once a service is uploaded it will be installed instantly.</p>
-
-  <p>Since Axis2 supports hot deployment one can drop the service jar
-  directly through the file system to the above mentioned services
-  directory.It will also cause the service to be automatically installed
-  without the container being restarted.</p>
-
-  <p>Use the <i>available services link</i> to check the successful
-  installation of a service. The services and the operations of successfully
-  installed services will be displayed in the available services page.</p>
-
-  <p align="center"><img src="images/clip_image012.jpg"
-  alt=""></p>
-
-  <p></p>
-
-  <p>If the service has deployment time error it will list those services
-  as faulty services. If you click on the link you can see the your deployment
-  fault error message(s).</p>
-
-  <p align="center"><img src="images/faultservice.jpg"
-  alt=""></p>
-
-  <p>Deployment time error message</p>
-
-  <p align="center"><strong><img src="images/faultmsg.jpg"
-  alt=""></strong></p>
-
-  <p>  </p>
-
-  <p>Axis2 Administration is all about configuring Axis2 at the run time and
-  the configuration will be transient. More descriptions are available in <a
-  href="webadminguide.html">Axis2 Web Administration Guide</a></p>
-</ol>
-</body>
-</html>
+<!-- saved from url=(0022)http://internet.e-mail -->
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 Installation Guide</title>
+  <style type="text/css">
+<!--
+.style1 {
+	font-family: "Courier New", Courier, mono;
+	font-size: 14px;
+	font-style: italic;
+}
+.style2 {font-family: Arial, Helvetica, sans-serif}
+-->
+  </style>
+</head>
+
+<body lang="en">
+<h1 align="center">Axis2 Installation Guide</h1>
+
+<p><i>Version 0.94</i></p>
+<i>Feedback: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>
+
+<h3>Contents</h3>
+<ul>
+  <li><a href="#Download_Axis2">Download Axis2</a></li>
+  <li><p><a href="#requirements">System Requirements</a></p>
+  </li>
+  <li><a href="#_Toc96698083">Setting up the Environment and tools</a>
+    <ul>
+      <li><p><a href="#_Toc96698084">Maven</a></p>
+      </li>
+      <li><a href="#_Toc96698085">The Axis2 source distribution</a></li>
+    </ul>
+  </li>
+  <li><p><a href="#_Toc96698086">Installing Axis2 in a Servlet
+    container</a></p>
+    <ul>
+      <li><a href="#upload">Uploading services</a></li>
+    </ul>
+  </li>
+</ul>
+
+<h3><a name="Download_Axis2">Download Axis2</a></h3>
+
+<p>Axis2 is distributed in several convenient distribution packages and can be installed either as a
+standalone server or as part of a J2EE compliant servlet container. Axis2 is
+distributed under the Apache License, version 2.0. You can download Axis2 <a href="http://ws.apache.org/axis2/download.cgi">here</a>. Latest release of Axis2 is version 0.94. </p>
+<table width="940" border="1" cellpadding="1">
+  <tr>
+    <th width="83" scope="col">Distribution Name</th>
+    <th width="633" scope="col">Description</th>
+    <th width="202" scope="col">Items</th>
+  </tr>
+  <tr>
+    <td>Minimal Distribution - Binary </td>
+    <td>This distribution is aimed at advanced users who will be embedding Axis2. It will contain the minimal runtime required to act as a Web Service client and/or a server (axis2-core-0.94.jar will contain compiled versions of common, xml, wsdl and core modules.) </td>
+    <td><ul>
+      <li>axis2-core-0.94.jar, axis2-adb-0.94.jar</li>
+      <li>third party distributable libraries</li>
+      <li>README.TXT and release-notes.html </li>
+    </ul></td>
+  </tr>
+  <tr>
+    <td>Minimal Distribution - Source </td>
+    <td background="#_Toc96698083"><p>This will contain the sources of Axis2 minimal distribution. One can generate a binary distribution from this by typing  <span class="style1">$maven dist-min-bin. </span>(<a href="#_Toc96698083">Set up Axis2 environment</a> before running this command) </p></td>
+    <td><ul>
+      <li>sources of Axis2 common, xml, wsdl, adb and core modules </li>
+      <li>README.TXT and release-notes.html</li>
+    </ul></td>
+  </tr>
+  <tr>
+    <td>Standard Distribution - Binary </td>
+    <td>This is the complete version of Axis2 and will contain useful samples as well. Useful for some one to get familiar with Axis2. (Since WS-Addressing implementation module is engaged in to Axis2, by default, this distribution will contain addressing.mar. But  the other modules that are being developed within Axis2 will not be included here and are available to be downloaded separately from <a href="http://ws.apache.org/axis2/modules/index.html">here</a>.)</td>
+    <td><ul>
+      <li>all the content of minimal-binary distribution</li>
+      <li>Contents of codegen and DOOM modules</li>
+      <li>Samples</li>
+      <li>addressing.mar</li>
+    </ul></td>
+  </tr>
+  <tr>
+    <td>Standard Distribution - Source </td>
+    <td>This will contain the sources of Axis2 standard distribution. One can generate a binary distribution from this by typing <span class="style1">$maven dist-standard-bin. </span>(<a href="#_Toc96698083">Set up Axis2 environment</a> before running this command) </td>
+    <td><ul>
+      <li>all the content of minimal-source distribution</li>
+      <li>Contents of codegen and DOOM modules</li>
+      <li>Samples</li>
+      </ul></td>
+  </tr>
+  <tr>
+    <td>WAR (Web Archive) Distribution </td>
+    <td>This will be the web application of Axis2 which can be deployed in most of the servlet containers. </td>
+    <td><ul>
+      <li>
+        all the contents of the minimal distribution 
+      </li>
+      <li>
+        Admin web app
+      </li>
+    </ul></td>
+  </tr>
+  <tr>
+    <td>Documents Distribution </td>
+    <td>This will contain all the documentation in one package.</td>
+    <td><ul>
+      <li>xdocs</li>
+      <li>javadocs </li>
+    </ul></td>
+  </tr>
+  <tr>
+    <td>Plugin Distribution </td>
+    <td>This will contain the plugins that are created for Eclipse and IDEA.</td>
+    <td><ul>
+      <li>Intellij IDEA plugins</li>
+      <li>Eclipse plugins</li>
+    </ul></td>
+  </tr>
+</table>
+<h3><a name="requirements">System Requirements</a></h3>
+
+<table border="2">
+  <caption></caption>
+  <tbody>
+    <tr>
+      <td>Java Runtime
+
+        <p>Environment</p>
+      </td>
+      <td>1.4 (It has not been fully tested on the latest JRE 1.5)
+
+        <p>For instructions on setting up the JRE in different operating
+        systems, visit <a
+        href="http://java.sun.com/">http://java.sun.com</a></p>
+      </td>
+    </tr>
+    <tr>
+      <td>Maven</td>
+      <td>1.0.2 or higher (<a href="http://maven.apache.org/">download</a>)
+
+        <p>Required only for building Axis2 from source distribution</p>
+      </td>
+    </tr>
+    <tr>
+      <td>Memory</td>
+      <td>No minimum requirement</td>
+    </tr>
+    <tr>
+      <td>Disk</td>
+      <td>No minimum requirement.
+
+        <p>Approximately 20 MB will be used for war distribution</p>
+      </td>
+    </tr>
+    <tr>
+      <td>Operating system</td>
+      <td>Tested on Windows XP, Mac OS X, Fedora core, Ubuntu, Gentoo</td>
+    </tr>
+  </tbody>
+</table>
+
+<p></p>
+
+<p>All the required jars are shipped with the binary distribution.</p>
+
+<p>Running the Maven build will automatically download the required jars when
+using source distribution.</p>
+
+<h3><a name="_Toc96698083"></a>Setting up the Environment and Tools</h3>
+
+<h4><a name="_Toc96698084" id="_Toc96698084"></a>Maven</h4>
+
+<p>The Axis2 build is based on <a href="http://maven.apache.org/">Maven </a>.
+Hence the only prerequisite to build Axis2 from source distribution is to
+have Maven installed. Extensive instruction guides are available at the Maven
+site.This guide however contains the easiest path for quick environment
+setting. Advanced users who wish to know more about Maven can visit <a
+href="http://maven.apache.org/start/index.html">here </a>.</p>
+<ul>
+<li>Windows</li>
+<ol>
+  <li>Download and run the Windows installer package</li>
+  <li>Set the 'Environment Variables' ( create system variable MAVEN_HOME and
+    edit path. eg: "C:\Program Files\Apache Software Foundation\maven-2.0.1";
+    path %MAVEN_HOME%\bin)</li>
+  <li>Make sure that system variable JAVA_HOME is set to the location of your
+    JDK, eg. C:\Program Files\Java\jdk1.5.0_02</li>
+  <li>Run maven --version to verify that it is correctly installed.</li>
+</ol>
+
+
+<p align="center"><img alt="clip_image002 (15K)"
+src="images/clip_image002.jpg" height="211" width="477"></p>
+
+<li>Unix based OS (Linux etc)</li>
+
+<p>The tar ball or the zip archive is the best option. 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>
+
+</ul>
+<p>Once maven is properly installed you can start building Axis2.</p>
+
+<h4><a name="_Toc96698085"></a>The Axis2 source distribution</h4>
+
+<p>The <a href="http://ws.apache.org/axis2/download.cgi">source distribution </a> is available as a
+zipped archive. 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 running maven command will build the
+Axis2 jar file.</p>
+
+<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg"
+height="248" width="668"></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>
+
+<p><strong></strong>The default maven build will however build only the Axis2
+jar file. To obtain a WAR (Web Archive), "maven war" command should be
+issued. This will create a complete WAR with the name axis2.war inside the
+target directory.</p>
+
+<p>Once this build step is complete, the binaries are ready to be
+deployed.</p>
+
+<h3><a name="_Toc96698086"></a>Installing Axis2 in a Servlet container</h3>
+<ol>
+  <li>Download Axis2 war file</li>
+  <li>Drop the war in the webapps folder. Most servlet containers will
+    automatically install war. (some servlet containers may require a restart
+    in order to capture the new web application. Refer your servlet container
+    documentation for more information about this.)</li>
+  <li>Once the WAR is successfully installed, test it by pointing the web
+    browser to the <strong>http:// &lt;host :port&gt;/ axis2. </strong>It
+    should produce the following page.</li>
+
+  <p align="center"><strong><img src="images/clip_image006.jpg"></strong></p>
+
+  <p></p>
+  <li>Use validate link to ensure that everything is fine and smooth. If the
+    validation fails then the war has failed to install properly or some
+    essential jars are missing. At such a situation the documentation of the
+    particular servlet container should be consulted to find the problem. The
+    following page is a successful validation. Note the statement core Axis2
+    libraries are present.
+    <p></p>
+  </li>
+
+  <p align="center"><strong><img src="images/happyaxis.jpg"></strong></p>
+</ol>
+
+<p></p>
+
+<h4><a name="upload">Uploading services</a></h4>
+<ol>
+  <p>The Axis2 web application also provides an interface to upload services.
+  Once a service is created according to the service specification as
+  described in userguide that jar file can be uploaded using the upload
+  page.</p>
+
+  <p align="center"><strong><img src="images/clip_image010.jpg"
+  alt=""></strong></p>
+
+  <p>The uploaded jar files will be stored in the default service directory.
+  For Axis2 this will be the &lt;webapps&gt;/axis2/WEB-INF/services
+  directory. Once a service is uploaded it will be installed instantly.</p>
+
+  <p>Since Axis2 supports hot deployment one can drop the service jar
+  directly through the file system to the above mentioned services
+  directory.It will also cause the service to be automatically installed
+  without the container being restarted.</p>
+
+  <p>Use the <i>available services link</i> to check the successful
+  installation of a service. The services and the operations of successfully
+  installed services will be displayed in the available services page.</p>
+
+  <p align="center"><img src="images/clip_image012.jpg"
+  alt=""></p>
+
+  <p></p>
+
+  <p>If the service has deployment time error it will list those services
+  as faulty services. If you click on the link you can see the your deployment
+  fault error message(s).</p>
+
+  <p align="center"><img src="images/faultservice.jpg"
+  alt=""></p>
+
+  <p>Deployment time error message</p>
+
+  <p align="center"><strong><img src="images/faultmsg.jpg"
+  alt=""></strong></p>
+
+  <p>  </p>
+
+  <p>Axis2 Administration is all about configuring Axis2 at the run time and
+  the configuration will be transient. More descriptions are available in <a
+  href="webadminguide.html">Axis2 Web Administration Guide</a></p>
+</ol>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/0_94/userguide1.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/userguide1.html?rev=370124&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/userguide1.html (added)
+++ webservices/axis2/trunk/java/xdocs/0_94/userguide1.html Wed Jan 18 03:13:48 2006
@@ -0,0 +1,231 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 User's Guide</title>
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<p><i>Version 0.94</i></p>
+<i>User Feedback: <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>
+
+<p align="right">Pages: <a href="userguide.html"
+target="_blank">Content</a>, <b>1</b>, <a href="userguide2.html"
+target="_blank">2</a>, <a href="userguide3.html" target="_blank">3</a>, <a
+href="userguide4.html" target="_blank">4</a>, <a href="userguide5.html"
+target="_blank">5</a></p>
+
+<h2><a name="Introduction">Introduction</a></h2>
+
+<p>Welcome to Axis2, the next generation of Apache Axis!!! This User's Guide
+will help you to understand what Axis2 has to offer and how to get started
+with it. We hope you will benefit from the power of Axis2.</p>
+
+<h3><a name="Attention">Attention</a></h3>
+<ul>
+  <li><p style="margin-bottom: 0in">This User's Guide is written based on
+    Axis2 standard binary distribution. (The standard binary distribution can
+    be created from the source distribution using the maven goal <code>$maven
+    dist-std-bin</code>). Please refer the <a
+    href="installationguide.html#Download_Axis2">installation guide</a> for further
+    information on the downloadables available in this release.</p>
+  </li>
+  <li><p>If you are new to Axis, it's highly recommended that you read <a
+    href="http://ws.apache.org/axis/java/user-guide.html" target="_blank">Axis 1.x User's
+    Guide</a> before you go any further in this guide.</p>
+  </li>
+</ul>
+
+<h3><a name="What_is_Axis2_">What is Axis2?</a></h3>
+
+<p>Axis2 is the next generation of Apache Axis. In late August 2004, during
+the Axis2 Summit held in Colombo, Sri Lanka, a new architecture for Axis was
+introduced which was much more flexible, efficient and configurable. Although
+the architecture is new, some of the well established concepts from Axis 1.x
+like handlers are preserved in Axis2. Axis2 comes with many new features,
+enhancements and industry specification implementations.</p>
+
+<p>After months of continued discussion and coding in this direction, Axis2
+now delivers the following key features:</p>
+<ul>
+  <li><p style="margin-bottom: 0in"><strong>Speed</strong> - Axis2 uses its
+    own object model and StAX (Streaming API for XML) parsing to achieve
+    significantly greater speed than earlier versions of Apache Axis.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Low memory foot print</strong>-
+    Axis2 was designed ground-up keeping low memory foot print in mind.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>AXIOM</strong> - Axis2 comes with
+    its own light-weight object model, AXIOM, for message processing which is
+    extensible, high performance and developer convenient</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong><a name="Hot_Deployment">Hot
+    Deployment</a></strong> - Axis2 is equipped with the capability of
+    deploying web service &amp; handlers while system is up and running. In
+    other words, new services can be added to the system without having to
+    shut down server.Drop the required Web service archive into the services
+    directory in the repository and deployment model will automatically
+    deploy the service and make it available for use.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Asynchronous Web
+    Services</strong> - Axis2 now supports asynchronous web services &amp;
+    asynchronous web services invocation using non-blocking clients and
+    transports .</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>MEP Support</strong> - Axis2 now
+    comes handy with the flexibility to support Message Exchange Patterns
+    (MEPs) with in-built support for basic MEPs defined in WSDL 2.0.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Flexibility</strong> - The Axis2
+    architecture gives the developer complete freedom to insert extensions
+    into the engine for custom header processing, system management, or
+    <em>anything else you can imagine</em>.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Stability</strong> - Axis2
+    defines a set of published interfaces which change relatively slowly
+    compared to the rest of Axis.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Component-oriented
+    Deployment</strong> - You can easily define reusable networks of Handlers
+    to implement common patterns of processing for your applications, or to
+    distribute to partners.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Transport Framework</strong> - We
+    have a clean and simple abstraction for integrating and using Transports
+    (i.e., senders and listeners for SOAP over various protocols such as
+    SMTP, FTP, message-oriented middleware, etc), and the core of the engine
+    is completely transport-independent.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>WSDL support</strong> - Axis2
+    supports the <a href="http://www.w3.org/TR/wsdl" target="_blank">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 Axis2.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Add-ons</strong> Several web
+    services specifications have been incorporated including <a
+    href="http://ws.apache.org/wss4j/" target="_blank">WSS4J</a> for security, <a
+    href="http://ws.apache.org/sandesha/" target="_blank">Sandesha</a> for reliable
+    messaging, <a href="http://ws.apache.org/kandula/" target="_blank">Kandula</a> which is
+    an encapsulation of WS-Coordination, WS-AtomicTransaction and
+    WS-BusinessActivity.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Composition and
+    Extensibility</strong> - modules and phases improve support for
+    composability and extensibility. Modules supports composability and is
+    able to add support for new WS-* specifications in a simple and clean
+    manner. They are however not <a href="#Hot_Deployment">hot deployable</a>
+    as they change the overall behavior of the system.</p>
+  </li>
+</ul>
+
+<p>We hope you enjoy using Axis2. 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 us a hand! The Axis developer community welcomes your
+participation.</p>
+
+<p>Let us know what you think!</p>
+
+<p>Please send your feedback on Axis2 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>
+
+<h3><a name="Axis2_Complete_Features_List">Axis2 Complete Features
+List</a></h3>
+<ol type="1">
+  <li>AXIOM, an XML object model working on StAX (Streaming API for XML)
+    parsing optimized for SOAP 1.1/1.2 Messages. This has complete XML
+    infoset support.</li>
+  <li>Support for One-Way Messaging (In-Only) and Request Response Messaging
+    (In-Out)</li>
+  <li>Module Architecture, mechanism to extend the SOAP Processing Model</li>
+  <li>Module version support , can have multiple versions of the same module
+    and use them depending on the requirement.</li>
+  <li>Content hierarchy</li>
+  <li>Archive based deployment Model and Directory based deployment model</li>
+  <li>JWS like deployment (making Java class into Web service)</li>
+  <li>WSDL Code Generation Tool for Stub and skeletons</li>
+  <li>WS-Addressing, both the submission (2004/08) and final (2005/08)
+    versions</li>
+  <li>WSS4J module for security</li>
+  <li>Improved and user friendly Client API</li>
+  <li>WSDL2Java</li>
+  <li>REST (REpresentational State Transfer) Support</li>
+  <li>Transports supports: HTTP, SMTP, TCP, JMS</li>
+  <li>Raw XML providers</li>
+  <li>Support for MTOM/ MIME/ SwA</li>
+  <li>SAAJ implementation</li>
+  <li>DOOM - New Feature</li>
+  <li>Pack/Unpack capability for the generated code- New Feature</li>
+  <li>Axis Data Binding - ADB (Framework and Schema Compiler)</li>
+  <li>Numerous bug fixes since last release</li>
+</ol>
+
+<h4><a name="Experimental_Features_List">Experimental Features List</a></h4>
+<ol type="1">
+  <li>Sessions scoping for Application, SOAP, Transport and Request
+  levels</li>
+  <li><a href="WS_policy.html" target="_blank">Server side Web Service Policy
+    support</a></li>
+  <li>?wsdl and ?xsd support</li>
+  <li>Java2WSDL</li>
+  <li>Generating ServiceClient for a given WSDL and invoke the corresponding
+    service using generated client.</li>
+</ol>
+
+<h4><a name="Major_Changes_Since_Last_Release">Major Changes Since Last
+Release</a></h4>
+<ol type="1">
+  <li>Fixing of memory leaks</li>
+  <li>Client API changes , Introducing ServiceClient instead of MEPClient,
+    InOnlyMEPClient, InOutMEPClient, Call. (Please note that the above
+    classes will be deprecated in this release.)</li>
+  <li>Module versioning support , can have multiple versions of the same
+    module and use them depending on the requirement.</li>
+  <li>Code generator improved to process multi-port WSDL's properly</li>
+  <li>Packing and unpacking options for the code generated classes</li>
+</ol>
+
+<h3><a name="Tools_included_in this_Release">Tools Included In This
+Release</a></h3>
+<ol type="1">
+  <li>Axis2 Web Application (Web App)</li>
+  <li>WSDL2WS- <a href="CodegenTools-EclipsePlugin.html" target="_blank">Eclipse
+    plugin</a><a>/</a><a href="CodegenToolReference.html" target="_blank">Command line
+    version</a><a>/</a><a
+    href="tools\idea\Idea_plug-in_userguide.html#WSDL2Java_Code_Generation" target="_blank">IntelliJ
+    IDEA plugin</a></li>
+  <li>Service Archive Wizard- <a
+    href="ServiceArchiveToolReference.html" target="_blank">Eclipse plugin</a>/ <a
+    href="tools\idea\Idea_plug-in_userguide.html#Create_Service_Archive" target="_blank">IntelliJ
+    IDEA plugin</a></li>
+</ol>
+<a href="http://ws.apache.org/axis2/download.cgi" target="_blank">Download</a> above plugins
+
+<h3><a name="What's_still_to_do_">What's Still To Do?</a></h3>
+
+<p>See list of what we think needs to be done, and consider helping out if
+you're interested &amp; able!</p>
+<ol type="1">
+  <li>JAX-RPC 1.1 and/or JAX-WS compliance</li>
+  <li>SOAP Encoding</li>
+  <li>Binary serialization and de-serialization support</li>
+  <li>Management Interface for Axis2</li>
+  <li>Implementation of other Transports.</li>
+  <li>Resource framework implementation (WS-RF) and Enterprise web services
+    such as JSR 109 support</li>
+  <li>Completion of interop tests</li>
+</ol>
+
+<p align="right"><a href="userguide.html" target="_blank"><img
+src="images/arrow_left.gif"> Previous</a> | <a href="userguide2.html"
+target="_blank">Next <img src="images/arrow_right.gif"></a></p>
+
+Pages: <a href="userguide.html" target="_blank">Content</a>,
+<b>1</b>, <a href="userguide2.html" target="_blank">2</a>, <a href="userguide3.html"
+target="_blank">3</a>, <a href="userguide4.html" target="_blank">4</a>, <a
+href="userguide5.html" target="_blank">5</a></body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/0_94/userguide2.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/userguide2.html?rev=370124&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/userguide2.html (added)
+++ webservices/axis2/trunk/java/xdocs/0_94/userguide2.html Wed Jan 18 03:13:48 2006
@@ -0,0 +1,395 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+      "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+  <title>Axis2 User's Guide</title>
+  <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<p><i>Version 0.94</i></p>
+<i>User Feedback: <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>
+
+<p align="right">Pages: <a href="userguide.html"
+target="_blank">Content</a>, <a href="userguide1.html" target="_blank">1</a>,
+<b>2</b>, <a href="userguide3.html" target="_blank">3</a>, <a
+href="userguide4.html" target="_blank">4</a>, <a href="userguide5.html"
+target="_blank">5</a></p>
+
+<b><font size="4">Note (on samples):</font></b> In this page of the user's
+guide we will look at how to write and deploy Web Services using Axis2. All
+the user's guide samples are located in the <b>"samples/userguide/src"</b>
+directory of the binary distribution.
+
+<h2><a name="Web_Services_Using_Axis2">Web Services Using Axis2</a></h2>
+
+<p>Before starting, please check whether you have deployed the "axis2.war" in
+your servlet container and it is working properly. (See <a
+href="installationguide.html" target="_blank">Installation Guide</a>). User
+can select any of the  following two ways of writing web services using
+Axis2. </p>
+<ol>
+  <li><a href="#Writing_Web_Services_Using Axis2's_Primary_APIs">Use Axis2's primary interfaces (APIs) and implement
+    the business logic.</a></li>
+  <li><p><a href="#Writing_Web_Services_by_Code_Generating_Skeleton">Start from the WSDL -&gt;Code generate the
+    Skeleton -&gt;Implement the Business Logic.</a></p>
+  </li>
+</ol>
+
+<h3><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">Writing Web
+Services Using Axis2's Primary APIs</a></h3>
+
+<h4><a name="Creating_Web_Service__MyService_">Creating Web Service
+(MyService)</a></h4>
+
+<p>First let's see how we can write a simple Web Service (MyService) using
+Axis2's primary interfaces and deploy it. For this purpose we will create a
+Web Service with two operations as follows.</p>
+<pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
+public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and 
+                                          //responds with another OMElement after processing.</pre>
+
+<p>Complete code for this example Web Service (MyService) can be found in the
+"Axis2Home/samples/userguide/src" directory under "userguide/example1"
+package. As you can see, the two operations are very simple and need no
+explanations on what they do. Now let's see how we can write the deployment
+descriptors for the service and deploy it.</p>
+
+<h4><a name="How_to_write_the_Web_Service_">How to write the Web
+Service?</a></h4>
+Writing a new Web Service with Axis2 involve four steps:
+<ol>
+  <li><p style="margin-bottom: 0in">Write the Implementation Class</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Write a services.xml file to explain the
+    Web Service</p>
+  </li>
+  <li><p style="margin-bottom: 0in">create a *.aar archive (Axis Archive) for
+    the Web Service</p>
+  </li>
+  <li><p>Deploy the Web Service</p>
+  </li>
+</ol>
+
+<h4><a name="Step1_:Write_the_Implementation_Class">Step1 :Write the
+Implementation Class</a></h4>
+
+<p>Provides a implementation class that provide the business logic for the
+Web Service, it should have methods that match the operations in the Web
+Service. Unless you have data binding the signature of the methods can have
+one parameter of type OMElement.</p>
+<pre>public class MyService{
+    public void ping(OMElement element){
+     ......
+    }
+    public OMElement echo(OMElement element){
+     ......
+    }
+}</pre>
+
+<h4><a name="Step2_:Write_the_services_xml_file">Step2 :Write the
+services.xml file</a></h4>
+
+<p>Axis2 uses "services.xml" to keep configurations for a Web Service. Each
+Web Service deployed in Axis2 needs a "services.xml" containing the
+configurations. "services.xml" for MyService will be as follows.</p>
+<pre>&lt;service &gt;
+    &lt;description&gt;
+        This is a sample Web Service with two operations, echo and ping.
+    &lt;/description&gt;
+    &lt;parameter name="ServiceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;
+    &lt;operation name="echo"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+     &lt;operation name="ping"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
+    &lt;/operation&gt;
+ &lt;/service&gt;</pre>
+
+<p><em>The above XML tags can be explained as follows:</em></p>
+
+<p>Name of the service will be the name of the archive file , if and only if
+the services.xml contains only one service element.</p>
+
+<p>Next comes the description and the service class.</p>
+
+<p>The next two xml tags describe the operations that are available in this
+service with respective message receivers. For the "echo" operation we have
+used a <strong>RawXMLINOutMessageReceiver</strong> since it is an IN-OUT
+operation. For IN-ONLY operation "ping", we have used
+<strong>RawXMLINOnlyMessageReceiver</strong> as the message receiver.</p>
+
+<p>You can write a services.xml file to include a group of services instead
+of a single service. This makes management and deployment of a set of related
+services very easy. At runtime you can share information between these
+services within a single interaction using the ServiceGroupContext. If you
+hope to use this functionality, the services.xml file should have following
+format.</p>
+<pre>&lt;serviceGroup&gt;
+  &lt;service name="Service1"&gt;
+    &lt;!-- details for Service1 --&gt;
+  &lt;/service&gt;
+  &lt;service name="Service2"&gt;
+    &lt;!-- details for Service2 --&gt;
+  &lt;/service&gt;
+  &lt;module ref="ModuleName" /&gt;
+  &lt;parameter name="serviceGroupParam1" locked="false"&gt;value 1&lt;/parameter&gt;
+&lt;/serviceGroup&gt;</pre>
+
+<p>Note : name of the service is a compulsory attribute</p>
+
+<h4><a name="Step3_:Create_the_Web_Service_Archive">Step3 :Create the Web
+Service Archive</a></h4>
+
+<p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web
+Services. Therefore, for MyService we will use "MyService.aar" with the
+"services.xml" packaged in the META-INF as shown in the following picture.</p>
+
+<p><img src="images/userguide/ServiceItems.jpg" name="Graphic1"
+align="bottom" width="176" height="91" border="0"></p>
+
+<p>To create "MyService.aar" user can first create a jar file containing all
+the files necessary for the service and then rename the "jar" to "aar" so
+that Axis2 understands it as a service archive. This has already been created
+in the "Axis2Home/samples/userguide" directory. Now let's use it...</p>
+
+<h4><a name="Step4_:Deploy_the_Web_Service">Step4 :Deploy the Web
+Service</a></h4>
+
+<p>Deploying the service  is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "MyService.aar" into the
+"<b>services</b>" directory. Once these steps are completed, start the
+servlet container (if you have not already started) and check the link
+"Services" on the <a href="http://localhost:8080/axis2/index.jsp"
+target="_blank">Home Page of Axis2 Web Application</a>
+(http://localhost:8080/axis2/index.jsp) and see whether the MyService is
+deployed properly. If you can see the following output then you have
+successfully deployed MyService on Axis2.</p>
+
+<p align="center"><img src="images/userguide/MyServiceDeployed.jpg"
+name="Graphic2" align="bottom" width="734" height="766" border="0"></p>
+
+<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool on Axis2 Web Application's Administration module. (See the <a
+href="webadminguide.html" target="_blank">Web Administration Guide</a> for
+more information on this)</p>
+
+<h3><a name="Writing_Web_Services_by_Code_Generating_Skeleton">Writing Web
+Services by Code Generating Skeleton</a></h3>
+
+<p>This is the second method of writing Web Services using Axis2. Let's see
+how we can generate the skeleton from a given WSDL and implement the business
+logic using Axis2. For this we use Axis2SampleDocLit.wsdl that can be found
+in the <b>wsdl</b> directory under samples.</p>
+
+<h4><a name="WSDL2Java_Tool">WSDL2Java Tool</a></h4>
+
+<p>To generate the skeleton and the required classes you can use the
+WSDL2Java tool provided in Axis2. This tool is located in the bin directory
+of the distribution and can be executed using the provided scripts (.bat or
+.sh). The tool's parameter list is as follows and user can specify these
+values depending on their requirements.</p>
+<pre>Usage WSDL2Code -uri  :WSDL file location
+-o  : output file location
+-a : Generate async style code only. Default if off
+-s : Generate sync style code only. Default if off. takes precedence over -a
+-p  : set custom package name
+-l  : valid languages are java and csharp. Default is java
+-t : Generate TestCase to test the generated code
+-ss : Generate server side code (i.e. skeletons).Default is off
+-sd : Generate service descriptor (i.e. axis2.xml).Default is off.Valid with -ss</pre>
+
+<p>We will use the tool with the following parameters and generate the
+skeleton and the other required classes.</p>
+
+<p>Windows users can use the following command in the console:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -d xmlbeans -ss -sd -o ..\samples -p org.apache.axis2.userguide</pre>
+
+<p>Linux users should switch the file separator:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans -ss -sd -o ../samples -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required classes in the <b>src</b> directory inside
+samples, and the schema classes in <strong>schema</strong> directory also
+inside samples. Note that these are not source files and should be availed in
+the class path in order to compile the generated classes</p>
+
+<h4><a name="Implement_the_Business_Logic">Implement the Business Logic</a></h4>
+
+<p>Locate the skeleton class that can be found under src/userguide directory
+with the name "Axis2SampleDocLitPortTypeSkeleton.java". This is the skeleton
+for our web service and we can now easily implement the business logic. The
+WSDL we have used has three operations:<!--<li><p style="margin-bottom: 0in">echoVoid   - Operation that does not
+accept any input parameters  and also provide no out put parameters. Just
+perform some task </p>
+</li>-->
+</p>
+<ul>
+  <li><p style="margin-bottom: 0in">echoString  - Operation that echoes a
+    String value </p>
+  </li>
+  <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
+    string array as the input and echoes them back</p>
+  </li>
+  <li><p>echoStruct - Operation that accept a Struct as the input and echoes
+    them back.</p>
+  </li>
+</ul>
+<!--<h4>echoVoid   </h4>
+
+<p>Locate the following code segment  in the
+"Axis2SampleDocLitPortTypeSkeleton.java"  and fill the business logic. For
+the explanation purpose we do not need anything to be implemented here.</p>
+<pre>public  void echoVoid(){
+//Todo fill this with the necessary business logic
+}</pre> -->
+
+<h4><a name="echoString">echoString</a></h4>
+
+<p>Locate the following code segment  in the
+"Axis2SampleDocLitPortTypeSkeleton.java"  and fill the business logic as
+shown below.</p>
+<pre> public  org.soapinterop.xsd.EchoStringArrayReturnDocument 
+                echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2){
+    //To do fill this with the necessary business logic
+    return null;
+ }</pre>
+
+<p>Once filled with the business logic it will be as follows. The code is
+simple and the explanations are given as comments.</p>
+<pre>public org.soapinterop.xsd.EchoStringReturnDocument 
+                          echoString(org.soapinterop.xsd.EchoStringParamDocument param6) {
+   //Use the factory to create the output document.
+   EchoStringReturnDocument retDoc = EchoStringReturnDocument.Factory.newInstance();
+   //send the string back.
+   retDoc.setEchoStringReturn(param6.getEchoStringParam());
+   return retDoc;
+}</pre>
+
+<p>Similarly following code fragments shows how you can fill the business
+logic for our first web service.</p>
+
+<h4><a name="echoStringArray">echoStringArray</a></h4>
+<pre>public org.soapinterop.xsd.EchoStringArrayReturnDocument 
+                echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2) {
+
+    //Use the factory to create the output document.
+    EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
+
+    //Get the String array from the input parameters.
+    String[] inParams = param2.getEchoStringArrayParam().getStringArray();
+    ArrayOfstringLiteral retParams = ArrayOfstringLiteral.Factory.newInstance();
+    //Set the input parameters to the output parameters for echoing.
+    for (int i = 0; i &lt; inParams.length; i++) {
+        retParams.addString(inParams[i]);
+    }
+
+    //return the output document.
+    retDoc.setEchoStringArrayReturn(retParams);
+    return retDoc;
+}</pre>
+
+<h4><a name="echoStruct">echoStruct</a></h4>
+<pre>public org.soapinterop.xsd.EchoStructReturnDocument 
+                echoStruct(org.soapinterop.xsd.EchoStructParamDocument param4) {
+  
+   //Use the factory to create the output document.
+   EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
+  
+   //Get the SOAPStrcut from the incoming parameters
+   SOAPStruct inStruct = param4.getEchoStructParam();
+   
+   //Struct for the sending back
+   SOAPStruct outStruct = SOAPStruct.Factory.newInstance();
+   
+   //Fill the outgoing struct
+   outStruct.setVarFloat(inStruct.getVarFloat());
+   outStruct.setVarInt(inStruct.getVarInt());
+   outStruct.setVarString(inStruct.getVarString());
+   //Set the outgoing document.
+   retDoc.setEchoStructReturn(outStruct);
+  
+   return retDoc;
+}</pre>
+
+<h4><a name="services_xml">services.xml</a></h4>
+
+<p> Axis2 uses "services.xml" to hold the configurations for a particular web
+service deployed in the Axis2 engine. When we generate the skeleton using the
+WSDL2Java tool, it will also generate the required services.xml for this web
+service as well. This can be found in the same directory as the skeleton. The
+generated services.xml is as follows.</p>
+<pre>&lt;!--Auto generated Axis Service XML--&gt;
+&lt;service name="Axis2SampleDocLitPortTypeSkeletonTest"&gt;
+    &lt;parameter locked="xsd:false" name="ServiceClass"&gt;userguide.Axis2SampleDocLitPortTypeSkeleton&lt;/parameter&gt;
+    &lt;!--Mounting the method echoStringArray--&gt;
+    &lt;operation name="echoStringArray"&gt;
+    &lt;messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/&gt;
+    &lt;/operation&gt;
+    &lt;!--Mounting the method echoStruct--&gt;
+    &lt;operation name="echoStruct"&gt;
+    &lt;messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/&gt;
+    &lt;/operation&gt;
+    &lt;!--Mounting the method echoString--&gt;
+    &lt;operation name="echoString"&gt;
+    &lt;messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/&gt;
+    &lt;/operation&gt;
+&lt;/service&gt;</pre>
+
+<p>First line of the "services.xml" gives the name of the Web Service. This
+is used in the URL to the service as the service name. Next comes the
+description and the service class. The next xml tags describe the operations
+that are available in this service with respective message receivers.</p>
+
+<h4><a name="Packaging">Packaging</a></h4>
+
+<p>Next step in the process is to package the classes in a .aar (axis2
+archive) and deploy it in Axis2. When the WSDL2Java tool generate the
+skeleton it will also generate the required data binding classes. These
+schema related classes are located in the <b>schema </b>directory of the
+generated code. Copy this to your class path, compile the skeleton and the
+supporting classes. In order to create the .aar file, let's create the
+following directory structure with the required files and then simply use jar
+command to package it.</p>
+
+<p><img src="images/userguide/DirectoryStructure.JPG" align="bottom"
+width="164" height="142" border="0"></p>
+
+<p>Go to the top level directory where you can find the class files for the
+above service (i.e. one level up on the directory structure shown above),
+then type the following command in a command line.</p>
+<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitPortType.aar .</pre>
+
+<p>Deploying the service  is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "echo.aar" into the "<b>services</b>"
+directory. Once these steps are completed, please start the servlet container
+(if you have not already started) and check the link "Services" on the <a
+href="http://localhost:8080/axis2/index.jsp" target="_blank">Home Page of
+Axis2 Web Application</a> (http://localhost:8080/axis2/index.jsp) and see
+whether the Axis2SampleDocLitPortType is deployed properly. If you can see
+the following output then you have successfully deployed
+Axis2SampleDocLitPortType on Axis2.</p>
+
+<p align="center"><img src="images/userguide/ServiceDeployed.JPG"
+name="Graphic4" align="bottom" width="734" height="764" border="0"></p>
+
+<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool on Axis2 Web Application's Administration module. (See the <a
+href="webadminguide.html" target="_blank">Web Administration Guide</a> for
+more information on this)</p>
+
+<p align="right"><a href="userguide1.html" target="_blank"><img
+src="images/arrow_left.gif"> Previous</a> | <a href="userguide3.html"
+target="_blank">Next <img src="images/arrow_right.gif"></a></p>
+
+<p>Pages: <a href="userguide.html" target="_blank">Content</a>, <a
+href="userguide1.html" target="_blank">1</a>, <b>2</b>, <a
+href="userguide3.html" target="_blank">3</a>, <a href="userguide4.html"
+target="_blank">4</a>, <a href="userguide5.html" target="_blank">5</a></p>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/0_94/userguide3.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/0_94/userguide3.html?rev=370124&view=auto
==============================================================================
--- webservices/axis2/trunk/java/xdocs/0_94/userguide3.html (added)
+++ webservices/axis2/trunk/java/xdocs/0_94/userguide3.html Wed Jan 18 03:13:48 2006
@@ -0,0 +1,508 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+      "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+  <title>Axis2 User's Guide</title>
+  <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<p><i>Version 0.94</i></p>
+<i>User Feedback: <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>
+
+<p align="right">Pages: <a href="userguide.html"
+target="_blank">Content</a>, <a href="userguide1.html" target="_blank">1</a>,
+<a href="userguide2.html" target="_blank">2</a>, <b>3</b>, <a
+href="userguide4.html" target="_blank">4</a>, <a href="userguide5.html"
+target="_blank">5</a></p>
+
+<p><b><font size="4">Note (on samples):</font></b> In this page of the user's
+guide we will look at how to write Web Service Clients using Axis2. All the
+user's guide samples are located at the <b><font
+color="#000000">"samples/userguide/src"</font></b> directory of the binary
+distribution. So... let's explore the samples.</p>
+
+<h2><a name="Web_Service_Clients_Using_Axis2">Web Service Clients Using Axis2</a></h2>
+
+<p>Now let's see how we can write a Web Service Client to use this Web
+Service.</p>
+
+<p>Web services can be used to provide wide range of functionality to the
+users ranging from simple, less time consuming  operations such as
+"getStockQuote"  to time consuming business services. When we utilize (invoke
+using client applications) these Web Service we cannot use some simple
+generic invocation paradigm that suites all the timing complexities involved
+in the service operations. For example, if we use a single transport channel
+(such as HTTP) to invoke a Web Service with and IN-OUT operation that take
+long time to complete, then most of the time we may end up with "connection
+time outs". On the other hand, if there are simultaneous service invocations
+that  we need to perform from a single client application, then the use of a
+"blocking" client API will degrade the performance of the client application.
+Similarly there are various other consequences such as One-Way transports
+that come in to play when we need them. Let's try to analyze some common
+service invocation paradigms.</p>
+
+<p>Many web service engines provide the users with a Blocking and
+Non-Blocking client APIs.</p>
+<ul>
+  <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
+    invocation is called, the client application hangs and only gets control
+    back when the operation completes, after which client receives a response
+    or a fault. This is the simplest way of invoking Web Services and it also
+    suites many business situations.</p>
+  </li>
+  <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
+    hence once a service invocation is called, the client application
+    immediately gets the control back and the response is retrieved using the
+    callback object provided. This approach provides the flexibility to the
+    client application to invoke several Web Services simultaneously without
+    blocking the operation already invoked.</p>
+  </li>
+</ul>
+
+<p>Both these mechanisms work in the API level. Let's name the  asynchronous
+behavior that we can get using the <strong>Non-Blocking API</strong> as
+<b>API Level Asynchrony.</b></p>
+
+<p>Both these mechanisms use single transport connection to send the request
+and to receive the response. They severely lags the capability of using two
+transport connections for the request and the response (either One-Way of
+Two-Way). So both these mechanisms fail to address the problem of long
+running transactions (the transport connection may time-out before the
+operation completes). A possible solution would be to use <strong>two
+separate transport connections for request and response</strong>. The
+asynchronous behavior that we gain using this solution can be called
+<b>Transport Level Asynchrony</b>.</p>
+
+<p>By combining API Level Asynchrony &amp; Transport Level Asynchrony we can
+obtain four different invocation patterns for web services as shown in the
+following table.</p>
+<a name="table1"></a>
+
+<table width="100%" border="1" cellpadding="0" cellspacing="0">
+  <tbody>
+    <tr>
+      <td width="33%" height="19"><p><strong>API
+        (Blocking/Non-Blocking)</strong></p>
+      </td>
+      <td width="33%"><p><strong> Dual Transports (Yes/No)</strong></p>
+      </td>
+      <td width="33%"><p><strong>Description</strong></p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>Simplest and the familiar invocation pattern</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>Using callbacks or polling</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is useful when the service operation is IN-OUT
+        in nature but the transport used is One-Way (e.g. SMTP)</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is can be used to gain the maximum asynchronous
+        behavior. No blocking in the API level and also in the transport
+        level</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<p>Axis2 provides the user with all these possibilities to invoke Web
+Services.</p>
+
+<p>Below we describe how to write Web Services Clients using Axis2. This can
+be done in two methods:</p>
+<ol>
+  <li><a href="#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Using the Axis2's primary APIs</a></li>
+  <li><p><a href="#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Using stubs generated with data binding
+    support</a>, making the life easy for developers writing Web Service
+    client applications</p>
+  </li>
+</ol>
+
+<h3><a name="Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
+Web Service Clients Using Axis2's Primary APIs</a></h3>
+
+<h4><a name="EchoBlockingClient">EchoBlockingClient</a></h4>
+
+<p>Axis2 provides the user with several invocation patterns for Web Services,
+ranging from pure blocking single channel invocations to a non-blocking dual
+channel invocations. Let's first see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest blocking invocation. The
+client code you need to write is as follows.</p>
+<pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+<font color="#33cc00">            Options options = new Options();
+            options.setTo(targetEPR);
+            options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
+            options.setUseSeparateListener(false);
+
+            ServiceClient serviceClient = new ServiceClient();
+            serviceClient.setOptions(options);</font>
+
+<font color="#33cc00">            OMElement result = sender.sendReceive(payload);</font>
+
+            StringWriter writer = new StringWriter();
+            result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance().createXMLStreamWriter(writer)));
+            writer.flush();
+
+            System.out.println(writer.toString());
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } catch (XMLStreamException e) {
+            e.printStackTrace();
+        }
+}</pre>
+
+<p>The green lines shows the set of operations that you need to perform
+inorder to invoke a web service. The rest is used to create the OMElement
+that needs to be sent and display the response OMElement. To test this
+client, use the provided ant build file that can be found in the
+"Axis2Home/samples" directory. Run the "testEchoBlockingClient" target . If
+you can see the response OMElement printed in your command line,  then you
+have successfully tested the client. </p>
+
+<h4><a name="PingClient">PingClient</a></h4>
+
+<p>In the Web Service "MyService" we had a IN-ONLY operation with the name
+"ping" (see <a href="userguide2.html#Web_Services_Using_Axis2" tareget="_blank">Web Services Using
+Axis2</a>). Let's write a client to invoke this operation. The client code is
+as follows:</p>
+<pre> try {
+       OMElement payload = ClientUtil.getPingOMElement();
+       Options options = new Options();
+       options.setTo(targetEPR);
+       ServiceClient serviceClient = new ServiceClient();
+       serviceClient.setOptions(options);
+       serviceClient.fireAndForget(payload);
+
+     } 
+catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+     }</pre>
+
+<p>Since we are accessing a IN-ONLY operation we can directly use the
+"fireAndForget()" in ServiceClient to invoke this operation , and that will
+not block the invocation, hence it will return the control immediately back
+to the client. You can test this client by running the target
+"testPingClient" of the ant build file at "Axis2Home/samples".</p>
+
+<p>We have invoked the two operations in our service. Are we done? No! There
+are lot more to explore. Let's see some other ways to invoke the same
+operations...</p>
+
+<h4><a name="EchoNonBlockingClient">EchoNonBlockingClient</a></h4>
+
+<p>In the EchoBlockingClient once the "serviceCleint.sendReceive(payload);"
+is called, the client is blocked till the operation is completed. This
+behavior is not desirable when there are many Web Service invocations to be
+done in a single client application. A solution would be to use a
+Non-Blocking API to invoke web services. Axis2 provides a callback based
+non-blocking API for users.</p>
+
+<p>A sample client for this can be found under
+"Axis2Home/samples/userguide/src/userguide/clients" with the name
+EchoNonBlockingClient. If we consider the changes that user may have to do
+with respect to the "EchoBlockingClient" that we have already seen, it will
+be as follows:</p>
+<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
+
+<p>The invocation accepts a callback object as a parameter. Axis2 client API
+provides an abstract Callback with the following methods:</p>
+<pre>public abstract void onComplete(AsyncResult result);
+public abstract void onError(Exception e);
+public boolean isComplete() {}</pre>
+
+<p>The user is expected to implement the "onComplete " and "onError " methods
+of their extended call back class. Axis2 engine calls the onComplete method
+once the Web Service response is received by the Axis2 Client API
+(ServiceClient). This will eliminate the blocking nature of the Web Service
+invocations and provides the user with the flexibility to use Non Blocking
+API for Web Service Clients.</p>
+
+<p>To run the sample client ( EchoNonBlockingClient) you can simply use the
+"testEchoNonBlockingClient" target of the ant file found at the
+"Axis2Home/samples" directory.</p>
+
+<h4><a name="EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></h4>
+
+<p>The solution provided by the Non-Blocking API has one limitation when it
+comes to  Web Service invocations which takes long time to complete. The
+limitation is due to the use of single transport connection to invoke the Web
+Service and to retrieve the response. In other words, client API provides a
+non blocking invocation mechanism for the users, but the request and the
+response comes in a single transport (Two-Way transport) connection (like
+HTTP). Long running Web Service invocations or Web Service invocations using
+One-Way transports (like SMTP) cannot be utilized by simply using a non
+blocking invocation. </p>
+
+<p>The trivial solution is to use separate transport connections (either
+One-Way or Two-Way) for the request and response. The next problem that needs
+to be solved is the correlation (correlating the request and the response).
+<a href="http://www.w3.org/Submission/ws-addressing/"
+target="_blank">WS-Addressing</a> provides a neat solution to this using
+&lt;wsa:MessageID&gt; and &lt;wsa:RelatesTo&gt; headers. Axis2 provides
+support for addressing  based correlation mechanism and a complying Client
+API to invoke Web Services with two transport connections. (Core of Axis2
+does not depend on WS-Addressing, but contains a set of parameters like in
+addressing that can be populated in any means. WS-Addressing is one of the
+users that may populate them. Even the transports can populate these. Hence
+Axis2 has the flexibility to use different versions of addressing)</p>
+
+<p>Users can select between Blocking or Non-Blocking APIs for the Web Service
+clients with two transport connections. By simply using a boolean flag, the
+same API can be used to invoke web services (IN-OUT operations) using two
+separate transport connections. Let's see how it's done using an example.
+Following code fragment shows how to invoke the same "echo" operation using
+Non-Blocking API with two transport connections<strong>. The ultimate
+asynchrony!!</strong></p>
+<pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+            Options options = new Options();<br>            options.setTo(targetEPR);<br>            options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
+
+            //The boolean flag informs the axis2 engine to use two separate transport connection
+            //to retrieve the response.
+<br>            options.setUseSeparateListener(true); 
+            
+            ServiceClient serviceClinet = new ServiceClinet();
+<br>            serviceClinet.setOptions(options);</pre>
+<pre>                  
+            //Callback to handle the response
+            Callback callback = new Callback() {
+                public void onComplete(AsyncResult result) {
+                    try {
+                        StringWriter writer = new StringWriter();
+                        result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance()
+                                                                .createXMLStreamWriter(writer)));
+                        writer.flush();
+
+                        System.out.println(writer.toString());
+
+                    } catch (XMLStreamException e) {
+                        onError(e);
+                    }
+                }
+
+                public void onError(Exception e) {
+                    e.printStackTrace();
+                }
+            };
+
+            //Non-Blocking Invocation
+            serviceClinet.sendReceiveNonblocking(payload, callback);
+
+            //Wait till the callback receives the response.
+            while (!callback.isComplete()) {
+                Thread.sleep(1000);
+            }
+          <font color="#33cc00">serviceClinet.finalizeInvoke();</font>
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } catch (Exception ex) {
+            ex.printStackTrace();
+        }</pre>
+
+<p><font color="#0000ff"><font color="#000000">The boolean flag (value true)
+in the "<b>options.setUseSeparateListener(...)</b>" method informs the Axis2
+engine to use separate transport connections for request and response.
+Finally "<b>serviceClinet.finalizeInvoke()</b>" informs the Axis2 engine to
+stop the client side listener started to retrieve the
+response.</font></font></p>
+
+<p>Before we run the sample client we have one more step to perform. As
+mentioned earlier Axis2 uses addressing based correlation mechanism, hence we
+need to "engage" addressing module in the server side as well. According to
+the Axis2 architecture, addressing module is deployed in the
+"<strong>pre-dispatch</strong>" phase (See <a
+href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
+more details about phases)  and hence "engaging" means simply adding module
+reference in the "axis2.xml" (NOT the "services.xml"). Now add the following
+line to the "axis2.xml" that you can find in the "/webapps/axis2/WEB-INF"
+directory in the servlet container. </p>
+<pre style="margin-bottom: 0.2in"> &lt;module ref="addressing"/&gt;</pre>
+
+<p>Note: <font color="#000000">Once you change the "axis2.xml" you need to
+restart the servlet container.</font></p>
+
+<p>This will enable the addressing in the server side. Now you can test the
+"TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
+target of the ant file found at "Axis2Home/samples" directory. If you see the
+response OMElement printed in the client side, then you have successfully
+tested the Non Blocking API with two transport channels at the client
+side.</p>
+
+<h4><a name="EchoBlockingDualClient">EchoBlockingDualClient</a></h4>
+
+<p>This is again a Two-Way transport request/response client, but this time,
+we use a Blocking API in the client code. Sample code for this can be found
+in the "Axis2Home/samples/userguide/src/userguide/clients/" directory and the
+explanation is similar to the <a
+href="#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a>, except that
+here we do not use a callback object to handle response. This is a very
+useful mechanism when the service invocation is IN-OUT in nature and the
+transports are One-Way (e.g. SMTP). For the sample client we use two HTTP
+connections for request and response. User can test this client using the
+"echoBlockingDualClient" target of the ant build file found in the
+"Axis2Home/samples" directory.</p>
+
+<p>See <a href="http-transport.html" target="_blank">Configuring
+Transports</a> for use different transports.</p>
+
+<h3><a
+name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
+Web Service Clients using Code Generation with Data Binding Support</a></h3>
+
+<p>Axis2 provides the data binding support for Web Service client as well.
+The user can generate the required stubs from a given WSDL with the other
+supporting classes. Let's generate stubs for the WSDL used earlier to
+generate the skeleton for the "Axis2SampleDocLitPortType". Simply run the
+WSDL2Java tool that can be found in the bin directory of the Axis2
+distribution using the following command:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required stub "Axis2SampleDocLitPortTypeStub.java"
+that can be used to invoke the Web Service Axis2SampleDocLitPortType. Let's
+see how we can use this stub to write Web Service clients to utilize the Web
+Service Axis2SampleDocLitPortType (the service that we have already
+deployed).</p>
+
+<h4><a name="Client_for_echoVoid_Operation">Client for echoVoid
+Operation</a></h4>
+
+<p>Following code fragment shows the necessary code for utilizing the
+echoVoid operation of the Axis2SampleDocLitPortType that we have already
+deployed. In this operation, a blank SOAP body element is sent to the Web
+Service and the same SOAP envelope is echoed back.</p>
+<pre> try {
+   //Create the stub by passing the AXIS_HOME and target EPR.
+   //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+   Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null, 
+                                "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+   stub.echoVoid();
+
+} catch (Exception e) {
+    e.printStackTrace();
+}</pre>
+
+<h4><a name="Client_for_echoString_Operation">Client for echoString
+Operation</a></h4>
+
+<p>Following code fragment shows the necessary code for utilizing the
+echoString operation of the Axis2SampleDocLitPortType that we have already
+deployed. The code is very simple to understand and the explanations are in
+the form of comments.</p>
+<pre>try {
+     //Create the stub by passing the AXIS_HOME and target EPR.
+     //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME 
+     Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
+                                "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+     //Create the request document to be sent.
+     EchoStringParamDocument  reqDoc= EchoStringParamDocument.Factory.newInstance();
+     reqDoc.setEchoStringParam("Axis2 Echo");
+     //invokes the web service.
+     EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
+     System.out.println(resDoc.getEchoStringReturn());
+
+    } catch (Exception e) {
+        e.printStackTrace();
+    }</pre>
+
+<p>Similarly following code fragments show client side code for
+echoStringArray operation and echoStruct operation respectively.</p>
+
+<h4><a name="Client_for_echoStringArray_Operation">Client for echoStringArray
+Operation</a></h4>
+<pre>try {
+     //Create the stub by passing the AXIS_HOME and target EPR.
+     //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+     Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+                                "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+
+     //Create the request document to be sent.
+     EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
+     ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
+
+     paramArray.addString("Axis2");
+     paramArray.addString("Echo");
+
+      reqDoc.setEchoStringArrayParam(paramArray);
+      EchoStringArrayReturnDocument resDoc = stub.echoStringArray(reqDoc);
+
+      //Get the response params
+      String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
+
+      for (int i = 0; i &lt; resParams.length; i++) {
+           System.out.println(resParams[i]);
+      }
+      } catch (Exception e) {
+        e.printStackTrace();
+      }</pre>
+
+<h4><a name="Client_for_echoStruct_Operation">Client for echoStruct
+Operation</a></h4>
+<pre>try {
+    //Create the stub by passing the AXIS_HOME and target EPR.
+    //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+    Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null, 
+                                "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+    //Create the request Document
+    EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
+
+    //Create the complex type
+    SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
+
+    reqStruct.setVarFloat(100.50F);
+    reqStruct.setVarInt(10);
+    reqStruct.setVarString("High");
+
+    reqDoc.setEchoStructParam(reqStruct);
+
+    //Service invocation
+    EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
+    SOAPStruct resStruct = resDoc.getEchoStructReturn();
+
+    System.out.println("floot Value :" + resStruct.getVarFloat());
+    System.out.println("int Value :" + resStruct.getVarInt());
+    System.out.println("String Value :" + resStruct.getVarString());
+
+} catch (Exception e) {
+    e.printStackTrace();
+}</pre>
+
+<p align="right"><a href="userguide2.html" target="_blank"><img
+src="images/arrow_left.gif"> Previous</a> | <a href="userguide4.html"
+target="_blank">Next <img src="images/arrow_right.gif"></a></p>
+
+<p>Pages: <a href="userguide.html" target="_blank">Content</a>, <a
+href="userguide1.html" target="_blank">1</a>, <a href="userguide2.html"
+target="_blank">2</a>, <b>3</b>, <a href="userguide4.html"
+target="_blank">4</a>, <a href="userguide5.html" target="_blank">5</a></p>
+</body>
+</html>