Google Git
Sign in
apache / axis-axis2-java-core / c65cdde289dc947f00217c20f5f5498b41b0b94c / . / xdocs / userguide.html
blob: b9f62c22f043b8a5b85b98d5c89eca396b87e9fe [file] [log] [blame]
<!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="#Introduction">Introduction</a></p>
</li>
<li><p><a href="#What_is_Axis_2_0__">What is Axis 2.0 ?</a></p>
</li>
<li><p><a href="#Web_Services_Using_Axis2">Web Services Using Axis2</a></p>
</li>
<li><p><a href="#Web_Service_Clients_Using_Axis2">Web Service Clients Using Axis2</a></p>
</li>
<li><p><a href="#Modules">Modules</a></p>
</li>
<li><p><a href="#Other_Samples">Other Samples</a></p>
</li>
<li><p><a href="#Tools">Tools</a></p>
</li>
<li><p><a href="#Advanced_Topics">Advanced Topics</a></p>
</li>
</ul>
<p><br>
<br>
</p>
<h2><a name="_Toc96698076"></a><a name="Introduction"></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="What_is_Axis_2_0__"></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="Web_Services_Using_Axis2"></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="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="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>
<p>Windows users can use the following command in the console </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>Linux users should switch the file seperator</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 three 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 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
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 Axis2SampleDocLitPortType.aar .</pre>
<p>Deploying the service  is just a matter of dropping the ".aar" in to
"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
your servlet container and hence please copy the "echo.aar" into the
"<b>services</b>" directory. Once these steps are completed, please start the
servlet container (if you have not already started) and check the link "List
Available services" 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="Web_Service_Clients_Using_Axis2"></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  operations such as
"getStockQuote"  to time consuming business services. When we utilize (invoke
using client applications) these Web Service we cannot use some simple
generic invocation paradigm that suites all the timing complexities involved
in the service operations. For example, if we use a single transport channel
(such as HTTP) to invoke a Web Service with and IN-OUT operation, that take
long time to complete, then in most of the time we may end up with
"connection time outs". On the other hand, if there are simultaneous service
invocations that  we need to perform from a single client application, then
the use of a "blocking" client API will degrade the performance of the client
application. Similarly there are various other consequences such as One-Way
transports that come in to play when we need '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>
<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>
</li>
</ul>
<p>Both these mechanism works in the API level and 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 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" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td width="33%" height="19"><p>API (Blocking/Non-Blocking)</p>
</td>
<td width="33%"><p> 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>
</tbody>
</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
"echo" operation of "MyService" 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("echo", 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 "Axis2Home/samples" directory. Run the "testEchoBlockingClient" target .
if you can see the response OMElement printed in your command line  then you
have successfully tested the client as well. </p>
<h3>PingClient</h3>
<p>In the Web Service "MyService" we had a IN-ONLY operation with the name
"ping" (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("ping", payload);
} catch (AxisFault axisFault) {
axisFault.printStackTrace();
}</pre>
<p>Since we are accessing a IN-ONLY operation we can directly use the
"MessageSender" 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
"testPingClient" of the ant build file at "Axis2Home/samples".</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 "call.invokeBlocking("echo", payload);"
is called, the client is blocked till the operation is completed. This
behavior is not desirable when there are many Web Service invocations to be
done in a single client application. A solution, would be to use a
Non-Blocking API to invoke web services. Axis2 provides a callback based
non-blocking API for users.</p>
<p>A sample client for this can be found under
"Axis2Home/samples/userguide/src/userguide/clients" with the name
EchoNonBlockingClient. If we consider the changes that the user may have to
do with respect to the "EchoBlockingClient" that we have already seen, it
will be as follows.</p>
<pre style="margin-bottom: 0.2in">call.invokeNonBlocking("echo", 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 "onComplete " and "reportError "
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
"testEchoNonBlockingClient" target of the ant file found at the
"Axis2Home/samples" directory.</p>
<h3>EchoNonBlockingDualClient</h3>
<p>The solution provided by the Non-Blocking API has one limitation when it
comes to  Web Service invocations which takes long time to complete. The
limitation is due to the use of single transport connection to invoke the Web
Service and to retrieve the response. In other words, client API provides a
non blocking invocation mechanism for the users, but the request and the
response comes in a single transport 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  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 "echo" 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("echo", 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 "green" color. Since our correlation mechanism is based on addressing
we need to first "<strong>engage</strong>" the addressing module.<font
color="#0000ff"> <font color="#000000"><b>"call.engageModule(new
QName(Constants.MODULE_ADDRESSING));" </b>informs the Axis2 engine to engage
the addressing module at the client side. The boolean flag (value true) in
the "<br>
<b>call.setTransportInfo(...)</b>" method informs the Axis2 engine to use
separate transport connections for request and response. Finally
"<b>call.close()</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 need one more step to perform. As
mentioned earlier Axis2 uses addressing based correlation mechanism and hence
we need to "engage" addressing module in the server side as well. According
to the Axis2 architecture addressing module is deployed in the
"<strong>pre-dispatch</strong>" phase (See <a
href="file:///G:/Documents and Settings/Jaliya/Desktop/Axis2ArchitectureGuide.html">Architecture
Guide</a> for more details about phases)  and hence "engaging" means simply
adding module reference in the "axis2.xml" (NOT the "services.xml"). Please
add the following line to the "axis2.xml" that you can find in the
"/webapps/axis2/WEB-INF" directory in the servlet container. </p>
<pre style="margin-bottom: 0.2in"> &lt;module ref="addressing"/&gt;</pre>
<p>Note: Please note that<font color="#000000"> once you change the
"axis2.xml" you need to restart the servlet container.</font></p>
<p>This will enable the addressing in the server side and now you can test
the "TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
target of the ant file found at "Axis2Home/samples" 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 "Axis2Home/samples/userguide/src/userguide/clients/" 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
"echoBlockingDualClient" target of the ant build file found in the
"Axis2Home/samples" 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
"Axis2SampleDocLitPortType". Simply run the WSDL2Java tool that can be found
in the bin directory of the Axis2 distribution using the following
command.</p>
<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide</pre>
<p>This will generate the required stub "Axis2SampleDocLitPortTypeStub.java"
that can be used to invoke the Web Service Axis2SampleDocLitPortType. Let's
see how we can use this stub to write Web Service clients to utilize the Web
Service Axis2SampleDocLitPortType (the service that we have already
deployed).</p>
<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,
"http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
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,
"http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request document to be sent.
EchoStringParamDocument reqDoc= EchoStringParamDocument.Factory.newInstance();
reqDoc.setEchoStringParam("Axis2 Echo");
//invokes the web service.
EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
System.out.println(resDoc.getEchoStringReturn());
} catch (Exception e) {
e.printStackTrace();
}</pre>
<p>Similarly following code fragments 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,
"http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request document to be sent.
EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
paramArray.addString("Axis2");
paramArray.addString("Echo");
reqDoc.setEchoStringArrayParam(paramArray);
EchoStringArrayReturnDocument resDoc = stub.echoStringArray(reqDoc);
//Get the response params
String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
for (int i = 0; i &lt; resParams.length; i++) {
System.out.println(resParams[i]);
}
} catch (Exception e) {
e.printStackTrace();
}</pre>
<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,
"http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
//Create the request Document
EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
//Create the complex type
SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
reqStruct.setVarFloat(100.50F);
reqStruct.setVarInt(10);
reqStruct.setVarString("High");
reqDoc.setEchoStructParam(reqStruct);
//Service invocation
EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
SOAPStruct resStruct = resDoc.getEchoStructReturn();
System.out.println("floot Value :" + resStruct.getVarFloat());
System.out.println("int Value :" + resStruct.getVarInt());
System.out.println("String Value :" + resStruct.getVarString());
} catch (Exception e) {
e.printStackTrace();
}</pre>
<h2><a name="Modules"></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>
<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>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
."mar" (Module Archive) to deploy modules in Axis2. Following diagram shows
the file structure inside that 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"
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 "org.apache.axis2.modules.Module" 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. "public void
invoke(MessageContext ctx);" is the method that is called by the 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 revoke(MessageContext msgContext) {
log.info(msgContext.getEnvelope().toString());
}
public void setName(QName name) {
this.name = name;
}
}</pre>
<h4>Step3 : module.xml</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 the 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 it can be seen there are four phases defined in this "module.xml"</p>
<ol>
<li><p style="margin-bottom: 0in">inflow               - Represents the
handler chain that will run when a message is coming in. </p>
</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 going to run."InFlowLogHandler" 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. "&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>
<h4>Step 4: Modify the "axis2.xml"</h4>
<p>In this handler the phase "loggingPhase" is defined by the module writer.
It is not a pre-defined handler phase and hence the module writer should
introduce it to the "axis2.xml" (NOT the services.xml) so that Axis2 engine
knows where to place the handler in different "flows" (<br>
InFlow, OutFlow, etc...). Following xml lines shows the respective changes to
the "axis2.xml" in order for us to deploy this logging module in Axis2
engine. This is an extract of the phase section of the "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"/&gt;
&lt;phase name="PostDispatch"/&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="<font color="#33cc00">loggingPhase</font>"/&gt;
&lt;/phaseOrder&gt;
&lt;phaseOrder type="outflow"&gt;
&lt;!-- user can add his own phases to this area --&gt;
&lt;phase name="<font color="#33cc00">loggingPhase</font>"/&gt;
&lt;/phaseOrder&gt;
&lt;phaseOrder type="INfaultflow"&gt;
&lt;!-- user can add his own phases to this area --&gt;
&lt;phase name="<font color="#33cc00">loggingPhase</font>"/&gt;
&lt;/phaseOrder&gt;
&lt;phaseOrder type="Outfaultflow"&gt;
&lt;!-- user can add his own phases to this area --&gt;
&lt;phase name="<font color="#33cc00">loggingPhase</font>"/&gt;
&lt;/phaseOrder&gt;</pre>
<p>Shown in green, the custom phase "loggingPhase" 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 "services.xml"</h4>
<p>Up to this point we have created the required classes and the
configuration descriptions for the logging module and by changing the
"axis2.xml" we have created the required phases for the logging module. Now
the 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 guide, the MyService. However, since we need to modify the
"services.xml" 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
"Axis2Home/samples/userguide/src/userguide/example2" directory. The simple
changes that we have done to he "services.xml' are shown in the green color
in the following lines of xml.</p>
<pre>&lt;service name="<font color="#33cc00">MyServiceWithModule</font>"&gt;
&lt;description&gt;
This is a sample Web Service with a logging module engaged.
&lt;/description&gt;
<font color="#33cc00">&lt;module ref="logging"/&gt;</font>
&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 the "services.xml". This informs the Axis2 engine
that the module "logging" should be engaged for this service. The handler in
side the module will be executed in their respective phases as described by
the "module.xml".</p>
<p><b>Step6 : Packaging</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 "Axis2Home/samples/userguide" 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 "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 "LoggingModule.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 just deploy and see. Please deploy this service using the same steps that
you use to deploy "MyService" and copy the "LoggingModule.mar" file to the
"modules" directory. Then by using the "TestWebServiceWithModuleClient.bat"
and "TestWebServiceWithModuleClient.sh" in the
"Axis2Home/samples/userguide/src/userguide/clients/bin" directory.</p>
<p>Note: To see the logs, the user needs to modify the "log4j.properties" to
log INFO as well. The property file is located in
"webapps\axis2\WEB-INF\classes" of your servlet container. Change the line
"log4j.rootCategory= ERROR, LOGFILE" to "log4j.rootCategory=INFO, ERROR,
LOGFILE".</p>
<h2> </h2>
<h2><a name="Other_Samples"></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>
<li><p>Amazon queuing sample</p>
</li>
</ul>
<p>Following is a simple introduction to each of the samples. Each sample
contains it's own help document that says about  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 "guessed" AXIS_HOME would not be correct in this case)</p>
<h2><a name="Tools"></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> </p>
<h2><a name="Advanced_Topics"></a>Advanced Topics</h2>
<ul>
<li><p style="margin-bottom: 0in"><a href="rest-ws.html">RESTful Web
Services</a></p>
</li>
<li><p style="margin-bottom: 0in"><a href="tcp-transport.html">TCP
transport</a></p>
</li>
<li><p style="margin-bottom: 0in"><a href="mail-transport.html">Mail
Transport</a></p>
</li>
<li><p style="margin-bottom: 0in"><a href="http-transport.html">HTTP
Transports</a></p>
</li>
<li><p><a href="mtom-guide.html">MTOM with Axis2</a></p>
</li>
<li><p><a href="security-module.html">Securing SOAP Messages with WSS4J</a></p>
</li>
</ul>
</body>
</html>