axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chinth...@apache.org
Subject svn commit: r290333 [2/2] - /webservices/axis2/trunk/java/xdocs/userguide.html
Date Tue, 20 Sep 2005 02:26:34 GMT

Modified: webservices/axis2/trunk/java/xdocs/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/userguide.html?rev=290333&r1=290332&r2=290333&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/userguide.html (original)
+++ webservices/axis2/trunk/java/xdocs/userguide.html Mon Sep 19 19:26:28 2005
@@ -1,1313 +1,1376 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<HTML>
-<HEAD>
-	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
-	<TITLE>Axis 2.0 User's Guide</TITLE>
-	<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1.4  (Win32)">
-	<META NAME="CREATED" CONTENT="20050918;20224042">
-	<META NAME="CHANGEDBY" CONTENT="Chamikara Jayalath">
-	<META NAME="CHANGED" CONTENT="20050919;1140420">
-</HEAD>
-<BODY LANG="en-US" DIR="LTR">
-<H1 ALIGN=CENTER><A NAME="_Toc96697849"></A>Axis 2.0 User's Guide 
-</H1>
-<H2>Contents</H2>
-<UL>
-	<LI><P><A HREF="#bmIntro">Introduction</A></P>
-	<LI><P><A HREF="#bmWhatIs">What is Axis 2.0 ?</A></P>
-	<LI><P><A HREF="#bmWS">Web Services Using Axis2</A></P>
-	<LI><P><A HREF="#bmWSC">Web Service Clients Using Axis2</A></P>
-	<LI><P><A HREF="#bmModules">Modules</A></P>
-	<LI><P><A HREF="#bmOther">Other Samples</A></P>
-	<LI><P><A HREF="#bmTools">Tools</A></P>
-	<LI><P><A HREF="#bmAdvance">Advance Topics</A></P>
-</UL>
-<P><BR><BR>
-</P>
-<H2><A NAME="_Toc96698076"></A><A NAME="bmIntro"></A>Introduction 
-</H2>
-<P>Welcome to Axis 2.0, the next generation of Apache Axis !!! This
-User Guide will help you to understand what you will get from Axis
-2.0 and how to get started. We hope you will benefit from the power
-of Axis 2.0. 
-</P>
-<H2>Attention</H2>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in">This User Guide is written based
-	on the Axis2 binary distribution, the Binary distribution can be
-	created from the source distribution using the maven goal <CODE>$maven
-	dist-bin</CODE> 
-	</P>
-	<LI><P>Before we start, its highly recommended to read <A HREF="http://ws.apache.org/axis/java/user-guide.html">Axis
-	1.x User's guide </A>, if you are new to Axis. 
-	</P>
-</UL>
-<H2><A NAME="_Toc96698077"></A><A NAME="bmWhatIs"></A>What is Axis
-2.0 ? 
-</H2>
-<P>Axis 2.0 is the next generation of Apache Axis. In late August
-2004, during the Axis Summit held in Colombo, Sri Lanka, a new
-architecture was introduced to have a much more flexible, efficient
-and configurable Axis. Even though the architecture is new, some of
-the well established concepts from Axis 1.x, like handlers are
-preserved in Axis 2.0 also. Axis 2.0 comes with lots of new features,
-enhancements and new industry specification implementations. 
-</P>
-<P>After months of continued discussion and coding effort in this
-direction, Axis 2.0 now delivers the following key features: 
-</P>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Speed</STRONG>. Axis uses
-	its own object model and StAX (streaming) parsing to achieve
-	significantly greater speed than earlier versions of Apache AXIS. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Low memory foot print</STRONG>.
-	Axis 2.0 was designed ground-up keeping low memory foot print in
-	mind. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>AXIOM</STRONG>. Axis 2.0
-	comes with its own light-weight object model, AXIOM, for message
-	processing which is extensible, high performance and developer
-	convenient 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Hot Deployment.</STRONG>
-	One can now hot deploy web services and handlers. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Asynchronous Web Services</STRONG>.
-	Axis 2.0 now support asynchronous web services invocation and
-	asynchronous web services. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>MEP Support. </STRONG>Axis
-	2.0 now comes handy with support for Message Exchange Patterns. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Flexibility</STRONG>. The
-	Axis architecture gives the developer complete freedom to insert
-	extensions into the engine for custom header processing, system
-	management, or anything else you can imagine. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><STRONG>Stability</STRONG>. Axis
-	defines a set of published interfaces which change relatively slowly
-	compared to the rest of Axis. 
-	</P>
-	<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><P STYLE="margin-bottom: 0in"><STRONG>Transport framework</STRONG>.
-	We have a clean and simple abstraction for designing 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><P><STRONG>WSDL support.</STRONG> Axis 2.0 supports the <A HREF="http://www.w3.org/TR/wsdl">Web
-	Service Description Language </A>, version 1.1 and 2.0, which allows
-	you to easily build stubs to access remote services, and also to
-	automatically export machine-readable descriptions of your deployed
-	services from Axis. 
-	</P>
-</UL>
-<P>We hope you enjoy using Axis. Please note that this is an
-open-source effort - if you feel the code could use some new features
-or fixes, please get involved and lend a hand! The Axis developer
-community welcomes your participation . 
-</P>
-<P>Let us know what you think! 
-</P>
-<P>Please send feedback about the package to &quot;
-<A HREF="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org </A>&quot;
-and make sure to prefix the subject of the mail with [Axis2]. 
-</P>
-<H2><A NAME="_Toc96698078"></A>What's in this release? 
-</H2>
-<P>This release includes the following features:</P>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in">AXIOM, a SOAP specific streaming
-	XML infoset model for SOAP 1.1/1.2 Messages 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Support for One-Way Messaging and
-	Request Response Messaging 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Modules, mechanism to extend the
-	SOAP Processing Model 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Archives based deployment Model 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">WSDL Code Generation Tool for Stub
-	and skeltons 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">XML Beans based data binding
-	support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Support for WS-Addressing, both
-	the submission and final versions 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Client API 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">REST Web Service Support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">HTTP transport Support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">SMTP transport Support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">TCP transport Support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">MTOM/SWA attachments support 
-	</P>
-	<LI><P>SAAJ implementation 
-	</P>
-</UL>
-<P>The release include following tools</P>
-<OL>
-	<LI><P STYLE="margin-bottom: 0in">Admin Web App 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">WSDL2WS, eclipe Plugin/Command
-	line version 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Service Archive Wizard, eclipe
-	Plugin 
-	</P>
-	<LI><P>Module Archive Wizard, eclipe Plugin 
-	</P>
-</OL>
-<H2><A NAME="_Toc96698079"></A>What's still to do? 
-</H2>
-<P>Please see a list of what we think needs doing - and please
-consider helping out if you're interested &amp; able!</P>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in">JAX-RPC 1.1 and/or JAX-WS
-	compliance 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Pluggable Data binding support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">SOAP Encoding 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Binary serialization and
-	deserialization support 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Management Interface for Axis2 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Complete XML infoset support for
-	AXIOM 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Implementation of other
-	transports. e.g. JMS.. 
-	</P>
-	<LI><P>Web Service Policy Support 
-	</P>
-</UL>
-<H2><A NAME="_Toc96697863"></A><!-- Image goes here --><!--<h3><a name="_Toc96698087"></a>Running the Axis2 standalone server </h3>
-<p>Since a J2EE servlet container can be heavy in certain cases, a simple socket server is provided with Axis2. </p>
-Start scripts are inluded in the bin directory of the binary distribution.</p>
-<p>For windows</p>
-			 <p class="command">&gt;start.bat </p>
-<p>For Linux</p>
-			 <p class="command">$start.sh</p>			 			 
-<p>This will start the simple axis server in the default port (8080). To start the server in a non default port
-the server script can be used. The sever script however needs two parameters, the repository location and the port.</p>
-
-<p>For windows</p>
-			 <p class="command">&gt;server <i>repository directory</i> <i>port</i> </p>
-<p>For Linux</p>
-			 <p class="command">$server <i>repository directory</i> <i>port</i> </p>			 			 
- 
- <p><b>
- Note - the directory entered as the repository loacation needs to have a services directory inside. This is
- absolutely required and AXIS will not create it automatically in the case of the simple axis server. 
- </b></p> -->Samples</H2>
-<P>In this section of the user guide we will look at how to write and
-deploy Web Services and how to write Web Service Clients using Axis2.
-All the user guide samples are located at the <B><FONT COLOR="#000000">&quot;samples/userguide/src&quot;</FONT></B>
-directory of the binary distribution. So.. let's explore the samples.</P>
-<P>Note: Please note that the rest of this user guide assumes that
-the user has downloaded the binary distribution of Axis2. If you have
-already downloaded the source tree of Axis2 then please create the
-binary distribution by simply using the maven command <STRONG>maven
-dist-bin </STRONG>This will create the &quot;axis2-0.91-bin.zip&quot;
-and &quot;axis2-0.91-bin.tar&quot; in the &quot;target/dist&quot;
-directory. Extract the zip or the tar ball to any directory in your
-machine and for the explanations purposes we will name this directory
-as &quot;Axis2Home&quot;. 
-</P>
-<H2><A NAME="bmWS"></A>Web Services Using Axis2</H2>
-<P>Before starting, please check whether you have deployed the
-&quot;axis2.war&quot; in your servlet container and it is working
-properly. (See <A HREF="installationguide.html">Installation Guide</A>).
-User can select any of the&nbsp; following two ways of writing web
-services using Axis2. 
-</P>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in">Use Axis2's primary interfaces and
-	implement the business logic. 
-	</P>
-	<LI><P>Start from the WSDL -&gt;Code generate the Skeleton
-	-&gt;Implement the Business Logic. 
-	</P>
-</UL>
-<H3>Write My Service using Axis2</H3>
-<H4>MyService</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 &quot;Axis2Home/samples/userguide/src&quot; directory under
-&quot;userguide/example1&quot; package. As you can see, the two
-operations are very simple and need no explanations on what they are
-doing. So let's see how we can write the deployment descriptors for
-the service and deploy it.</P>
-<H4>How to write the Web Service?</H4>
-<P>Write a new Web Service with Axis2 involve four steps</P>
-<OL>
-	<LI><P STYLE="margin-bottom: 0in">Write the Implementation Class 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Write a services.xml file to
-	explain the Web Service 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">create a *.aar archive for the Web
-	Service 
-	</P>
-	<LI><P>Deploy the Web Service 
-	</P>
-</OL>
-<H4>Step1 :Write the Implementation Class</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>
-Step2 :Write the services.xml file</H4>
-<P>Axis2 uses &quot;services.xml&quot; to keep configurations for a
-Web Service. Each Web Service deployed in Axis2 needs a
-&quot;services.xml&quot; containing the configurations.
-&quot;services.xml&quot; for MyService will be as follows; we will
-see what each parameter means later.</P>
-<PRE>&lt;service name=&quot;MyService&quot;&gt;
-    &lt;description&gt;
-        This is a sample Web Service with two operations, echo and ping.
-    &lt;/description&gt;
-    &lt;parameter name=&quot;ServiceClass&quot; locked=&quot;xsd:false&quot;&gt;userguide.example1.MyService&lt;/parameter&gt;
-    &lt;operation name=&quot;echo&quot;&gt;
-        &lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
-    &lt;/operation&gt;
-     &lt;operation name=&quot;ping&quot;&gt;
-        &lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver&quot;/&gt;
-    &lt;/operation&gt;
- &lt;/service&gt;</PRE><P>
-As it can be seen, first line of the &quot;services.xml&quot; 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 two xml tags describe the operations that are
-available in this service with respective message receivers. For the
-&quot;echo&quot; operation we have used a <STRONG>RawXMLINOutMessageReceiver</STRONG>
-since it is an IN-OUT operation. For IN-ONLY operation, &quot;ping&quot;
-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 withing 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=&quot;Service1&quot;&gt;
-    &lt;!-- details for Service1 --&gt;
-  &lt;/service&gt;
-  &lt;service name=&quot;Service2&quot;&gt;
-    &lt;!-- details for Service2 --&gt;
-  &lt;/service&gt;
-  &lt;module ref=&quot;ModuleName&quot; /&gt;
-  &lt;parameter name=&quot;serviceGroupParam1&quot; locked=&quot;xsd:false&quot;&gt;value 1&lt;/parameter&gt;
-&lt;/serviceGroup&gt;</PRE><H4>
-Step3 :Create the Web Service Archive</H4>
-<P>Axis2 use &quot;.aar&quot; (Axis Archive) file as the deployment
-package for Web Services. So, for MyService we will use
-&quot;MyService.aar&quot; with the &quot;services.xml&quot; 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 &quot;MyService.aar&quot; user can first create a jar
-file containing all the files necessary for the service and then
-rename the &quot;jar&quot; to &quot;aar&quot; so that Axis2
-understands it as a service archive. This has already been created in
-the &quot;Axis2Home/samples/userguide&quot; directory, and let's use
-it.. 
-</P>
-<H4>Step4 :Depoly the Web Service</H4>
-<P>Deploying the service&nbsp; is just a matter of dropping the
-&quot;.aar&quot; in to &quot;services&quot; directory that can be
-found in the &quot;\webapps\axis2\WEB-INF&quot; of your servlet
-container and hence please copy the &quot;MyService.aar&quot; into
-the &quot;<B>services</B>&quot; directory. Once these steps are
-completed, please start the servlet container (if you have not
-already started) and check the link &quot;List Available services&quot;
-in the page http://localhost:8080/axis2/index.jsp and see whether the
-MyService is deployed properly. If everything is ok, you will see the
-following out put.. 
-</P>
-<P ALIGN=CENTER><IMG SRC="images/userguide/MyServiceDeployed.jpg" NAME="Graphic2" ALIGN=BOTTOM WIDTH=734 HEIGHT=766 BORDER=0>
-</P>
-<P>If you can see the above output then you have successfully
-deployed MyService on Axis2. Now let's see how we can write Web
-Service client to use this services. Axis2 provides an easy way to
-deploy a Web Services using, index.jsp. (See the installation guide
-for more information on this)</P>
-<H3>Axis2SampleDocLitPortType</H3>
-<P>Now 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>Generating Skeleton</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>
-<PRE STYLE="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -o ..\samples\src -p org.apache.axis2.userguide</PRE><P>
-This will generate the required classes in the <B>src</B> directory
-inside samples. This will also generate the schema classes in a
-directory named <B>schema</B> and please note that these are not
-source files and should be availed in the class path in order to
-compile the generated classes 
-</P>
-<H4>Implement the Business Logic</H4>
-<P>Locate the skeleton class that can be found under src/usreguide
-directory with the name &quot;Axis2SampleDocLitPortTypeSkeleton.java&quot;.
-This is the skeleton for our web service and we can easily fill the
-business logic now. The WSDL we have used has four operations as
-follows.</P>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in">echoVoid&nbsp;&nbsp; - Operation
-	that does not accept any input parameters&nbsp; and also provide no
-	out put parameters. Just perform some task 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">echoString&nbsp; - Operation that
-	echos a String value 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">echoStringArray - Operation that
-	accept string array as the input and echos them back 
-	</P>
-	<LI><P>echoStruct - Operation that accept a Struct as the input and
-	echos them back. 
-	</P>
-</UL>
-<H4>echoVoid&nbsp;&nbsp; 
-</H4>
-<P>Locate the following code segment&nbsp; in the
-&quot;Axis2SampleDocLitPortTypeSkeleton.java&quot;&nbsp; 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>
-echoString&nbsp; 
-</H4>
-<P>Locate the following code segment&nbsp; in the
-&quot;Axis2SampleDocLitPortTypeSkeleton.java&quot;&nbsp; and fill the
-business logic as shown below.</P>
-<PRE> public  org.soapinterop.xsd.EchoStringArrayReturnDocument 
-                echoStringArray(org.soapinterop.xsd.EchoStringArrayParamDocument param2){
-    //Todo 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 in the 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>echoStringArray 
-</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>
-echoStruct</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>
-services.xml</H4>
-<P>&nbsp;Axis2 uses &quot;services.xml&quot; to hold the
-configuretions 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 and it 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=&quot;Axis2SampleDocLitPortTypeSkeletonTest&quot;&gt;
-&lt;parameter locked=&quot;xsd:false&quot; name=&quot;ServiceClass&quot;&gt;userguide.Axis2SampleDocLitPortTypeSkeleton&lt;/parameter&gt;
-&lt;!--Mounting the method echoVoid--&gt;
-&lt;operation name=&quot;echoVoid&quot;&gt;
-&lt;messageReceiver class=&quot;userguide.Axis2SampleDocLitPortTypeMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;!--Mounting the method echoStringArray--&gt;
-&lt;operation name=&quot;echoStringArray&quot;&gt;
-&lt;messageReceiver class=&quot;userguide.Axis2SampleDocLitPortTypeMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;!--Mounting the method echoStruct--&gt;
-&lt;operation name=&quot;echoStruct&quot;&gt;
-&lt;messageReceiver class=&quot;userguide.Axis2SampleDocLitPortTypeMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;!--Mounting the method echoString--&gt;
-&lt;operation name=&quot;echoString&quot;&gt;
-&lt;messageReceiver class=&quot;userguide.Axis2SampleDocLitPortTypeMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;/service&gt;</PRE><P>
-As it can be seen, first line of the &quot;services.xml&quot; 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>Packaging</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 as well. These schema related classes are located in the
-<B>schema </B>directory of the generated code. Copy this to your
-class path and 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" NAME="Graphic3" 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 in the directory structure
-shown above) and type the following command in a command line.</P>
-<PRE STYLE="margin-bottom: 0.2in">jar -cf echo.aar .</PRE><P>
-Deploying the service&nbsp; is just a matter of dropping the &quot;.aar&quot;
-in to &quot;services&quot; directory that can be found in the
-&quot;\webapps\axis2\WEB-INF&quot; of your servlet container and
-hence please copy the &quot;echo.aar&quot; into the &quot;<B>services</B>&quot;
-directory. Once these steps are completed, please start the servlet
-container (if you have not already started) and check the link &quot;List
-Available services&quot; in the page
-http://localhost:8080/axis2/index.jsp and see whether the
-Axis2SampleDocLitPortType is deployed properly. If everything is ok,
-you will see the following out put.. 
-</P>
-<P ALIGN=CENTER><IMG SRC="images/userguide/ServiceDeployed.JPG" NAME="Graphic4" ALIGN=BOTTOM WIDTH=734 HEIGHT=764 BORDER=0>
-</P>
-<P>If you can see the above output then you have successfully
-deployed Axis2SampleDocLitPortType on Axis2. Now let's see how we can
-write Web Service client to use this services. Axis2 provides an easy
-way to deploy a Web Services using, index.jsp. (See the installation
-guide for more information on this)</P>
-<H2><A NAME="bmWSC"></A>Web Service Clients Using Axis2</H2>
-<P>Web services can be used to provide wide range of functionality to
-the users ranging from simple less time consuming&nbsp; operations
-such as &quot;getStockQuote&quot;&nbsp; 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 in most of the time we may end up with
-&quot;connection time outs&quot;. On the other hand, if there are
-simultaneous service invocations that&nbsp; we need to perform from a
-single client application, then the use of a &quot;blocking&quot;
-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 's try&lt;&lt; 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 gets
-	the control back only when the operation completes and the client
-	receives a response or a fault. This is the simplest way of invoking
-	Web Services and suites many business situations. 
-	</P>
-	<LI><P><B>Non-Blocking API </B>- A callback or polling based API and
-	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 with out blocking on the operation already invoked. 
-	</P>
-</UL>
-<P>Both these mechanism works in the API level and let's name the&nbsp;
-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 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 of these mechanisms
-fail to address the problem of long running transactions (the
-transport connection may times-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 can be called, <B>Transport Level Asynchrony</B>.</P>
-<P>By combining the two 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 BORDERCOLOR="#111111" CELLPADDING=0 CELLSPACING=0>
-	<TR>
-		<TD WIDTH=33% HEIGHT=19>
-			<P>API (Blocking/Non-Blocking)</P>
-		</TD>
-		<TD WIDTH=33%>
-			<P>&nbsp;Dual Transports (Yes/No)</P>
-		</TD>
-		<TD WIDTH=33%>
-			<P>Description</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>
-</TABLE>
-<P>Axis2 provides the user with all these possibilities to invoke Web
-Services. In addition Axis2 provides a data binding support making
-the life easy for developers writing Web Service client applications.
-In this user guide we will first see how we can write Web Service
-clients using the Axis2's primary APIs and later we will see how we
-can use generated stubs to simply write Web Service Clients.</P>
-<H3>Using Axis2's Primary APIs</H3>
-<H3>EchoBlockingClient</H3>
-<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. First let's see how we can
-write a client to invoke &quot;echo&quot; operation of &quot;MyService&quot;
-using the simplest good old blocking invocation. The client code that
-you need to write will be as follows.</P>
-<PRE>  try {
-            OMElement payload = ClientUtil.getEchoOMElement();
-            <FONT COLOR="#33cc00">Call call = new Call();</FONT>
-<FONT COLOR="#33cc00">            call.setTo(targetEPR);</FONT>
-<FONT COLOR="#33cc00">            call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);</FONT>
-
-<FONT COLOR="#33cc00">            OMElement result = (OMElement) call.invokeBlocking(&quot;echo&quot;, 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
-in-order to invoke a web service while the rest is used to create the
-OMElement that needs to be sent and to display the response
-OMElement. To test this client you can use the provided ant build
-file that can be found in the &quot;Axis2Home/samples&quot;
-directory. Run the &quot;testEchoBlockingClient&quot; target . if you
-can see the response OMElement printed in your command line&nbsp;
-then you have successfully tested the client as well. 
-</P>
-<H3>PingClient</H3>
-<P>In the Web Service &quot;MyService&quot; we had a IN-ONLY
-operation with the name &quot;ping&quot; (see Web Services Using
-Axis2). So let's write a client to invoke this operation as well. The
-client code will be as follows.</P>
-<PRE> try {
-       OMElement payload = ClientUtil.getPingOMElement();
-
-       MessageSender msgSender = new MessageSender();
-       msgSender.setTo(targetEPR);
-       msgSender.setSenderTransport(Constants.TRANSPORT_HTTP);
-       msgSender.send(&quot;ping&quot;, payload);
-
-     } catch (AxisFault axisFault) {
-            axisFault.printStackTrace();
-     }</PRE><P>
-Since we are accessing a IN-ONLY operation we can directly use the
-&quot;MessageSender&quot; to invoke this operation. As it can be seen
-in the above code , it is very straight forward to invoke this type
-of operation. MessageSender 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 &quot;testPingClient&quot; of the
-ant build file at &quot;Axis2Home/samples&quot;.</P>
-<P>Ok, 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>
-<H3>EchoNonBlockingClient</H3>
-<P>In the EchoBlockingClient once the &quot;call.invokeBlocking(&quot;echo&quot;,
-payload);&quot; 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
-&quot;Axis2Home/samples/userguide/src/userguide/clients&quot; with
-the name EchoNonBlockingClient. If we consider the changes that the
-user may have to do with respect to the &quot;EchoBlockingClient&quot;
-that we have already seen, it will be as follows.</P>
-<PRE STYLE="margin-bottom: 0.2in">call.invokeNonBlocking(&quot;echo&quot;, 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 reportError(Exception e);
-public boolean isComplete() {}</PRE><P>
-The user is expected to implement the &quot;onComplete &quot; and
-&quot;reportError &quot; 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 (Call). 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 &quot;testEchoNonBlockingClient&quot; target of the ant file
-found at the &quot;Axis2Home/samples&quot; directory. 
-</P>
-<H3>EchoNonBlockingDualClient 
-</H3>
-<P>The solution provided by the Non-Blocking API has one limitation
-when it comes to&nbsp; 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 connection (needs two way transports 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/">WS-Addressing</A>
-provides a neat solution to above using &lt;wsa:MessageID&gt; and
-&lt;wsa:RelatesTo&gt; headers. Axis2 provides support for addressing&nbsp;
-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, and it is the addressing like properties,
-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
-we can do it using an example. Following code fragment shows how to
-invoke the same &quot;echo&quot; operation, using Non-Blocking API
-with two transport connections<STRONG>. The ultimate asynchrony!!</STRONG></P>
-<PRE>  try {
-            OMElement payload = ClientUtil.getEchoOMElement();
-
-            Call call = new Call();
-            call.setTo(targetEPR);
-
-            //The boolean flag informs the axis2 engine to use two separate transport connection
-            //to retrieve the response.
-            <FONT COLOR="#33cc00">call.engageModule(new QName(Constants.MODULE_ADDRESSING));</FONT>
-            call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, <FONT COLOR="#00cc00">true</FONT>);
-
-            //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) {
-                        reportError(e);
-                    }
-                }
-
-                public void reportError(Exception e) {
-                    e.printStackTrace();
-                }
-            };
-
-            //Non-Blocking Invocation
-            call.invokeNonBlocking(&quot;echo&quot;, payload, callback);
-
-            //Wait till the callback receives the response.
-            while (!callback.isComplete()) {
-                Thread.sleep(1000);
-            }
-          <FONT COLOR="#33cc00">call.close();</FONT>
-
-        } catch (AxisFault axisFault) {
-            axisFault.printStackTrace();
-        } catch (Exception ex) {
-            ex.printStackTrace();
-        }</PRE><P>
-The three changes that we need do to the EchoNonBlockingClient are
-shown in the &quot;green&quot; color. Since our correlation mechanism
-is based on addressing we need to first &quot;<STRONG>engage</STRONG>&quot;
-the addressing module.<FONT COLOR="#0000ff"> <FONT COLOR="#000000"><B>&quot;call.engageModule(new
-QName(Constants.MODULE_ADDRESSING));&quot; </B>informs the Axis2
-engine to engage the addressing module at the client side. The
-boolean flag (value true) in the &quot;<BR><B>call.setTransportInfo(...)</B>&quot;
-method informs the Axis2 engine to use separate transport connections
-for request and response. Finally &quot;<B>call.close()</B>&quot;
-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 need one more step to perform.
-As mentioned earlier Axis2 uses addressing based correlation
-mechanism and hence we need to &quot;engage&quot; addressing module
-in the server side as well. According to the Axis2 architecture
-addressing module is deployed in the &quot;<STRONG>pre-dispatch</STRONG>&quot;
-phase (See <A HREF="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture
-Guide</A> for more details about phases)&nbsp; and hence &quot;engaging&quot;
-means simply adding module reference in the &quot;axis2.xml&quot;
-(NOT the &quot;services.xml&quot;). Please add the following line to
-the &quot;axis2.xml&quot; that you can find in the
-&quot;/webapps/axis2/WEB-INF&quot; directory in the servlet
-container. 
-</P>
-<PRE STYLE="margin-bottom: 0.2in"> &lt;module ref=&quot;addressing&quot;/&gt;</PRE><P>
-Note: Please note that<FONT COLOR="#000000"> once you change the
-&quot;axis2.xml&quot; you need to restart the servlet container.</FONT></P>
-<P>This will enable the addressing in the server side and now you can
-test the &quot;TestEchoNonBlockingDualClient&quot; using the
-&quot;testEchoNonBlockingDualClient&quot; target of the ant file
-found at &quot;Axis2Home/samples&quot; directory. If you can see the
-response OMElement printed in the client side, that means you have
-successfully tested the Non Blocking API with two transport channels
-at the client side.</P>
-<H3>EchoBlockingDualClient 
-</H3>
-<P>This is again a two 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
-&quot;Axis2Home/samples/userguide/src/userguide/clients/&quot;
-directory and the explanation is similar to the
-EchoNonBlockingDualClient, 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
-&quot;echoBlockingDualClient&quot; target of the ant build file found
-in the &quot;Axis2Home/samples&quot; directory.</P>
-<P>See <A HREF="#configTransport">Configuring Transports</A> for use
-different transports.</P>
-<H3>With Data Binding 
-</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 see how we can generate the stubs
-for the WSDL we have used earlier to generate the skeleton for the
-&quot;Axis2SampleDocLitPortType&quot;. 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
-&quot;Axis2SampleDocLitPortTypeStub.java&quot; 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>
-<H3>Client for echoVoid Operation</H3>
-<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 sa the AXIS_HOME
-   Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null, 
-                                &quot;http://localhost:8080/axis2/services/Axis2SampleDocLitPortType&quot;);
-   stub.echoVoid();
-
-} catch (Exception e) {
-    e.printStackTrace();
-}</PRE><H3>
-Client for echoString Operation</H3>
-<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 given in the 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 sa the AXIS_HOME 
-     Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
-                                &quot;http://localhost:8080/axis2/services/Axis2SampleDocLitPortType&quot;);
-     //Create the request document to be sent.
-     EchoStringParamDocument  reqDoc= EchoStringParamDocument.Factory.newInstance();
-     reqDoc.setEchoStringParam(&quot;Axis2 Echo&quot;);
-     //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 shows client side code for
-echoStringArray operation and echoStruct operation respectively.</P>
-<H3>Client for echoStringArray Operation</H3>
-<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 sa the AXIS_HOME
-     Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
-                                &quot;http://localhost:8080/axis2/services/Axis2SampleDocLitPortType&quot;);
-
-     //Create the request document to be sent.
-     EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
-     ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
-
-     paramArray.addString(&quot;Axis2&quot;);
-     paramArray.addString(&quot;Echo&quot;);
-
-      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><H3>
-Client for echoStruct Operation</H3>
-<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 sa the AXIS_HOME
-    Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null, 
-                                &quot;http://localhost:8080/axis2/services/Axis2SampleDocLitPortType&quot;);
-    //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(&quot;High&quot;);
-
-    reqDoc.setEchoStructParam(reqStruct);
-
-    //Service invocation
-    EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
-    SOAPStruct resStruct = resDoc.getEchoStructReturn();
-
-    System.out.println(&quot;floot Value :&quot; + resStruct.getVarFloat());
-    System.out.println(&quot;int Value :&quot; + resStruct.getVarInt());
-    System.out.println(&quot;String Value :&quot; + resStruct.getVarString());
-
-} catch (Exception e) {
-    e.printStackTrace();
-}</PRE><H2>
-<A NAME="bmModules"></A>Modules</H2>
-<P>Axis2 provides an extended support for modules (See <A HREF="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture
-Guide</A> for more details about modules in axis2). Let's see how we
-can create a custom module and deploy it to the MyService that we
-have created earlier. Following steps shows the actions that needs 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><P STYLE="margin-bottom: 0in">Create the Handlers 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Create the moduel.xml 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Modify the &quot;axis2.xml&quot;
-	(if you need custom phases) 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Modify the &quot;services.xml&quot;
-	to engage modules at the deployment time. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Package in a &quot;.mar&quot;
-	(Module Archive) 
-	</P>
-	<LI><P>Deploy the module in Axis2 
-	</P>
-</OL>
-<H3>MyService with a Logging Module 
-</H3>
-<P>Let's write a simple logging module for our sample. This module
-contains one handler that just logs the message that is passed though
-it. Axis2 uses .&quot;mar&quot; (Module Archive) to deploy modules in
-Axis2. Following diagram shows the file structure inside that needs
-to be there in the &quot;.mar&quot; archive. Let's create all these
-and see how it works.</P>
-<P><IMG SRC="images/userguide/ModuleView.jpg" NAME="Graphic5" ALIGN=BOTTOM WIDTH=185 HEIGHT=120 BORDER=0></P>
-<H4>Step1 : LoggingModule Class</H4>
-<P>LoggingModule is the implementation class of the Axis2 module.
-Axis2 modules should implement the &quot;org.apache.axis2.modules.Module&quot;
-interface with the following methods.</P>
-<PRE>public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
-public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing</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 and 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>Step2 : LogHandler</H4>
-<P>A module in axis2 can contain, one or more handlers that perform
-various SOAP header processing at different phases. (See<A HREF="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">
-Architecture Guide</A> for more information about phases). For the
-logging module we will write a handle with the following methods.
-&quot;public void invoke(MessageContext ctx);&quot; is the method
-that is called by the Axis2 engine when the control is passed to the
-handler. &quot;public void revoke(MessageContext ctx);&quot; 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 revoke(MessageContext msgContext) {
-        log.info(msgContext.getEnvelope().toString());
-    }
-
-    public void setName(QName name) {
-        this.name = name;
-    }
-}</PRE><H4>
-Step3 : module.xml</H4>
-<P>&quot;module.xml&quot; contains the deployment configurations for
-a particular module. It contains details such as Implementation class
-of the module (in this example it is the &quot;LoggingModule&quot;
-class and the various handlers that will run in different phases.
-&quot;module.xml&quot; for the logging module will be as follows.</P>
-<PRE>&lt;module name=&quot;logging&quot; class=&quot;userguide.loggingmodule.LoggingModule &quot;&gt;
-&lt;inflow&gt;
-        &lt;handler name=&quot;InFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
-        &lt;order phase=&quot;loggingPhase&quot; /&gt;
-        &lt;/handler&gt;
-&lt;/inflow&gt;
-
-&lt;outflow&gt;
-        &lt;handler name=&quot;OutFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
-        &lt;order phase=&quot;loggingPhase&quot;/&gt;
-        &lt;/handler&gt;
-&lt;/outflow&gt;
-
-&lt;Outfaultflow&gt;
-        &lt;handler name=&quot;FaultOutFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
-        &lt;order phase=&quot;loggingPhase&quot;/&gt;
-        &lt;/handler&gt;
-&lt;/Outfaultflow&gt;
-
-&lt;INfaultflow&gt;
-        &lt;handler name=&quot;FaultInFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
-        &lt;order phase=&quot;loggingPhase&quot;/&gt;
-        &lt;/handler&gt;
-&lt;/INfaultflow&gt;
-&lt;/module&gt;</PRE><P>
-As it can be seen there are four phases defined in this &quot;module.xml&quot;</P>
-<OL>
-	<LI><P STYLE="margin-bottom: 0in">inflow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-	- Represents the handler chain that will run when a message is
-	coming in. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">outflow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-	- Represents the handler chain that will run when the message is
-	going out. 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in">Outfaultflow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-	- Represents the handler chain that will run when there is a fault
-	and the fault is going out 
-	</P>
-	<LI><P>INfaultflow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - Represents
-	the handler chain that will run when there is a fault and the fault
-	is coming in 
-	</P>
-</OL>
-<P>Following set of tags describe the name of the handler, handler
-class and the phase in which this handler going to
-run.&quot;InFlowLogHandler&quot; is the name given for the particular
-instance of this handler. The property, class 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. &quot;&lt;order
-phase=&quot;loggingPhase&quot; /&gt;&quot; describes the phase in
-which this handler runs. 
-</P>
-<PRE>&lt;handler name=&quot;InFlowLogHandler&quot; class=&quot;userguide.loggingmodule.LogHandler&quot;&gt;
-&lt;order phase=&quot;loggingPhase&quot; /&gt;
-&lt;/handler&gt;</PRE><H4>
-Step 4: Modify the &quot;axis2.xml&quot;</H4>
-<P>In this handler the phase &quot;loggingPhase&quot; is defined by
-the module writer. It is not a pre-defined handler phase and hence
-the module writer should introduce it to the &quot;axis2.xml&quot;
-(NOT the services.xml) so that Axis2 engine knows where to place the
-handler in different &quot;flows&quot; (<BR>InFlow, OutFlow, etc...).
-Following xml lines shows the respective changes to the &quot;axis2.xml&quot;
-in order for us to deploy this logging module in Axis2 engine. This
-is an extract of the phase section of the &quot;axis2.xml&quot;.</P>
-<PRE>&lt;!-- ================================================= --&gt;
-&lt;!-- Phases --&gt;
-&lt;!-- ================================================= --&gt;
-&lt;phaseOrder type=&quot;inflow&quot;&gt;
-&lt;!-- System pre defined phases --&gt;
-        &lt;phase name=&quot;TransportIn&quot;/&gt;
-        &lt;phase name=&quot;PreDispatch&quot;/&gt;
-        &lt;phase name=&quot;Dispatch&quot;/&gt;
-        &lt;phase name=&quot;PostDispatch&quot;/&gt;
-&lt;!-- System pre defined phases --&gt;
-
-&lt;!-- After Postdispatch phase module author or or service author can add any phase he want --&gt;
-&lt;phase name=&quot;<FONT COLOR="#33cc00">loggingPhase</FONT>&quot;/&gt;
-&lt;/phaseOrder&gt;
-
-&lt;phaseOrder type=&quot;outflow&quot;&gt;
-&lt;!-- user can add his own phases to this area --&gt;
-&lt;phase name=&quot;<FONT COLOR="#33cc00">loggingPhase</FONT>&quot;/&gt;
-&lt;/phaseOrder&gt;
-
-&lt;phaseOrder type=&quot;INfaultflow&quot;&gt;
-&lt;!-- user can add his own phases to this area --&gt;
-&lt;phase name=&quot;<FONT COLOR="#33cc00">loggingPhase</FONT>&quot;/&gt;
-&lt;/phaseOrder&gt;
-
-&lt;phaseOrder type=&quot;Outfaultflow&quot;&gt;
-&lt;!-- user can add his own phases to this area --&gt;
-&lt;phase name=&quot;<FONT COLOR="#33cc00">loggingPhase</FONT>&quot;/&gt;
-&lt;/phaseOrder&gt;</PRE><P>
-Shown in green, the custom phase &quot;loggingPhase&quot; is placed
-in all the flows, and hence that phase will be called in all the
-message flows in the engine. Since our module is associated with this
-phase, the LogHandler is now have a phase for it to get executed. 
-</P>
-<H4>Step5 : Modify the &quot;services.xml&quot;</H4>
-<P>Up to this point we have created the required classes and the
-configuration descriptions for the logging module and by changing the
-&quot;axis2.xml&quot; we have created the required phases for the
-logging module. Now the next step is to &quot;<B>engage</B>&quot;
-(use) this module in one of our services. For this, let's use the
-same Web Service that we have used throughout the user guide, the
-MyService. However, since we need to modify the &quot;services.xml&quot;
-of the MyService in order for us engage this module, we use a
-separate Web Service, but with the similar operations. The code for
-this service can be found in the
-&quot;Axis2Home/samples/userguide/src/userguide/example2&quot;
-directory. The simple changes that we have done to he &quot;services.xml'
-are shown in the green color in the following lines of xml.</P>
-<PRE>&lt;service name=&quot;<FONT COLOR="#33cc00">MyServiceWithModule</FONT>&quot;&gt;
-&lt;description&gt;
-This is a sample Web Service with a logging module engaged.
-&lt;/description&gt;
-<FONT COLOR="#33cc00">&lt;module ref=&quot;logging&quot;/&gt;</FONT>
-&lt;parameter name=&quot;ServiceClass&quot; locked=&quot;xsd:false&quot;&gt;userguide.example2.MyService&lt;/parameter&gt;
-&lt;operation name=&quot;echo&quot;&gt;
-&lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;operation name=&quot;ping&quot;&gt;
-&lt;messageReceiver class=&quot;org.apache.axis2.receivers.RawXMLINOutMessageReceiver&quot;/&gt;
-&lt;/operation&gt;
-&lt;/service&gt;</PRE><P>
-In this example we have changed the service name (the implementatoin
-class is very similar to what we have used ealier although it is in a
-different package). In addition we have added the line <B>&quot;&lt;module
-ref=&quot;logging&quot;/&gt;&quot;</B> to the &quot;services.xml&quot;.
-This informs the Axis2 engine that the module &quot;logging&quot;
-should be engaged for this service. The handler in side the module
-will be executed in their respective phases as described by the
-&quot;module.xml&quot;.</P>
-<P><B>Step6 : Packaging</B></P>
-<P>Before deploying the module we need to create the &quot;.mar&quot;
-file for this module. This can be done, using the &quot;jar&quot;
-command and then renaming the created jar file, or you can find the
-&quot;Logging.mar&quot; that is already created for you in the
-&quot;Axis2Home/samples/userguide&quot; directory.</P>
-<H4>Step7 : Deploy the Module in Axis2</H4>
-<P>Deploying a module in Axis2 require the user to create a directory
-with the name &quot;modules&quot; in the &quot;webapps/axis2/WEB-INF&quot;
-directory of their servlet container and then copying the &quot;.mar&quot;
-file to that directory. So let's first create the &quot;modules&quot;
-directory and drop the &quot;LoggingModule.mar&quot; in to this
-directory.</P>
-<P>Although the required changes to the &quot;services.xml&quot; is
-very little, we have created a separate service archive
-(MyServiceWithModule.aar) for users to just deploy and see. Please
-deploy this service using the same steps that you use to deploy
-&quot;MyService&quot; and copy the &quot;LoggingModule.mar&quot; file
-to the &quot;modules&quot; directory. Then by using the
-&quot;TestWebServiceWithModuleClient.bat&quot; and
-&quot;TestWebServiceWithModuleClient.sh&quot; in the
-&quot;Axis2Home/samples/userguide/src/userguide/clients/bin&quot;
-directory. 
-</P>
-<P>Note: To see the logs, the user needs to modify the
-&quot;log4j.properties&quot; to log INFO as well. The property file
-is located in &quot;webapps\axis2\WEB-INF\classes&quot; of your
-servlet container. Change the line &quot;log4j.rootCategory= ERROR,
-LOGFILE&quot; to &quot;log4j.rootCategory=INFO, ERROR, LOGFILE&quot;.</P>
-<H2>&nbsp;</H2>
-<H2><A NAME="bmOther"></A>Other Samples</H2>
-<P>To show the power and usage of Axis2, three standard samples are
-shipped with the 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><P STYLE="margin-bottom: 0in">Google spell checker sample<!--<li>Google search sample</li> -->
-		</P>
-	<LI><P>Amazon queuing sample 
-	</P>
-</UL>
-<P>Following is a simple introduction to each of the samples. Each
-sample contains it's own help document that says about&nbsp; the
-usage and the advanced operations of that particular sample.</P>
-<H4>Google spell checker sample</H4>
-<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
-samples\googleSpellcheck folder and can be easily started using
-either the batch file or the shell script.</P>
-<H4>Google search sample</H4>
-<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 the samples\googleSearch
-folder and can be easily started using either the batch file or the
-shell script.</P>
-<H4>Amazon queuing service</H4>
-<P>Amazon queuing service sample shows how to use the Amazon queuing
-service. it has two user interfaces , one to enqueue and the other
-dequeue. This sample is included in the samples\amazonQS and also
-contains the batch/shell scripts to run.</P>
-<H3>Where are these samples ?</H3>
-<P>The most obvious place to look for the samples are the binary
-distribution. all these samples are included in the samples directory
-in the binary distribution. The shell scripts and the batch files are
-in fact written to use the binary distributions root directory as the
-home to find the libraries.</P>
-<P>The other way is to build the samples from source. Moving to the
-modules/samples and running maven will create the samples in the
-target/samples directory. However if the samples need to be started
-using the shell scripts (or the batch files) then the AXIS_HOME
-environment need to be set.( the &quot;guessed&quot; AXIS_HOME would
-not be correct in this case)</P>
-<H2><A NAME="bmTools"></A>Tools</H2>
-<P>Axis2 is shipped with two standard tools. Both the tools are
-Eclipse plug-ins, the Codegen tool even has the accompanying Ant task
-and the command line tool. 
-</P>
-<P>Documentation for the code generator tool is available for the
-<A HREF="CodegenToolReference.html">Codegen wizard</A> and the
-<A HREF="ServiceArchiveToolReference.html">Service Archiver</A>.</P>
-<P>&nbsp;</P>
-<H2><A NAME="bmAdvance"></A>Advanced Topics</H2>
-<UL>
-	<LI><P STYLE="margin-bottom: 0in"><A HREF="rest-ws.html">RESTful Web
-	Services</A> 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><A HREF="tcp-transport.html">TCP
-	transport</A> 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><A HREF="mail-transport.html">Mail
-	Transport</A> 
-	</P>
-	<LI><P STYLE="margin-bottom: 0in"><A HREF="http-transport.html">HTTP
-	Transports</A> 
-	</P>
-	<LI><P><A HREF="mtom-guide.html">MTOM with Axis2</A> 
-	</P>
-</UL>
-</BODY>
-</HTML>
\ No newline at end of file
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html; charset=windows-1252">
+  <title>Axis 2.0 User's Guide</title>
+  <meta name="CREATED" content="20050918;20224042">
+  <meta name="CHANGEDBY" content="Chamikara Jayalath">
+  <meta name="CHANGED" content="20050919;1140420">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h1 align="center"><a name="_Toc96697849"></a>Axis 2.0 User's Guide</h1>
+
+<h2>Contents</h2>
+<ul>
+  <li><p><a href="#bmIntro">Introduction</a></p>
+  </li>
+  <li><p><a href="#bmWhatIs">What is Axis 2.0 ?</a></p>
+  </li>
+  <li><p><a href="#bmWS">Web Services Using Axis2</a></p>
+  </li>
+  <li><p><a href="#bmWSC">Web Service Clients Using Axis2</a></p>
+  </li>
+  <li><p><a href="#bmModules">Modules</a></p>
+  </li>
+  <li><p><a href="#bmOther">Other Samples</a></p>
+  </li>
+  <li><p><a href="#bmTools">Tools</a></p>
+  </li>
+  <li><p><a href="#bmAdvance">Advance Topics</a></p>
+  </li>
+</ul>
+
+<p><br>
+<br>
+</p>
+
+<h2><a name="_Toc96698076"></a><a name="bmIntro"></a>Introduction</h2>
+
+<p>Welcome to Axis 2.0, the next generation of Apache Axis !!! This User
+Guide will help you to understand what you will get from Axis 2.0 and how to
+get started. We hope you will benefit from the power of Axis 2.0.</p>
+
+<h2>Attention</h2>
+<ul>
+  <li><p style="margin-bottom: 0in">This User Guide is written based on the
+    Axis2 binary distribution, the Binary distribution can be created from
+    the source distribution using the maven goal <code>$maven
+    dist-bin</code></p>
+  </li>
+  <li><p>Before we start, its highly recommended to read <a
+    href="http://ws.apache.org/axis/java/user-guide.html">Axis 1.x User's
+    guide </a>, if you are new to Axis.</p>
+  </li>
+</ul>
+
+<h2><a name="_Toc96698077"></a><a name="bmWhatIs"></a>What is Axis 2.0 ?</h2>
+
+<p>Axis 2.0 is the next generation of Apache Axis. In late August 2004,
+during the Axis Summit held in Colombo, Sri Lanka, a new architecture was
+introduced to have a much more flexible, efficient and configurable Axis.
+Even though the architecture is new, some of the well established concepts
+from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes
+with lots of new features, enhancements and new industry specification
+implementations.</p>
+
+<p>After months of continued discussion and coding effort in this direction,
+Axis 2.0 now delivers the following key features:</p>
+<ul>
+  <li><p style="margin-bottom: 0in"><strong>Speed</strong>. Axis uses its own
+    object model and StAX (streaming) 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>.
+    Axis 2.0 was designed ground-up keeping low memory foot print in mind.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>AXIOM</strong>. Axis 2.0 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>Hot Deployment.</strong> One can
+    now hot deploy web services and handlers.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Asynchronous Web
+    Services</strong>. Axis 2.0 now support asynchronous web services
+    invocation and asynchronous web services.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>MEP Support. </strong>Axis 2.0
+    now comes handy with support for Message Exchange Patterns.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Flexibility</strong>. The Axis
+    architecture gives the developer complete freedom to insert extensions
+    into the engine for custom header processing, system management, or
+    anything else you can imagine.</p>
+  </li>
+  <li><p style="margin-bottom: 0in"><strong>Stability</strong>. Axis 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 designing 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><strong>WSDL support.</strong> Axis 2.0 supports the <a
+    href="http://www.w3.org/TR/wsdl">Web Service Description Language </a>,
+    version 1.1 and 2.0, which allows you to easily build stubs to access
+    remote services, and also to automatically export machine-readable
+    descriptions of your deployed services from Axis.</p>
+  </li>
+</ul>
+
+<p>We hope you enjoy using Axis. Please note that this is an open-source
+effort - if you feel the code could use some new features or fixes, please
+get involved and lend a hand! The Axis developer community welcomes your
+participation .</p>
+
+<p>Let us know what you think!</p>
+
+<p>Please send feedback about the package to " <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org </a>" and make
+sure to prefix the subject of the mail with [Axis2].</p>
+
+<h2><a name="_Toc96698078"></a>What's in this release?</h2>
+
+<p>This release includes the following features:</p>
+<ul>
+  <li><p style="margin-bottom: 0in">AXIOM, a SOAP specific streaming XML
+    infoset model for SOAP 1.1/1.2 Messages</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Support for One-Way Messaging and Request
+    Response Messaging</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Modules, mechanism to extend the SOAP
+    Processing Model</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Archives based deployment Model</p>
+  </li>
+  <li><p style="margin-bottom: 0in">WSDL Code Generation Tool for Stub and
+    skeletons</p>
+  </li>
+  <li><p style="margin-bottom: 0in">XML Beans based data binding support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Support for WS-Addressing, both the
+    submission and final versions</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Client API</p>
+  </li>
+  <li><p style="margin-bottom: 0in">REST Web Service Support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">HTTP transport Support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">SMTP transport Support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">TCP transport Support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">MTOM/SWA attachments support</p>
+  </li>
+  <li><p>SAAJ implementation</p>
+  </li>
+</ul>
+
+<p>The release include following tools</p>
+<ol>
+  <li><p style="margin-bottom: 0in">Admin Web App</p>
+  </li>
+  <li><p style="margin-bottom: 0in">WSDL2WS, eclipse Plugin/Command line
+    version</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Service Archive Wizard, eclipse Plugin</p>
+  </li>
+  <li><p>Module Archive Wizard, eclipse Plugin</p>
+  </li>
+</ol>
+
+<h2><a name="_Toc96698079"></a>What's still to do?</h2>
+
+<p>Please see a list of what we think needs doing - and please consider
+helping out if you're interested &amp; able!</p>
+<ul>
+  <li><p style="margin-bottom: 0in">JAX-RPC 1.1 and/or JAX-WS compliance</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Pluggable Data binding support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">SOAP Encoding</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Binary serialization and de-serialization
+    support</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Management Interface for Axis2</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Complete XML infoset support for AXIOM</p>
+  </li>
+  <li><p style="margin-bottom: 0in">Implementation of other transports. e.g.
+    JMS..</p>
+  </li>
+  <li><p>Web Service Policy Support</p>
+  </li>
+</ul>
+
+<h2><a name="_Toc96697863"></a><!-- Image goes here -->
+<!--<h3><a name="_Toc96698087"></a>Running the Axis2 standalone server </h3>
+<p>Since a J2EE servlet container can be heavy in certain cases, a simple socket server is provided with Axis2. </p>
+Start scripts are inluded in the bin directory of the binary distribution.</p>
+<p>For windows</p>
+<p class="command">&gt;start.bat </p>
+<p>For Linux</p>
+<p class="command">$start.sh</p>        
+<p>This will start the simple axis server in the default port (8080). To start the server in a non default port
+the server script can be used. The sever script however needs two parameters, the repository location and the port.</p>
+
+<p>For windows</p>
+<p class="command">&gt;server <i>repository directory</i> <i>port</i> </p>
+<p>For Linux</p>
+<p class="command">$server <i>repository directory</i> <i>port</i> </p>        
+
+<p><b>
+Note - the directory entered as the repository location needs to have a services directory inside. This is
+absolutely required and AXIS will not create it automatically in the case of the simple axis server. 
+</b></p> -->
+Samples</h2>
+
+<p>In this section of the user guide we will look at how to write and deploy
+Web Services and how to write Web Service Clients using Axis2. All the user
+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>
+
+<p>Note: Please note that the rest of this user guide assumes that the user
+has downloaded the binary distribution of Axis2. If you have already
+downloaded the source tree of Axis2 then please create the binary
+distribution by simply using the maven command <strong>maven dist-bin
+</strong>This will create the "axis2-0.91-bin.zip" and "axis2-0.91-bin.tar"
+in the "target/dist" directory. Extract the zip or the tar ball to any
+directory in your machine and for the explanations purposes we will name this
+directory as "Axis2Home".</p>
+
+<h2><a name="bmWS"></a>Web Services Using Axis2</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">Installation Guide</a>). User can select any of
+the  following two ways of writing web services using Axis2. </p>
+<ul>
+  <li><p style="margin-bottom: 0in">Use Axis2's primary interfaces and
+    implement the business logic.</p>
+  </li>
+  <li><p>Start from the WSDL -&gt;Code generate the Skeleton -&gt;Implement
+    the Business Logic.</p>
+  </li>
+</ul>
+
+<h3>Write My Service using Axis2</h3>
+
+<h4>MyService</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 are doing. So let's see how we can write the
+deployment descriptors for the service and deploy it.</p>
+
+<h4>How to write the Web Service?</h4>
+
+<p>Write a new Web Service with Axis2 involve four steps</p>
+<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 for the Web
+    Service</p>
+  </li>
+  <li><p>Deploy the Web Service</p>
+  </li>
+</ol>
+
+<h4>Step1 :Write the Implementation Class</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>Step2 :Write the services.xml file</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; we will see
+what each parameter means later.</p>
+<pre>&lt;service name="MyService"&gt;
+    &lt;description&gt;
+        This is a sample Web Service with two operations, echo and ping.
+    &lt;/description&gt;
+    &lt;parameter name="ServiceClass" locked="xsd: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>As it can be seen, 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 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="xsd:false"&gt;value 1&lt;/parameter&gt;
+&lt;/serviceGroup&gt;</pre>
+
+<h4>Step3 :Create the Web Service Archive</h4>
+
+<p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web
+Services. So, 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, and let's use it..</p>
+
+<h4>Step4 :Depoly the Web Service</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 and hence please copy the "MyService.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 "List
+Available services" in the page http://localhost:8080/axis2/index.jsp and see
+whether the MyService is deployed properly. If everything is ok, you will see
+the following out put..</p>
+
+<p align="center"><img src="images/userguide/MyServiceDeployed.jpg"
+name="Graphic2" align="bottom" width="734" height="766" border="0"></p>
+
+<p>If you can see the above output then you have successfully deployed
+MyService on Axis2. Now let's see how we can write Web Service client to use
+this services. Axis2 provides an easy way to deploy a Web Services using,
+index.jsp. (See the installation guide for more information on this)</p>
+
+<h3>Axis2SampleDocLitPortType</h3>
+
+<p>Now 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>Generating Skeleton</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>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -o ..\samples\src -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required classes in the <b>src</b> directory inside
+samples. This will also generate the schema classes in a directory named
+<b>schema</b> and please note that these are not source files and should be
+availed in the class path in order to compile the generated classes</p>
+
+<h4>Implement the Business Logic</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 easily fill the business logic now. The WSDL
+we have used has four operations as follows.</p>
+<ul>
+  <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>
+  <li><p style="margin-bottom: 0in">echoString  - Operation that echos a
+    String value </p>
+  </li>
+  <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
+    string array as the input and echos them back</p>
+  </li>
+  <li><p>echoStruct - Operation that accept a Struct as the input and echos
+    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>echoString  </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){
+    //Todo 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 in the 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>echoStringArray</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>echoStruct</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>services.xml</h4>
+
+<p> Axis2 uses "services.xml" to hold the configuretions 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 and it 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 echoVoid--&gt;
+&lt;operation name="echoVoid"&gt;
+&lt;messageReceiver class="userguide.Axis2SampleDocLitPortTypeMessageReceiver"/&gt;
+&lt;/operation&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>As it can be seen, 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>Packaging</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 as well.
+These schema related classes are located in the <b>schema </b>directory of
+the generated code. Copy this to your class path and compile the skeleton and

[... 820 lines stripped ...]


Mime
View raw message