<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Axis 2.0 User's Guide</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="css/axis-docs.css" type="text/css" rel="stylesheet" />
<style type="text/css">
<!--
.style1 {font-family: "Courier New", Courier, mono}
.style2 {font-size: 14px}
.style3 {color: #990000}
.style4 {
	font-family: "Courier New", Courier, mono;
	font-size: 14px;
	color: #990000;
}
.style9 {color: #FF0066}
.style10 {color: #33CC00}
.style13 {color: #00CC00}
.style15 {color: #0000FF}
-->
</style>
</head>

<body>
<h1 align="center"><a name="_Toc96697849">Axis 2.0 User's Guide </a></h1>
<p>&nbsp; </p>
<h2><a name="_Toc96698076"></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><a name="_Toc96698077"></a>What is Axis 2.0 ? </h2>
<p>Before we start, its highly recommended to read <a href="http://ws.apache.org/axis/java/user-guide.html">Axis 1.x User's guide </a>, if you are new to Axis. </p>
<p>Axis 2.0 is the next generation of Apache Axis. In late August 2004, during the Axis Summit held in Colombo, Sri Lanka, a new architecture was introduced to have a much more flexible, efficient and configurable Axis. Even though the architecture is new, some of the well established concepts from Axis 1.x, like handlers are preserved in Axis 2.0 also. Axis 2.0 comes with lots of new features, enhancements and new industry specification implementations. </p>
<p>After months of continued discussion and coding effort in this direction, Axis 2.0 now delivers the following key features: </p>
<ul>
  <li><strong>Speed</strong>. Axis uses its own object model and StAX (streaming) parsing to achieve significantly greater speed than earlier versions of Apache AXIS. </li>
  <li><strong>Low memory foot print</strong>. Axis 2.0 was designed ground-up keeping low memory foot print in mind. </li>
  <li><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 </li>
  <li><strong>Hot Deployment.</strong> One can now hot deploy web services and handlers. </li>
  <li><strong>Asynchronous Web Services</strong>. Axis 2.0 now support asynchronous web services invocation and asynchronous web services. </li>
  <li><strong>MEP Support. </strong>Axis 2.0 now comes handy with support for Message Exchange Patterns. </li>
  <li><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. </li>
  <li><strong>Stability</strong>. Axis defines a set of published interfaces which change relatively slowly compared to the rest of Axis. </li>
  <li><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. </li>
  <li><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. </li>
  <li><strong>WSDL support.</strong> Axis 2.0 supports the <a href="http://www.w3.org/TR/wsdl">Web Service Description Language </a>, version 1.1 and 2.0, which allows you to easily build stubs to access remote services, and also to automatically export machine-readable descriptions of your deployed services from Axis. </li>
</ul>
<p>We hope you enjoy using Axis. Please note that this is an open-source effort - if you feel the code could use some new features or fixes, please get involved and lend a hand! The Axis developer community welcomes your participation . </p>
<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>AXIOM, a SOAP specific streaming XML infoset model for SOAP 1.1/1.2 Messages</li>
  <li>Modules, mechanism to extend the SOAP Processing Model</li>
  <li>Support for WS-Addressing</li>
  <li>Client API</li>
  <li>Support for One-Way Messaging</li>
  <li>Support for Request Response Messaging
      <ol>
        <LI>Synchronous, Using a two way transport</LI>
        <LI>Asynchronous, Using a two way transport</LI>
        <LI>Synchronous, Using a one way transport</LI>
        <LI>Asynchronous, Using a one way transport</LI>
      </ol>
  </li>
  <li>Hot deployment of Web Services and Module deployment based on the archived modules </li>
  <li>WSDL Code Generation Tool.</li>
  <li>REST Web Service Support</li>
  <li>HTTP transport Support</li>
  <li>SMTP transport Support</li>
  <li>TCP transport Support</li>
</ul>
<p>The release include following tools</p>
<ol>
  <LI>Admin Web App</LI>
  <LI>WSDL2WS, eclipe Plugin/Command line version</LI>
  <LI>Service Archive Wizard, eclipe Plugin</LI>
  <LI>Module Archive Wizard, eclipe Plugin</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 & able!</p>
<ul>
  <li> Encoding/data binding</li>
  <li>SOAP 1.1 and 1.2 validation </li>
  <li> JAX-RPC 1.1/2.0 compliance</li>
  <li> Data binding support for WSDL Based code (server/client) code generator</li>
  <li> MTOM/MIME/SWA attachments support</li>
  <li> Complete XML infoset support for AXIOM</li>
  <li> Implementation of other transports. e.g. JMS..</li>
  <li> Web Service Policy Support</li>
</ul>
<!-- 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> -->
<h2><a name="_Toc96697863"></a>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> <span class="style9">
<font color="#000000">&quot;samples/userguide/src&quot;</font></span></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-M2-bin.zip&quot; and &quot;axis2-M2-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> 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.htm">Installation Guide</a>)</p>
<h3>MyService</h3>
<p>First let's see how we can write a simple Web Service (MyService) and deploy it. For this purpose we will create a Web Service with two operations as follows.</p>
<source><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></source>
<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>
<p>Axis2 uses &quot;service.xml&quot; to keep configurations for a Web Service. Each Web Service deployed 
in Axis2 needs a &quot;service.xml&quot; containing the configurations. &quot;service.xml&quot; for MyService will be as follows; we will see what each parameter means later.</p>
<source><pre>&lt;service name=&quot;MyService&quot;&gt;<br>    &lt;description&gt;<br>        This is a sample Web Service with two operations, echo and ping.<br>    &lt;/description&gt;<br>    &lt;parameter name=&quot;ServiceClass&quot; locked=&quot;xsd:false&quot;&gt;userguide.example1.MyService&lt;/parameter&gt;<br>    &lt;operation name=&quot;echo&quot;&gt;<br>        &lt;messageReceiver class=&quot;org.apache.axis.receivers.RawXMLINOutMessageRecevier&quot;/&gt;<br>    &lt;/operation&gt;<br>     &lt;operation name=&quot;ping&quot;&gt;<br>        &lt;messageReceiver class=&quot;org.apache.axis.receivers.RawXMLINOnlyMessageRecevier&quot;/&gt;<br>    &lt;/operation&gt;<br> &lt;/service&gt;</pre></source>
<p>As it can be seen, first line of the &quot;service.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>RawXMLINOutMessageRecevier</strong> since it is an 
IN-OUT operation. For IN-ONLY operation, &quot;ping&quot; we have used <strong>RawXMLINOnlyMessageRecevier</strong> as the message receiver. </p>
<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;service.xml&quot; packaged 
in the META-INF as shown in the following picture.</p>
<p><img src="images/userguide/ServiceItems.jpg" width="176" height="91"></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>
<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" width="797" height="654"> </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>
<h2> 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 to invoke Web Services. So let's try to analyze some common service 
invocation paradigms.</p>
<p> Many web service engines provide the users with a Blocking and Non-Blocking 
client APIs. </p>
<ul>
  <li><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.</li>
  <li><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.</li>
</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>
<table border="1" cellpadding="0" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%" height="99">
  <tr>
    <td width="33%" height="19">API (Blocking/Non-Blocking)</td>
    <td width="33%" height="19">&nbsp;Dual Transports (Yes/No)</td>
    <td width="33%" height="19">Description</td>
  </tr>
  <tr>
    <td width="33%" height="19">Blocking</td>
    <td width="33%" height="19">No</td>
    <td width="33%" height="19">Simplest and the familiar invocation pattern</td>
  </tr>
  <tr>
    <td width="33%" height="19">Non-Blocking</td>
    <td width="33%" height="19">No</td>
    <td width="33%" height="19">Using callbacks or polling</td>
  </tr>
  <tr>
    <td width="33%" height="19">Blocking</td>
    <td width="33%" height="19">Yes</td>
    <td width="33%" height="19">This is useful when the service operation is 
    IN-OUT in nature but the transport used is One-Way (e.g. SMTP)</td>
  </tr>
  <tr>
    <td width="33%" height="19">Non-Blocking</td>
    <td width="33%" height="19">Yes</td>
    <td width="33%" height="19">This is can be used to gain the maximum 
    asynchronous behavior. No blocking in the API level and also in the 
    transport level</td>
  </tr>
</table>
<p><b>Axis2 provides the user with all these possibilities to invoke Web 
Services&nbsp; and let's see how to use them Now!</b></p>
<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>
<source><pre>  try {
            OMElement payload = ClientUtil.getEchoOMElement();
            <span class="style10">Call call = new Call();
            call.setTo(targetEPR);
            call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false);

            OMElement result = (OMElement) call.invokeBlocking("echo", payload);
</span>
            StringWriter writer = new StringWriter();
            result.serializeWithCache(XMLOutputFactory.newInstance().createXMLStreamWriter(writer));
            writer.flush();

            System.out.println(writer.toString());

        } catch (AxisFault axisFault) {
            axisFault.printStackTrace();
        } catch (XMLStreamException e) {
            e.printStackTrace();
        }
}
</pre></source></p>
<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>
<source><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></source>
</p> 
<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("echo", 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>
<source><pre>call.invokeNonBlocking(&quot;echo&quot;, payload, callback);</pre></source>
<p>The invocation  accepts a callback object as a parameter. Axis2 client API provides an 
abstract Callback with the following methods.</p>
<p><source><pre>public abstract void onComplete(AsyncResult result);
public abstract void reportError(Exception e);
public boolean isComplete() {}</pre></source></p>
<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>
<source><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, <span class="style13">true</span>);

            //Callback to handle the response
            Callback callback = new Callback() {
                public void onComplete(AsyncResult result) {
                    try {
                        StringWriter writer = new StringWriter();
                        result.getResponseEnvelope().serializeWithCache(
                                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);
            }</pre></source>
<source><pre>	  <font color="#33CC00">call.close();</font>

        } catch (AxisFault axisFault) {
            axisFault.printStackTrace();
        } catch (Exception ex) {
            ex.printStackTrace();
        }
</pre></source>
<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.<span class="style15">
<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></span></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="Axis2ArchitectureGuide.html">Architecture Guide</a> for more 
details about phases)&nbsp; and hence &quot;engaging&quot; means simply adding module reference in the &quot;server.xml&quot; (NOT the &quot;service.xml&quot;). Please add the following line to the &quot;server.xml&quot; that you can find in the &quot;/webapps/axis2/WEB-INF&quot; 
directory in the servlet container. </p>
<source><pre> &lt;module ref=&quot;addressing&quot;/&gt;</pre></source>
<p>Note: Please note that<span class="style15"><font color="#000000"> once you change the &quot;server.xml&quot; you need to restart the servlet container.</font></span></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>
<h2>Modules</h2>
<p>Axis2 provides an extended support for modules (See
<a href="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>Create the Module Implementation</li>
  <li>Create the Handlers</li>
  <li>Create the moduel.xml</li>
  <li>Modify the &quot;server.xml&quot; (if you need custom phases)</li>
  <li>Modify the &quot;service.xml&quot; to engage modules at the deployment time.</li>
  <li>Package in a &quot;.mar&quot; (Module Archive)</li>
  <li>Deploy the module in Axis2</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 .&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 border="0" src="images/userguide/ModuleView.jpg" width="185" height="120"></p>
<h4>
Step1 : LoggingModule Class</h4>
<p>LoggingModule is the implementation class of the Axis2 module. Axis2 modules 
should implement the &quot;org.apache.axis.modules.Module&quot; interface with the 
following methods.</p>
<source><pre>public void init(AxisConfiguration axisSystem) throws AxisFault;//Initialize the module
public void shutdown(AxisConfiguration axisSystem) throws AxisFault;//End of module processing
</pre></source>
<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="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>
<source><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></source>
<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>
<p>
<source><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></source></p>

<p>As it can be seen there are four phases defined in this &quot;module.xml&quot;</p>
<ol>
  <li>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.</li>
  <li>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.</li>
  <li>Outfaultflow&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - Represents the handler chain 
  that will run when there is a fault and the  fault is going out</li>
  <li>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</li>
</ol>

<p>
<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>
<source><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></source></p>

<h4>Step 4: Modify the &quot;server.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;server.xml&quot; (NOT the service.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;server.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;server.xml&quot;.</p>


<source><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></source>


<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;service.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;server.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;service.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;service.xml' are shown in 
the green color in the following lines of xml.</p>

<p><pre><cod>&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.axis.receivers.RawXMLINOutMessageRecevier&quot;/&gt;
&lt;/operation&gt;
&lt;operation name=&quot;ping&quot;&gt;
&lt;messageReceiver class=&quot;org.apache.axis.receivers.RawXMLINOutMessageRecevier&quot;/&gt;
&lt;/operation&gt;
&lt;/service&gt;
</code></pre></p>


<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;service.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;service.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>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>Google spell checker sample</li>
  <!--<li>Google search sample</li> -->
  <li>Amazon queuing sample</li>
</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>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="CodegenToolReference.html">Service Archiver</a>.</p>
<hr/>
<p>&nbsp;</p>
<h2><a name="#configTransport">Configuring Transports</a></h2>
<h3>Configuring HTTP transports</h3>
<p>The HTTP is configured by default, the server can be started by following </p>
<code>Java org.apache.axis.transport.http.SimpleHTTPServer repository port</code>
<h3>Configuring TCP transports</h3>
<p>The TCP transport is configured by default</p>


<h3>Configuring Mail transport</h3>
<p>Mail transport has two parts, transport Sender and transport Listener. </p>

 <a>First you need following additional jar dependencies in the classpath, they can be found by downloading the <a href="http://java.sun.com/products/javamail/">JavaMail API</a></p>
  <ol>
  <LI>pop3.jar</LI>
  <LI>smtp.jar</LI>
  <LI>mailapi.jar</LI>
  <LI>activation.jar</LI>
  </ol>
  
  
<h4>Transport Sender</h4>
<p>You need a mail account in a SMTP server, and Mail transport sender can be activated by adding following entry to the server.xml file or client.xml file or in both.
  </p>
  
  <code>
  <pre>   &lt;transportSender name="mail" class="org.apache.axis.transport.mail.MailTransportSender"&gt;
        &lt;parameter name="transport.mail.smtp.host" locked="xsd:false"&gt;smtp server host&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.user" locked="xsd:false"&gt;user name&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.password" locked="xsd:false"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.smtp.port" locked="xsd:false"&gt;25&lt;/parameter&gt;
   &lt;/transportSender&gt;
  </pre>
  </code>
  
  <h4>Transport Receiver</h4>
 
  
  <p>You need a mail address that has pop access, the mail Listener can be activated by adding following entry to the server.xml file or client.xml file or in both.</p>
  
  <code><pre>  &lt;transportReceiver name="mail" class="org.apache.axis.transport.mail.SimpleMailListener">
        &lt;parameter name="transport.mail.pop3.host" locked="xsd:false"&gt;pop server host&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.user" locked="xsd:false"&gt;user name&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.password" locked="xsd:false"&gt;password&lt;/parameter&gt;
        &lt;parameter name="transport.mail.pop3.port" locked="xsd:false"&gt;110&lt;/parameter&gt;
        &lt;parameter name="transport.mail.replyToAddress" locked="xsd:false"&gt;email address&lt;/parameter&gt;
  &lt;/transportReceiver&gt;
  </pre></code>
  
  <p>At the Client side if the Mail Listener is needed it is automatically started by Axis2. If the Mail Listener is need to be started as the server it can be done with following command with the all the axis2 jars and the mail dependency jars in the classpath.</p>
  
  <code>Java org.apache.axis.transport.mail.SimpleMailListener repository-directory</code>
  
  <h4>Configure James as SMTP and POP server</h4>
  <p>Download the <a href="http://james.apache.org/">Apache James</a> and start the James, connect to the James via telnet for administrator James with following code
</p>
  <code>
  <pre>  $telnet 127.0.0.1 4555
  Trying 127.0.0.1...
Connected to localhost.localdomain (127.0.0.1).
Escape character is '^]'.
JAMES Remote Administration Tool 2.2.0
Please enter your login and password
Login id:
root
Password:
root
Welcome root. HELP for a list of commands
  </pre>
  </code>

  <p>add users to the James</p>
  <code>
  <pre>adduser axis2-server axis2
User axis2-server added
adduser axis2-client axis2
User axis2-client added
Connection closed by foreign host.
  </pre>
  </code>  
  
  <p>Now the James is up and running with the accounts</p>
  
  <hr>  
  
  <p>&nbsp;</p>
  
  <!--
  <h3>Enable the REST support for the Client side</h3>
  <p>There are two ways to enable REST at the client side, first is to do the same thing done at the 
  Server side in the client.xml file or do the following in the Call.</p>
  <code>call.set(Constants.Configuration.DO_REST,"true");</code>
-->
</body>
</html>