axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cha...@apache.org
Subject svn commit: r453167 [6/6] - in /webservices/axis2/trunk/java/xdocs: ./ adb/ adb/images/ images/ images/archi-guide/ images/userguide/ jibx/ resources/ resources/schemas/
Date Thu, 05 Oct 2006 09:56:40 GMT
Added: webservices/axis2/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/userguide.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/userguide.html (added)
+++ webservices/axis2/trunk/java/xdocs/userguide.html Thu Oct  5 02:56:34 2006
@@ -0,0 +1,1483 @@
+<!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">
+<h1 align="center"><a name="_Toc96697849" id="_Toc96697849">Apache</a> Axis2
+User's Guide</h1>
+
+<p>This guide will help you get started with Axis2, the next generation of
+Apache Axis! It describes in details how to write Web services and Web
+service clients using Axis2; how to write custom modules and how to use them
+with a Web service. Advanced Topics and Samples which are shipped with the
+binary distribution of Axis2, are also discussed.</p>
+
+<h2>Content</h2>
+<ul>
+  <li><p><a href="#Introduction">Introduction</a></p>
+  </li>
+  <li><p><a href="#Web_Services_Using_Axis2">Web Services Using Axis2</a></p>
+    <ul>
+      <li><a href="#Getting_started">Getting Started</a></li>
+      <li><a href="#Writing_Web_Services_Using Axis2's_Primary_APIs">Writing
+        Web Services using Axis2 APIs</a>
+        <ul>
+          <li><a href="#How_to_write_the_Web_Service_">How to write the Web
+            Service?</a>
+            <ul>
+              <li><a href="#Step1_:Write_the_Implementation_Class">Step1
+                :Write the Implementation Class</a></li>
+              <li><a href="#Step2_:Write_the_services_xml_file">Step2 :Write
+                the services.xml file</a></li>
+              <li><a href="#Step3_:Create_the_Web_Service_Archive">Step3
+                :Create the Web Service Archive</a></li>
+              <li><a href="#Step4_:Deploy_the_Web_Service">Step4 :Deploy the
+                Web Service</a></li>
+            </ul>
+          </li>
+        </ul>
+      </li>
+      <li><p><a
+        href="#Writing_Web_Services_by_Code_Generating_Skeleton">Writing Web
+        Services by Code Generating Skeleton</a></p>
+        <ul>
+          <li><a href="#How_to_write_the_Web_Service_2">How to write the Web
+            Service?</a>
+            <ul>
+              <li><a href="#Step1_:Generate_skeleton">Step 1: Generate
+                Skeleton Code</a></li>
+              <li><a href="#Step2_Implement_Business_Logic">Step2 :Implement
+                Business Logic</a></li>
+              <li><a href="#Step3_:Verify_services_xml">Step3 :Verify
+                services.xml file</a></li>
+              <li><a href="#Step4_Create_archive">Step4 :Create the Web
+                Service Archive file</a></li>
+              <li><a href="#Step5_Deploy_web_service">Step5 :Deploy the Web
+                Service</a></li>
+            </ul>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ul>
+<ul>
+  <li><p><a href="#Axis2_User's_Guide">Web Service Clients Using Axis2</a></p>
+    <ul>
+      <li><a
+        href="#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
+        Web Service Clients using Axis2's Primary APIs</a>
+        <ul>
+          <li><a href="#EchoBlockingClient">EchoBlockingClient</a></li>
+          <li><a href="#PingClient">PingClient</a></li>
+          <li><a href="#EchoNonBlockingClient">EchoNonBlockingClient</a></li>
+          <li><a
+            href="#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></li>
+          <li><a
+          href="#EchoBlockingDualClient">EchoBlockingDualClient</a></li>
+        </ul>
+      </li>
+      <li><p><a
+        href="#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
+        Web Service Clients using Code Generation with Data Binding
+        Support</a></p>
+        <ul>
+          <!--<li><a href="#Client_for_echoVoid_Operation">Client
+          for echoVoid Operation</a></li>-->
+          <li><a href="#Client_for_echoString_Operation">Client for
+            echoString Operation</a></li>
+          <li><a href="#Client_for_echoStringArray_Operation">Client for
+            echoStringArray Operation</a></li>
+          <li><a href="#Client_for_echoStruct_Operation">Client for
+            echoStruct Operation</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><p><a href="#Axis2_User's_Guide">Modules</a></p>
+    <ul>
+      <li><a href="#MyService_with_a_Logging_Module">MyService with a Logging
+        Module</a>
+        <ul>
+          <li><a href="#Step1_:_LoggingModule_Class">Step1 : LoggingModule
+            Class</a></li>
+          <li><a href="#Step2_:_LogHandler">Step2 : LogHandler</a></li>
+          <li><a href="#Step3_:_module_xml">Step3 : module.xml</a></li>
+          <li><a href="#Step_4:_Modify_the_&quot;axis2_xml&quot;">Step 4:
+            Modify the "axis2.xml"</a></li>
+          <li><a href="#Step5_:_Modify_the_&quot;services_xml&quot;">Step5 :
+            Modify the "services.xml"</a></li>
+          <li><a href="#Step6_:_Packaging">Step6 : Packaging</a></li>
+          <li><a href="#Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy
+            the Module in Axis2</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><p><a href="#Axis2_User's_Guide">Other Samples</a></p>
+    <ul>
+      <li><a href="#Google_Spell_Checker_Sample">Google Spell Checker
+        Sample</a></li>
+      <li><a href="#Google_Search_Sample">Google Search Sample</a></li>
+      <li><a href="#Amazon_Queuing_Service">Amazon Queuing Service</a></li>
+    </ul>
+  </li>
+  <li><p>Advanced Topics</p>
+    <ul>
+      <li><a href="rest-ws.html" target="_blank">RESTful Web Services</a></li>
+      <li><a href="tcp-transport.html" target="_blank">TCP Transport</a></li>
+      <li><a href="mail-transport.html" target="_blank">Mail
+      Transport</a></li>
+      <li><a href="http-transport.html" target="_blank">HTTP
+      Transports</a></li>
+      <li><a href="jms-transport.html" target="_blank">JMS Transports</a></li>
+      <li><a href="mtom-guide.html" target="_blank">MTOM with Axis2</a></li>
+      <li><a href="../modules/wss4j/1_0/security-module.html"
+        target="_blank">Securing SOAP Messages with Apache Rampart</a></li>
+    </ul>
+  </li>
+</ul>
+
+<h2><a name="Introduction">Introduction</a></h2>
+
+<p>This User's Guide is written based on <a
+href="../download/1_1/download.html/#std-bin">Axis2 standard binary
+distribution</a>. The standard binary distribution can be directly <a
+href="[preferred]/ws/axis2/1_1/axis2-std-1.1-bin.zip"
+title="[preferred]/ws/axis2/1_1/axis2-std-1.1-bin.zip">downloaded</a> or
+built using the <a href="../download/1_1/download.html#src">standard source
+distribution</a>. If you choose to go for the latter, then <a
+href="installationguide.html">Installation Guide</a> will instruct you on how
+to build Axis2 Standard Binary Distribution using the Source.</p>
+
+<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! Send your feedback on Axis2 to "<a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Make sure
+to prefix the subject of the mail with [Axis2].</p>
+
+<h2><a name="Web_Services_Using_Axis2">Web Services Using Axis2</a></h2>
+
+<p>In this section, we will learn how to write and deploy Web services using
+Axis2. All the samples mentioned in this giude are located in the
+<b>"samples\userguide\src"</b> directory of <a
+href="../download/1_1/download.html/#std-bin">Axis2 standard binary
+distribution</a>.</p>
+
+<h3><a name="Getting_started">Getting Started</a></h3>
+
+<p>Please deploy axis2.war in your servlet container and ensure that it works
+fine. <a href="installationguide.html" target="_blank">Installation Guide</a>
+gives you step by step instructions on just how to build axis2.war and deploy
+it in your servlet container.</p>
+
+<p>Users can use either one of the following methods to write 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>
+
+<p>The complete code of the example Web service - MyService which will be
+used in this exercise is found in the "Axis2_HOME/samples/userguide/src"
+directory of Axis2 binary distribution, under "userguide/example1"
+package.</p>
+
+<h3><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">1. Writing Web
+Services Using Axis2's Primary APIs</a></h3>
+In our example, the web service will have two operations.
+<pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and does some processing.
+public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and  
+                                          // sends back the same again </pre>
+
+<h4><a name="How_to_write_the_Web_Service_">How to write a Web
+Service?</a></h4>
+Writing a new Web service with Axis2 involves 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 style="margin-bottom: 0in">Deploy the Web service</p>
+  </li>
+</ol>
+
+<h4><a name="Step1_:Write_the_Implementation_Class">Step1 :Write the
+Implementation Class</a></h4>
+
+<p>An implementation class has the business logic for the Web service and
+implements the operations provided by the Web service. Unless you have data
+binding, the signature of the methods can have only one parameter of type
+OMElement.</p>
+
+<p><span style="color: #FF0000">OMElement is .... </span>For more details see
+<a href="http://ws.apache.org/commons/axiom/OMTutorial.html">OM
+Tutorial</a>.</p>
+<pre>public class MyService{
+    public void ping(OMElement element){
+        // Business Logic     
+        ......
+    }
+    public OMElement echo(OMElement element){
+     ......
+    }
+}</pre>
+
+<h4><a name="Step2_:Write_the_services_xml_file">Step2 :Write the
+services.xml file</a></h4>
+
+<p>"services.xml" has the configuration for a web Service. Each web service,
+deployed in Axis2 , must have its configuration in "services.xml". The
+configuration for MyService is 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;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
+    &lt;/operation&gt;
+     &lt;operation name="ping"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
+        &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
+    &lt;/operation&gt;
+ &lt;/service&gt;</pre>
+
+<p><em>The above XML tags can be explained as follows:</em></p>
+
+<p>1. The description of the service class is provided in the description
+tag.</p>
+<pre>&lt;service &gt;
+    &lt;description&gt;
+        This is a sample Web service with two operations, echo and ping.
+    &lt;/description&gt;</pre>
+
+<p>2. The name of the service class is provided as a parameter.</p>
+<pre>&lt;parameter name="serviceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;</pre>
+
+<p>3. The "operation" xml tag describes the operations that are available in
+this service with respective message receivers.</p>
+<pre>   &lt;operation name="echo"&gt;
+            &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+            &lt;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="ping"&gt;
+       &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
+       &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
+   &lt;/operation&gt;</pre>
+
+<p>4. Every operation must map to a corresponding MessageReceiver class.
+After a message is processed by the handlers, Axis2 engine hands it over to a
+MessageReceiver.</p>
+
+<p>5. 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>6. The actionMapping is required only if you want to enable WS-Addressing.
+This will be used later in this user guide.</p>
+
+<p>7. 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 the
+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 uses ".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 in directory structure shown below.
+Please note that the name of the archive file will be same as that of the
+service only if the services.xml contains only one service element.</p>
+
+<p><img src="images/userguide/ServiceItems.jpg" name="Graphic1"
+align="bottom" width="176" height="91" border="0"></p>
+
+<p>To create the archive file, you can create a jar file containing all the
+necessary files and then rename it to .aar file.This archive file can be
+found in the "Axis2_HOME/samples/userguide" directory. This file now has to
+be deployed.</p>
+
+<h4><a name="Step4_:Deploy_the_Web_Service">Step4 : Deploy the Web
+Service</a></h4>
+
+<p>The service can be deployed by dropping dropping the ".aar" file in to
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
+Start the servlet container (if you have not already started) and check the
+link "Services" on the <a href="http://localhost:8080/axis2/"
+target="_blank">Home Page of Axis2 Web Application</a>
+(http://localhost:8080/axis2) and see whether the MyService is deployed
+properly. If you can see the following output then you have successfully
+deployed MyService on Axis2. Congratulations !!</p>
+
+<p align="center"><img src="images/userguide/MyServiceDeployed.jpg"
+name="Graphic2" align="bottom" 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. Please refer
+to the <a href="webadminguide.html" target="_blank">Web Administration
+Guide</a> for more information.</p>
+
+<h3><a name="Writing_Web_Services_by_Code_Generating_Skeleton">2. Writing Web
+Services by Code Generating Skeleton</a></h3>
+
+<p>This is the second method of writing Web services using Axis2. In this
+method, we generate the skeleton from a given WSDL and implement the business
+logic in the classes generated. For this example, we will use
+Axis2SampleDocLit.wsdl. This can be found in the <b>"samples\wsdl</b>"
+directory of the binary distribution.</p>
+
+<h4><a name="How_to_write_the_Web_Service_2">How to write a Web
+Service?</a></h4>
+This method of writing a Web service with Axis2 involves five steps:
+<ol>
+  <li><p style="margin-bottom: 0in">Generate the skeleton code</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Add business logic</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Verify generated services.xml</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Create a *.aar archive (Axis Archive) for
+    the Web service</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Deploy the Web service</p>
+  </li>
+</ol>
+
+<h4><a name="Step1_:Generate_skeleton">Step1 : Generate Skeleton Code</a></h4>
+
+<p>To generate the skeleton and 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 users can specify these values
+depending on their requirements.</p>
+<pre>Usage WSDL2Code -uri &lt;Location of WSDL&gt; : WSDL file location
+-o &lt;output Location&gt; : output file location
+-a : Generate async style code only. Default is off
+-s : Generate sync style code only. Default is off. takes precedence over -a
+-p &lt;package name&gt; : set custom package name
+-l &lt;language&gt; : 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. services.xml). Default is off. Valid with -ss
+-d &lt;databinding&gt; : valid databinding(s) are adb, xmlbeans and jaxme. Default is adb
+-g Generates all the classes. valid only with the -ss
+-pn &lt;port_name&gt; : name of port in the presence of multiple ports
+-sn &lt;service_name&gt; : name of service in the presence of multiple services
+-u : unpacks the databinding classes
+-r &lt;repository_path&gt; : path of the repository against which code is generated</pre>
+
+<p>The parameters for wsdl2java tool in our example are as follows:</p>
+<strong>Windows</strong> <!--<p>Windows users can use the following command in the console:</p> -->
+
+<pre style="margin-bottom: 0.2in">WSDL2Java.bat -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ..\samples -p org.apache.axis2.userguide</pre>
+<strong>Linux</strong> <!--<p>Linux users should switch the file separator:</p> -->
+
+<pre style="margin-bottom: 0.2in">WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ../samples -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required classes in the <b>"sample\src"</b>
+directory, and the schema classes in
+<strong>"samples\resources\schemaorg_apache_xmlbeans"</strong>
+directory<strong></strong>. Note that these are not source files and should
+be available in the class path in order to compile the generated classes.</p>
+
+<h4><a name="Step2_Implement_Business_Logic">Step 2: Implement Business
+Logic</a></h4>
+
+<p>Implement the business logic in the skeleton class. The skeleton class
+"Axis2SampleDocLitServiceSkeleton.java" can be found in
+<strong>"samples/src/org/apache/axis2/userguide</strong>" directory. Our
+sample WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong>
+directory 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  - echoes a String value </p>
+  </li>
+  <li><p style="margin-bottom: 0in">echoStringArray - echoes a String
+    Array</p>
+  </li>
+  <li><p style="margin-bottom: 0in">echoStruct - echoes a Struct</p>
+  </li>
+</ul>
+<!--<h4>echoVoid   </h4>
+
+<p>Locate the following code segment  in 
+"Axis2SampleDocLitServiceSkeleton.java"  and add 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
+"Axis2SampleDocLitServiceSkeleton.java"  and add the business logic as shown
+below.</p>
+<pre> public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString
+   (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4 ){
+      //Todo fill this with the necessary business logic
+      throw new  java.lang.UnsupportedOperationException();
+   }
+ </pre>
+
+<p>Once the business logic is added, the source code appears as below:</p>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString
+   (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
+   //Use the factory to create the output document.
+   EchoStringReturnDocument retDoc = EchoStringReturnDocument.Factory.newInstance();
+   //send the string back.
+   retDoc.setEchoStringReturn(param4.getEchoStringParam());
+   return retDoc;
+ }</pre>
+
+<h4><a name="echoStringArray">echoStringArray</a></h4>
+
+<p>The code segment for echoStringArray is shown below:</p>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument echoStringArray
+   (org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument param0) throws Exception {
+   //Use the factory to create the output document.
+   EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
+   //Get the String array from the input parameters.
+   String[] inParams = param0.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>
+
+<p>The code segment for echoStruct is shown below:</p>
+<pre>public org.apache.axis2.userguide.xsd.EchoStructReturnDocument echoStruct
+     (org.apache.axis2.userguide.xsd.EchoStructParamDocument param2) throws Exception {
+     //Use the factory to create the output document.
+     EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
+
+     //Get the SOAPStrcut from the incoming parameters
+     SOAPStruct inStruct = param2.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="Step3_:Verify_services_xml">Step3 : Verify Generated
+services.xml</a></h4>
+
+<p>As mentioned earlier, "services.xml" file holds all the configuration
+information for a Web service. When the skeleton is generated using the
+WSDL2Java tool, the services.xml file is also generated. This file can be
+found in the same directory as the skeleton. The generated services.xml is as
+follows.</p>
+<pre>&lt;!-- This file was auto-generated from WSDL --&gt;
+&lt;!-- by the Apache Axis2 version: #axisVersion# #today# --&gt;
+&lt;serviceGroup&gt;
+  &lt;service name="Axis2SampleDocLitService"&gt;
+   &lt;messageReceivers&gt;
+      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" 
+      class="org.apache.axis2.userguide.Axis2SampleDocLitServiceMessageReceiverInOut"/&gt;
+   &lt;/messageReceivers&gt;
+   &lt;parameter locked="false" name="ServiceClass"&gt;
+   org.apache.axis2.userguide.Axis2SampleDocLitServiceSkeleton&lt;/parameter&gt;
+   &lt;operation name="echoStringArray" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoStringArray&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="echoStruct" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoStruct&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="echoString" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoString&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+  &lt;/service&gt;
+&lt;/serviceGroup&gt;</pre>
+
+<p>1. 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.</p>
+
+<p>2. Next comes the description and the service class.</p>
+
+<p>3. The following xml tags describe the operations that are available in
+this service with respective message receivers.</p>
+
+<h4><a name="Step4_Create_archive">Step 4: Create Archive File</a></h4>
+
+<p>The next step is to package the classes in an .aar (axis2 archive) and
+deploy it in Axis2. When the WSDL2Java tool generates the skeleton, it will
+also generate the required data binding classes. These schema related classes
+are located in the
+<strong>"samples\resources\schemaorg_apache_xmlbeans</strong>" directory of
+the generated code. Copy this to your class path, compile the skeleton and
+the supporting classes. To create the .aar file, create the following
+directory structure with the required files and then jar it up.</p>
+
+<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
+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 run the following on the command line</p>
+<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitService.aar</pre>
+
+<h4><a name="Step5_Deploy_web_service">Step 5: Deploy Web Service</a></h4>
+
+<p>The service can be deployed by dropping dropping the ".aar" file in to
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet
+container.Start the servlet container (if you have not already started) and
+check the link "Services" on the <a href="http://localhost:8080/axis2/"
+target="_blank">Home Page of Axis2 Web Application</a>
+(http://localhost:8080/axis2) and see whether the Axis2SampleDocLitService is
+deployed properly. If you can see the following output then you have
+successfully deployed Axis2SampleDocLitService on Axis2. Congratulations
+!!</p>
+
+<p align="center"><img src="images/userguide/ServiceDeployed.jpg"
+name="Graphic4" align="bottom" 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>
+
+<h2><a name="Web_Service_Clients_Using_Axis2">Web Service Clients Using
+Axis2</a></h2>
+
+<p>Let's see how we can write a Web service Client using Axis2 in order to
+use a Web service. All samples mentioned in this guide are located at the
+<b><font color="#000000">"samples\userguide\src"</font></b> directory of the
+binary distribution. So let's get started!</p>
+
+<p>Web services can be used to provide a wide-range of functionality to user
+from simple, less time consuming  operations such as "getStockQuote"  to time
+consuming business services. When we utilize (invoke using client
+applications) these Web services we cannot use simple generic invocation
+paradigms that suite 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 an IN-OUT operation that takes a long time to
+complete, then most often 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 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 the 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 Non-Blocking API as <b>API Level
+Asynchrony.</b></p>
+
+<p>Both these mechanisms use single transport connections to send the request
+and to receive the response. They severely lag the capability of using two
+transport connections for the request and the response (either One-Way or
+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 two separate
+transport connections for request and response. The asynchronous behavior
+that we gain using this solution can be called <b>Transport Level
+Asynchrony</b>.</p>
+
+<p>By <strong>combining API Level Asynchrony &amp; Transport Level
+Asynchrony</strong> 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>The simplest and more 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. Non 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 life easier for
+    developers writing Web service client applications</p>
+  </li>
+</ol>
+
+<h3><a name="Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">1.
+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 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>
+<source><pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+            <!--<span style="color: #24C113">-->
+
+
+
+
+
+
+            <span style="color: rgb(36, 193, 19);">            
+            Options options = new Options();
+            options.setTo(targetEPR); // this sets the location of MyService service
+            
+            ServiceClient serviceClient = new ServiceClient();
+            serviceClient.setOptions(options);
+
+            OMElement result = serviceClient.sendReceive(payload);
+            </span>
+            System.out.println(result);
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } 
+}</pre>
+</source>
+<p>1. The lines highlighted in green lines show the set of operations that
+you need to perform in order to invoke a Web service.</p>
+
+<p>2. The rest is used to create the OMElement that needs to be sent and
+display the response OMElement.</p>
+
+<p>To test this client, use the provided ant build file that can be found in
+the "<strong>Axis2_HOME/samples/userguide</strong>" 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 an IN-ONLY operation with the name
+"ping" (see <a href="userguide2.html#Web_Services_Using_Axis2">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);
+        /**
+         * We have to block this thread untill we send the request , the problem
+         * is if we go out of the main thread , then request wont send ,so
+         * you have to wait some time :)
+         */
+       Thread.sleep(500);
+     } 
+catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+     }</pre>
+
+<p>Since we are accessing an IN-ONLY operation we can directly use the
+"fireAndForget()" in ServiceClient to invoke this operation. This will not
+block the invocation and 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 "<strong>Axis2Home/samples/userguide</strong>".</p>
+
+<p>We have now invoked the two operations in our service. Are we done? No!
+There's a 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 "serviceClient.sendReceive(payload);"
+is called, the client is blocked till the operation is complete. This
+behavior is not desirable when there are many Web service invocations to be
+done in a single client application or within a GUI. 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
+"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
+the name EchoNonBlockingClient. If we consider the changes that users 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. The 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
+invocation and provide users 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
+"<strong>Axis2_HOME/samples</strong>" 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 take a long time to complete. The
+limitation is due to the use of single transport connections to invoke the
+Web service and to retrieve the response. In other words, client API provides
+a non blocking invocation mechanism for users, but the request and the
+response come 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/2002/ws/addr/" 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 uses 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();
+            options.setTo(targetEPR);
+            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+            options.setUseSeparateListener(true);
+            options.setAction("urn:echo");  // this is the action mapping we put within the service.xml
+
+            //Callback to handle the response
+            Callback callback = new Callback() {
+                public void onComplete(AsyncResult result) {
+                    System.out.println(result.getResponseEnvelope());
+                }
+
+                public void onError(Exception e) {
+                    e.printStackTrace();
+                }
+            };
+            //Non-Blocking Invocation            
+            sender = new ServiceClient();            
+            sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+            sender.setOptions(options);            
+            sender.sendReceiveNonBlocking(payload, callback);            
+            //Wait till the callback receives the response.            
+            while (!callback.isComplete()) {                
+             Thread.sleep(1000);            
+            }            
+            //Need to close the Client Side Listener.        
+            } catch (AxisFault axisFault) {            
+              axisFault.printStackTrace();
+            } catch (Exception ex) {
+              ex.printStackTrace();
+            } finally {
+            try {
+                sender.finalizeInvoke();
+            } catch (AxisFault axisFault) {
+                //have to ignore this
+            }
+        }</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>service.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" the addressing module in both client and server sides.</p>
+
+<h5>Engaging Addressing in the Server Side</h5>
+According to the Axis2 architecture, addressing module put its handlers in
+the "<strong>pre-dispatch</strong>" phase (See <a
+href="Axis2ArchitectureGuide.html#incomingsoap">Architecture Guide</a> for
+more details on 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
+"<strong>/webapps/axis2/WEB-INF/conf</strong>" directory in the servlet
+container.
+<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>
+
+<h5>Engaging Addressing in the Client Side</h5>
+There are two ways of doing this:<br>
+
+<ol>
+  <li>One is to get the addressing-&lt;version&gt;.mar from modules folder of
+    the standard binary distribution. And then making that available in your
+    classpath.</li>
+  <li>The second method is to create a ConfigurationContext giving a
+    repository location. Axis2 has the concept of a repository to keep the
+    services and modules.</li>
+</ol>
+
+<p>You can use the extracted <a
+href="../download/1_1/download.html/#std-bin">standard binary
+distribution</a> itself as the repository as it contains the proper structure
+of an Axis2 repository (having the services and modules folders inside it).
+ConfigurationContext has the runtime context information of the Axis2 system.
+<br>
+</p>
+
+<p>If you have extracted the standard binary distribution to, say,
+$user_home/axis2/dist, then put the following line just before sender = new
+ServiceClient();</p>
+<pre>ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(&lt; Axis2RepositoryLocation &gt;, null);</pre>
+Then replace "sender = new ServiceClient();" line with "sender = new
+ServiceClient(configContext, null);"
+
+<p>This will enable addressing in both client and server sides. Now you can
+test the "TestEchoNonBlockingDualClient" using the
+"testEchoNonBlockingDualClient" target of the ant file found at
+"<strong>Axis2_HOME/samples/userguide</strong>" 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 "<strong>Axis2_HOME/samples/userguide/src/userguide/clients/</strong>"
+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 the 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. Users can test this client using the
+"echoBlockingDualClient" target of the ant build file found in the
+"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+
+<p>See <a href="http-transport.html" target="_blank">Configuring
+Transports</a> for using different transports.</p>
+
+<h3><a
+name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">2.
+Writing Web Service Clients using Code Generation with Data Binding
+Support</a></h3>
+
+<p>Axis2 provides the data binding support for Web service clients as well.
+The user can generate the required stubs from a given WSDL with other
+supporting classes. Let's generate stubs for the WSDL used earlier to
+generate the skeleton for the "Axis2SampleDocLitService". Simply run the
+WSDL2Java tool that can be found in the bin directory of the Axis2
+distribution using the following command:</p>
+
+<p>Windows users can use the following command in the console:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java.bat -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -d xmlbeans -o ..\samples\src -p org.apache.axis2.userguide</pre>
+
+<p>Linux users should switch the file separator to:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans -o ../samples/src -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required stub "Axis2SampleDocLitServiceStub.java"
+that can be used to invoke the Web service Axis2SampleDocLitService. Let's
+see how we can use this stub to write Web service clients to utilize the Web
+service Axis2SampleDocLitService (This is 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>The following code fragment shows the necessary code for utilizing the
+echoString operation of the Axis2SampleDocLitService 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/Axis2SampleDocLitService");
+     //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 the 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/Axis2SampleDocLitService");
+
+     //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/Axis2SampleDocLitService");
+    //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>
+
+<h2><a name="Modules"></a>Modules</h2>
+
+<p>Axis2 provides extended support for modules (See <a
+href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
+more details about modules in Axis2). Let's create a custom module and deploy
+it to MyService which we created earlier.</p>
+
+<p>Following steps show the actions that need to be performed to deploy a
+custom module for a given Web service:</p>
+<ol>
+  <li><p style="margin-bottom: 0in">Create the Module Implementation</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Create the Handlers</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Create the module.xml</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Modify the "axis2.xml" (if you need
+    custom phases)</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Modify the "services.xml" to engage
+    modules at the deployment time.</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Package in a ".mar" (Module Archive)</p>
+  </li>
+  <li><p>Deploy the module in Axis2</p>
+  </li>
+</ol>
+
+<h3><a name="MyService_with_a_Logging_Module">MyService with a Logging
+Module</a></h3>
+
+<p>Let's write a simple logging module for our sample located at
+<b>"samples\userguide\src"</b> directory of the binary distribution. This
+module contains one handler that just logs the message that is passed through
+it. Axis2 uses ".mar" (Module Archive) to deploy modules in Axis2. Following
+diagram shows the file structure inside which needs to be there in the ".mar"
+archive. Let's create all these and see how it works.</p>
+
+<p><img src="images/userguide/ModuleView.jpg" name="Graphic5" align="bottom"
+border="0"></p>
+
+<h4><a name="Step1_:_LoggingModule_Class">Step1 : LoggingModule Class</a></h4>
+
+<p>LoggingModule is the implementation class of the Axis2 module. Axis2
+modules should implement the "<a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/modules/Module.java?rev=396785&amp;view=log">org.apache.axis2.modules.Module</a>"
+interface with the following methods.</p>
+<pre>public void init(ConfigurationContext configContext, AxisModule module) throws AxisFault;//Initialize the module
+public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing
+public void engageNotify(AxisDescription axisDescription) throws AxisFault;</pre>
+
+<p>These methods can be used to control the module initialization and the
+termination. With the input parameter AxisConfiguration, the user is provided
+with the complete configuration hierarchy. This can be used to fine-tune the
+module behavior by the module writers. For the simple logging service we can
+keep these methods blank in our implementation class.</p>
+
+<h4><a name="Step2_:_LogHandler">Step2 : LogHandler</a></h4>
+
+<p>A module in Axis2 can contain, one or more handlers that perform various
+SOAP header processing at different phases. (See<a
+href="Axis2ArchitectureGuide.html#incomingsoap" target="_blank"> Architecture
+Guide</a> for more information on phases). To write a handler one should
+implement <a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&amp;view=log">org.apache.axis2.engine.Handler</a>.
+But for convenience, <a
+href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&amp;view=log">org.apache.axis2.handlers.AbstractHandler</a>
+provides an abstract implementation of the Handler interface.</p>
+
+<p>For the logging module we will write a handler with the following methods.
+"public void invoke(MessageContext ctx);" is the method that is called by
+Axis2 engine when the control is passed to the handler. "public void
+revoke(MessageContext ctx);" is called when the handlers are revoked by the
+Axis2 engine.</p>
+<pre>public class LogHandler extends AbstractHandler implements Handler {
+    private Log log = LogFactory.getLog(getClass());
+    private QName name;
+
+    public QName getName() {
+        return name;
+    }
+
+    public void invoke(MessageContext msgContext) throws AxisFault {
+        log.info(msgContext.getEnvelope().toString());
+    }
+
+    public void setName(QName name) {
+        this.name = name;
+    }
+}</pre>
+
+<h4><a name="Step3_:_module_xml">Step3 : module.xml</a></h4>
+
+<p>"module.xml" contains the deployment configurations for a particular
+module. It contains details such as Implementation class of the module (in
+this example it is the "LoggingModule" class and various handlers that will
+run in different phases). "module.xml" for the logging module will be as
+follows:</p>
+<pre>&lt;module name="logging" class="userguide.loggingmodule.LoggingModule "&gt;
+   &lt;inflow&gt;
+        &lt;handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase" /&gt;
+        &lt;/handler&gt;
+   &lt;/inflow&gt;
+
+   &lt;outflow&gt;
+        &lt;handler name="OutFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/outflow&gt;
+
+   &lt;Outfaultflow&gt;
+        &lt;handler name="FaultOutFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/Outfaultflow&gt;
+
+   &lt;INfaultflow&gt;
+        &lt;handler name="FaultInFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+        &lt;order phase="loggingPhase"/&gt;
+        &lt;/handler&gt;
+   &lt;/INfaultflow&gt;
+&lt;/module&gt;</pre>
+
+<p>As you can see there are four flows defined in this "module.xml"</p>
+<ol>
+  <li>inflow - Represents the handler chain that will run when a message is
+    coming in. </li>
+  <li><p style="margin-bottom: 0in">outflow - Represents the handler chain
+    that will run when the message is going out. </p>
+  </li>
+  <li><p style="margin-bottom: 0in">Outfaultflow - Represents the handler
+    chain that will run when there is a fault and the fault is going out</p>
+  </li>
+  <li><p>INfaultflow - Represents the handler chain that will run when there
+    is a fault and the fault is coming in </p>
+  </li>
+</ol>
+
+<p>Following set of tags describe the name of the handler, handler class and
+the phase in which this handler is going to run. "InFlowLogHandler" is the
+name given for the particular instance of this handler class. The value of
+class attribute is the actual implementation class for this handler. Since we
+are writing logging handler, we can reuse the same handler in all these
+phases. However this may not be the same for all the modules. "&lt;order
+phase="loggingPhase" /&gt;" describes the phase in which this handler
+runs.</p>
+<pre>&lt;handler name="InFlowLogHandler" class="userguide.loggingmodule.LogHandler"&gt;
+&lt;order phase="loggingPhase" /&gt;
+&lt;/handler&gt;</pre>
+
+<p>To learn more about Phase rules, check out the article <a
+href="http://www.developer.com/java/web/article.php/3529321"
+target="_blank">Axis2 Execution Framework</a></p>
+
+<h4><a name="Step_4:_Modify_the_&#34;axis2_xml&#34;">Step 4: Modify the
+"axis2.xml"</a></h4>
+
+<p>In this handler, the phase "loggingPhase", is defined by the module
+writer. It is not a pre-defined handler phase, hence the module writer should
+introduce it to the "axis2.xml" (NOT the services.xml) so that the Axis2
+engine knows where to place the handler in different "flows" ( inFlow,
+outFlow, etc.). Following xml lines show the respective changes made to the
+"axis2.xml" in order to deploy this logging module in the Axis2 engine. This
+is an extract of the phase section of "axis2.xml".</p>
+<pre>&lt;!-- ================================================= --&gt;
+&lt;!-- Phases --&gt;
+&lt;!-- ================================================= --&gt;
+
+&lt;phaseOrder type="inflow"&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;phase name="TransportIn"/&gt;
+        &lt;phase name="PreDispatch"/&gt;
+        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
+            &lt;handler name="AddressingBasedDispatcher"
+                     class="org.apache.axis2.engine.AddressingBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+
+            &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
+                &lt;order phase="PostDispatch"/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--  System pre defined phases       --&gt;
+        &lt;!--   After Postdispatch phase module author or service author can add any phase he wants      --&gt;
+        &lt;phase name="OperationInPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="outflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+        &lt;!--system predefined phases--&gt;
+        &lt;!--these phases will run irrespective of the service--&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;phase name="MessageOut"/&gt;
+    &lt;/phaseOrder/&gt;
+    &lt;phaseOrder type="INfaultflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationInFaultPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="Outfaultflow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutFaultPhase"/&gt;
+        &lt;phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;phase name="MessageOut"/&gt;
+    &lt;/phaseOrder&gt;
+    </pre>
+
+<p>The text in green, the custom phase "loggingPhase" is placed in all the
+flows, hence that phase will be called in all the message flows in the
+engine. Since our module is associated with this phase, the LogHandler inside
+the module will now be executed in this phase.</p>
+
+<h4><a name="Step5_:_Modify_the_&#34;services_xml&#34;">Step5 : Modify the
+"services.xml"</a></h4>
+
+<p>Up to this point we have created the required classes and configuration
+descriptions for the logging module and by changing the "axis2.xml" we have
+created the required phases for the logging module.</p>
+
+<p>Next step is to "<b>engage</b>" (use) this module in one of our services.
+For this, let's use the same Web service that we have used throughout the
+user's guide- MyService. However, since we need to modify the "services.xml"
+of MyService in order to engage this module, we use a separate Web service,
+but with the similar operations.</p>
+
+<p>The code for this service can be found in the
+"<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>"
+directory. The simple changes that we have done to "services.xml' are shown
+in green in the following lines of xml.</p>
+<pre>&lt;service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>"&gt;
+    &lt;description&gt;
+    This is a sample Web service with a logging module engaged.
+    &lt;/description&gt;
+    <span style="color: rgb(36, 193, 19);">&lt;module ref="logging"/&gt;</span>
+    &lt;parameter name="ServiceClass" locked="xsd:false"&gt;userguide.example2.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.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+&lt;/service&gt;</pre>
+
+<p>In this example we have changed the service name (the implementation class
+is very similar to what we have used earlier although it is in a different
+package). In addition we have added the line <b>"&lt;module
+ref="logging"/&gt;"</b> to "services.xml". This informs the Axis2 engine that
+the module "logging" should be engaged for this service. The handler inside
+the module will be executed in their respective phases as described by the
+"module.xml".</p>
+
+<p><b><a name="Step6_:_Packaging">Step6 : Packaging</a></b></p>
+
+<p>Before deploying the module we need to create the ".mar" file for this
+module. This can be done, using the "jar" command and then renaming the
+created jar file. Or you can find the "logging.mar" that is already created
+for you in the "<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+
+<h4><a name="Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy the Module in
+Axis2</a></h4>
+
+<p>Deploying a module in Axis2 require the user to create a directory with
+the name "modules" in the "webapps/axis2/WEB-INF" directory of their servlet
+container and then copying the ".mar" file to that directory. So let's first
+create the "modules" directory and drop the "logging.mar" in to this
+directory.</p>
+
+<p>Although the required changes to the "services.xml" is very little, we
+have created a separate service archive (MyServiceWithModule.aar) for users
+to deploy and see.</p>
+
+<p>Deploy this service using the same steps that you used to <a
+href="#Step4_:Deploy_the_Web_Service">deploy "MyService"</a> and copy the
+"logging.mar" file to the "modules" directory.</p>
+
+<p>Then run using the "TestWebServiceWithModuleClient.bat" or
+"TestWebServiceWithModuleClient.sh" in the
+"<strong>Axis2Home/samples/userguide/src/userguide/clients/bin</strong>"
+directory.</p>
+
+<p>Note: To see logs, the user needs to modify the "log4j.properties" to log
+INFO. The property file is located in
+"<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet container.
+Change the line "log4j.rootCategory= ERROR, LOGFILE" to
+"log4j.rootCategory=INFO, ERROR, LOGFILE".</p>
+
+<p><font size="4"><b>Note (on samples):</b></font> All samples mentioned in
+the user's guide are located at <b>"samples\userguide\src"</b> directory of
+the binary distribution.</p>
+
+<h2><a name="Other_Samples">Other Samples</a></h2>
+
+<p>To show the power of usage of Axis2, three standard samples are shipped
+with the standard binary distribution. These are meant to interact with
+outside Web services and prove the capabilities of the Axis2 system.</p>
+
+<p>The included samples are</p>
+<ul>
+  <li><style="margin-bottom: 0in">Google spell checker sample</li>
+  <li><p style="margin-bottom: 0in">Google search sample</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Amazon queuing sample</p>
+  </li>
+</ul>
+
+<p>A simple introduction to each of the above samples are given below. Each
+sample contains it's own <strong>help document</strong> that speaks about 
+the usage and the advanced operations of that particular sample.</p>
+
+<p>The most obvious place to look for the samples are the <a
+href="Axis2 standard binary distribution#std-bin">standard binary
+distribution</a>. All these samples are included in the
+<strong>samples</strong> directory in the binary distribution. The shell
+scripts and the batch files are in fact written to use the binary
+distribution's root directory as the home in order to find the libraries.</p>
+
+<p>The alternate method is to build the samples from <a
+href="Axis2 standard binary distribution#src">standard source
+distribution</a>. Moving to the "<strong>Axis2_HOME/modules/samples</strong>"
+of the source distribution and running maven will create the samples in the
+"<strong>Axis2_HOME/target/samples</strong>" directory. However, if the
+samples need to be started using the shell scripts (or the batch files) then
+the Axis2_HOME environment need to be set.( the "guessed" Axis2_HOME would
+not be correct in this case)</p>
+
+<h3><a name="Google_Spell_Checker_Sample">Google Spell Checker Sample</a></h3>
+
+<p>This includes a spell checker program that uses the Google spell checking
+service. It demonstrates the blocking and non-blocking modes of calling the
+service. This sample can be found at the
+"<strong>Axis2_HOME/samples/googleSpellcheck</strong>" directory in the Axis2
+standard binary distribution and can be easily started using either the batch
+file or the shell script.</p>
+
+<h3><a name="Google_Search_Sample">Google Search Sample</a></h3>
+
+<p>This includes a search program that uses the familiar Google search over
+the SOAP API. It utilizes the non-blocking mode of the client API. This
+sample can be found at "<strong>Axis2_HOME/samples/googleSearch</strong>"
+directory of the standard binary distribution and can be easily started using
+either the batch file or the shell script.</p>
+
+<h3><a name="Amazon_Queuing_Service">Amazon Queuing Service</a></h3>
+
+<p>Amazon queuing service sample shows how to use the Amazon queuing service.
+It has two user interfaces, one to enqueue and the other to dequeue. This
+sample is included in "<strong>Axis2_HOME/samples/amazonQS</strong>"
+directory of the standard binary distribution with the required batch/shell
+scripts to run the sample.</p>
+
+<h2>Advanced Topics</h2>
+    <ul>
+      <li><a href="rest-ws.html" target="_blank">RESTful Web Services</a></li>
+      <li><a href="tcp-transport.html" target="_blank">TCP Transport</a></li>
+      <li><a href="mail-transport.html" target="_blank">Mail
+      Transport</a></li>
+      <li><a href="http-transport.html" target="_blank">HTTP
+      Transports</a></li>
+      <li><a href="jms-transport.html" target="_blank">JMS Transports</a></li>
+      <li><a href="mtom-guide.html" target="_blank">MTOM with Axis2</a></li>
+      <li><a href="../modules/wss4j/1_0/security-module.html"
+        target="_blank">Securing SOAP Messages with Apache Rampart</a></li>
+    </ul>
+</body>
+</html>

Added: webservices/axis2/trunk/java/xdocs/webadminguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/webadminguide.html?view=auto&rev=453167
==============================================================================
--- webservices/axis2/trunk/java/xdocs/webadminguide.html (added)
+++ webservices/axis2/trunk/java/xdocs/webadminguide.html Thu Oct  5 02:56:34 2006
@@ -0,0 +1,345 @@
+<!-- saved from url=(0022)http://internet.e-mail -->
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title>Apache Axis2 Web Administrator's Guide</title>
+</head>
+
+<body lang="en">
+<h1 align="center">Apache Axis2 Web Administrator's Guide</h1>
+
+<p>This document will give you detailed instructions on administration
+console of Axis2 Web application. Axis2 Administration is all about
+configuring Axis2 at the run time and the configuration will be transient.</p>
+
+<p><i>Send your feedback to: <a
+href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Contents</h2>
+<ul>
+  <li><a href="#Intro">Introduction</a>
+    <ul>
+      <li><p><a href="#login">Login into Administration Site</a></p>
+      </li>
+    </ul>
+  </li>
+  <li><a href="#adminoptions">Administration Options</a>
+    <ul>
+      <li><p><a href="#tools">Tools</a></p>
+        <ul>
+          <li><a href="#upservice">Upload Service</a></li>
+        </ul>
+      </li>
+      <li><p><a href="#syscomponents">System components</a></p>
+        <ul>
+          <li><a href="#heading1">Available services</a></li>
+          <li><a href="#servgroups">Available service groups</a></li>
+          <li><a href="#avmodules">Available modules</a></li>
+          <li><a href="#globalmodules">Globally engaged modules</a></li>
+          <li><a href="#phases">Available phases</a></li>
+        </ul>
+      </li>
+      <li><p><a href="#executionchains">Execution chains</a></p>
+        <ul>
+          <li><a href="#globalchains">Global chains</a></li>
+          <li><a href="#operationchains">Operation specific chains</a></li>
+        </ul>
+      </li>
+      <li><p><a href="#engaginmodule">Engage module</a></p>
+      </li>
+      <li><a href="#services">Services</a>
+        <ul>
+          <li><a href="#turnoffservice">Inactivate Service</a></li>
+          <li><a href="#turnonservice">Activate Service</a></li>
+          <li><a href="#editservicepara">Edit service parameters</a></li>
+        </ul>
+      </li>
+      <li><p><a href="#context">Contexts</a></p>
+        <ul>
+          <li><a href="#viewhierarchy">View Hierarchy</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ul>
+
+<h3><a name="Intro">Introduction</a></h3>
+
+<p>Axis2 Web application has three main sections, 'Services'- lists all the
+available services deployed in this server, 'Validate'-checks the system to
+see whether all the required libraries are in place and views the system
+information, and 'Administration'- Axis2 Web Administration module which is
+the console for administering this Axis2 installation.</p>
+
+<p>Axis2 Web Administration module provides a way to configure Axis2
+dynamically. It's important to note that this dynamic configuration will NOT
+be persistent, i.e. if the servlet container is restarted then all the
+dynamic configuration changes will be lost.</p>
+
+<p><a name="login"></a></p>
+
+<h4>Login into Administration Site</h4>
+
+<p>Once Axis2 is successfully installed, the Web application can be accessed
+(See <a href="installationguide.html">Installation Guide</a> for
+instructions). From <a href="#homepage">Axis2 Web Application Home page</a>
+you can go to Administration page by following 'Administration' link, then
+login page shown below will appear requesting user name and a password. The
+default user name is 'admin' (without quotes) and default password is 'axis2'
+(without quotes).</p>
+
+<p align="center"><img alt="" src="images/adminlogin.jpg"></p>
+
+<p>You can change the user name &amp; password values by changing following
+two parameters in axis2.xml as required.</p>
+
+<p align="center"><img alt="" src="images/parameters.jpg"></p>
+
+<p>If the login is successful you will see the screen below. This is where
+you can view the configuration and the state of the running system and
+dynamically configure it.</p>
+
+<p align="center"><img alt="" src="images/admin.jpg"></p>
+
+<h3><a name="adminoptions">Administration Options</a></h3>
+<ul>
+  <a name="tools"><b>Tools</b></a>
+  <ul>
+    <li><a href="#upservice">Upload Service</a></li>
+  </ul>
+  <a name="syscomponents"><b>System components</b></a>
+  <ul>
+    <li><a href="#heading1">Available services</a></li>
+    <li><a href="#servgroups">Available service groups</a></li>
+    <li><a href="#avmodules">Available modules</a></li>
+    <li><a href="#globalmodules">Globally engaged modules</a></li>
+    <li><a href="#phases">Available phases</a></li>
+  </ul>
+  <a name="executionchains"><b>Execution chains</b></a>
+  <ul>
+    <li><a href="#globalchains">Global chains</a></li>
+    <li><a href="#operationchains">Operation specific chains</a></li>
+  </ul>
+  <b><a href="#engaginmodule">Engage module</a></b> <br>
+
+  <ul>
+    <li>For all Services</li>
+    <li>For a Service Group</li>
+    <li>For a Service</li>
+    <li>For an Operation</li>
+  </ul>
+  <a name="services"><b>Services</b></a>
+  <ul>
+    <li><a href="#turnoffservice">Inactivate service</a></li>
+    <li><a href="#turnonservice">Activate service</a></li>
+    <li><a href="#editservicepara">Edit service parameters</a></li>
+  </ul>
+  <a name="context"><b>Contexts</b></a>
+  <ul>
+    <li><a href="#viewhierarchy">View Hierarchy</a></li>
+  </ul>
+</ul>
+<a name="homepage"></a>
+
+<h3>Axis2 Web Application Home Page</h3>
+
+<p align="center"><strong><img alt=""
+src="images/clip_image006.jpg"></strong></p>
+
+<h3><a name="upservice">Upload Services</a></h3>
+
+<p>You can upload packaged Axis2<em> </em>service archive files using this
+page. This can be done in two simple steps:</p>
+<ul>
+  <li>Browse to the location and select the axisService archive file you wish
+    to upload</li>
+  <li>Then click Upload</li>
+</ul>
+
+<p align="center"><img alt="" src="images/clip_image010.jpg"></p>
+<a name="heading1"></a>
+
+<h3>Available Services</h3>
+
+<p>The functionality of the 'Available Services' option is almost same as the
+functionality of Axis2 Web Application Home page 'Services' option where it
+displays a list of deployed services and their operations. But as an
+additional feature, the 'Available Services' page will list details of
+modules that are engaged to the deployed services and their operations on a
+global, service or on an operation level.</p>
+
+<p>Using the 'Disengage' link one can disengage the corresponding module, as
+long as the module is not globally engaged (engaged to all services and
+operations).</p>
+
+<p>Click on a specific service and it will give you the WSDL file of that
+particular service.</p>
+
+<p><strong>Faulty services</strong> of this system will also be listed on
+this page. Click on each faulty service, it will take you to a page that
+lists the exception stack trace of the exception that caused service to be
+faulty.</p>
+
+<p align="center"><img alt="" src="images/adminmain.jpg"></p>
+<a name="servgroups"></a>
+
+<h3>Available Service Groups</h3>
+
+<p>Service group is a logical collection of related services and the
+'Available Service Groups' link will list all the available service groups in
+the system.</p>
+
+<p align="center"><img alt="" src="images/servicegroups.jpg"></p>
+<a name="avmodules"></a>
+
+<h3>Available Modules</h3>
+
+<p>To view the available modules in the 'modules' directory of the
+'repository' click 'Available Modules' link. This will show you all the
+available modules in the system. Those modules can be engaged dynamically.</p>
+
+<p align="center"><img alt="" src="images/modules.jpg"></p>
+<br>
+<a name="globalmodules"></a>
+
+<h3>Globally Engaged Modules</h3>
+
+<p>From the 'Globally Engaged Modules' link you can view globally engaged
+modules, if any. If a module was engaged globally then the handlers that
+belong to that module will be executed irrespective of the service.</p>
+<a name="phases"></a>
+
+<h3>Available Phases</h3>
+
+<p>The 'Available Phases' link will display all the available phases. In
+Axis2 there are two levels of phases:</p>
+<ul>
+  <li>System predefined phases (not allowed to be changed)</li>
+  <li>User defined phases</li>
+</ul>
+
+<p>The main difference between these two levels is that system predefined
+phases will be invoked irrespective of the services, while user defined
+phases will be invoked when the dispatcher finds the operation. Note that it
+is essential for module developers and service writers to have a good
+understanding of phases and phase ordering.</p>
+
+<p align="center"><img alt="" src="images/viewphases.jpg"></p>
+<br>
+<a name="globalchains"></a>
+
+<h3>Global Chains</h3>
+
+<p>The 'Global Chains' link will display all the Global Execution Chains. The
+most interesting feature of Axis2 Web Administration Module is that it
+provides a very basic way of viewing the global phase list and handlers
+inside the phases depending on both phase and handler orders. This kind of
+information is extremely useful in debugging the system, as there is no other
+way to list out handlers in the global chains. If you engage a new module,
+the new handlers will be added to the global chains and will be displayed on
+this page.</p>
+
+<p align="center"><img alt="" src="images/globalchain.jpg"></p>
+<br>
+<a name="operationchains"></a>
+
+<h3>Operation Specific Chains</h3>
+
+<p>The 'Operation Specific Chains' link can be used to view the handlers
+corresponding to a given service in the same order as it is in the real
+execution chain.</p>
+
+<p align="center"><img alt="" src="images/select_service_for_handler.jpg"></p>
+<br>
+
+
+<p>Select service of which service handlers you wish to view from the list
+box, and click on the 'View' button to view handlers. The page below shows
+service handlers of service <em>version</em></p>
+
+<p align="center"><img alt="" src="images/serviceHandlers.jpg"></p>
+<br>
+<a name="engaginmodule"></a>
+
+<h3>Engaging Modules</h3>
+
+<p>The 'Engaging Modules' link allows to engage modules either globally (to
+all services), to a service group, to a service or to an operation depending
+on the module implementation. If the module was designed to engage the
+handlers globally then handlers in the module can be included in any phase in
+the system. It can be either a system predefined phase or a user defined
+phase.</p>
+
+<p>On the other hand, if the module was implemented in such a way that it is
+going to be deployed to a service or to an operation, then the module cannot
+be included in any of the <a href="#phases">System Predefined Phases</a>.
+Thus it can only be included in <a href="#phases">User Defined Phases</a>.</p>
+
+<p>Immediately after engaging the module you can see the status of engagement
+indicating whether it is engaged properly or not.</p>
+
+<p align="center"><img alt="" src="images/moduleengage.jpg"></p>
+
+<p>�</p>
+<a name="turnoffservice"></a>
+
+<h3>Inactivate Service</h3>
+
+<p>The 'Inactivate Service' link under 'Services' list will lead to the page
+below. Inactivate service functionality provide a way to remove unnecessary
+services from the running system, but the removal is transient which means if
+you restart the system the service will be available.</p>
+
+<p>To inactivate service, select service from list box, tick 'Inactivate
+service' check box, then click on 'Inactivate' button. 'Clear' button will
+clear the 'Inactivate service' check box</p>
+
+<p align="center"><img alt="" src="images/inactivate.jpg"></p>
+<br>
+<a name="turnonservice"></a>
+
+<h3>Activate Service</h3>
+
+<p>The 'Activate Service' link under 'Services' list will lead to the page
+below. Activate service functionality provides a way to activate services
+while the system is running, but the activation is transient which means if
+you restart the system the service will be inactive.</p>
+
+<p>To activate service, select service from list box, tick 'Activate Service'
+check box, then click on 'Activate' button. 'Clear' button will clear the
+'Activate service' check box.</p>
+
+<p align="center"><img alt="" src="images/activate.jpg"></p>
+<br>
+<a name="editservicepara"></a>
+
+<h3>Edit Service Parameters</h3>
+
+<p>This functionality provides a way to change parameters in a service or its
+operations. These changes will be transient too, which means if you restart
+the system changes will not be reflected.</p>
+
+<p>The 'Edit Parameters' link under the 'Services' list on the navigation bar
+will link to the page where you can select services to edit Parameters. Once
+the service is selected click on the 'Edit Parameters' button. This will lead
+to the page below.</p>
+
+<p align="center"><img alt="" src="images/editserviecpara.jpg"></p>
+
+<h3></h3>
+
+<p><a name="viewhierarchy"></a></p>
+
+<h3>View Hierarchy</h3>
+
+<p>By listing current context hierarchy 'View Hierarchy' link provides a
+means to look at the system state at run time. This will list out all the
+available service group contexts, service contexts, operation context and
+etc.</p>
+
+<p></p>
+</body>
+</html>



---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org


Mime
View raw message