axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cha...@apache.org
Subject svn commit: r488985 [2/5] - in /webservices/axis2/branches/java/1_1/xdocs/1_1: ./ images/
Date Wed, 20 Dec 2006 09:04:28 GMT
Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html?view=diff&rev=488985&r1=488984&r2=488985
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/dii.html Wed Dec 20 01:04:27 2006
@@ -1,326 +1,326 @@
-<html>
-<head>
-  <meta http-equiv="content-type" content="">
-  <title></title>
-  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
-</head>
-
-<body>
-<a name="Web_Service_Clients_Using_Axis2"></a>
-
-<h1>Writing Web Service Clients Using Axis2's Primary APIs</h1>
-
-<p>This section presents complex yet powerful <strong>XML based client
-API</strong> which is intended for advanced users. However if you are a new
-user we recommend using code generation given in the <a
-href="userguide.html">user guide</a>.</p>
-
-<p>Web services can be used to provide a wide-range of functionality to the
-user from simple, less time consuming operations such as "getStockQuote" to
-time consuming business services. When we utilize (invoke using client
-applications) these Web services we cannot use simple generic invocation
-paradigms that suite all the timing complexities involved in the service
-operations. For example, if we use a single transport channel (such as HTTP)
-to invoke a Web service with an IN-OUT operation that takes a long time to
-complete, then most often we may end up with "connection time outs". On the
-other hand, if there are simultaneous service invocations that we need to
-perform from a single client application, then the use of a "blocking" client
-API will degrade the performance of the client application. Similarly, there
-are various other consequences such as One-Way transports that come into play
-when we need them. Let's try to analyze some common service invocation
-paradigms.</p>
-
-<p>Many Web service engines provide users with a Blocking and Non-Blocking
-client APIs.</p>
-<ul>
-  <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
-    invocation is called, the client application hangs and only gets control
-    back when the operation completes, after which the client receives a
-    response or a fault. This is the simplest way of invoking Web services
-    and it also suites many business situations.</p>
-  </li>
-  <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
-    hence once a service invocation is called, the client application
-    immediately gets the control back and the response is retrieved using the
-    callback object provided. This approach provides the flexibility to the
-    client application to invoke several Web services simultaneously without
-    blocking the operation already invoked.</p>
-  </li>
-</ul>
-
-<p>Both these mechanisms work in the API level. Let's name the asynchronous
-behavior that we can get using the Non-Blocking API as <b>API Level
-Asynchrony.</b></p>
-
-<p>Both these mechanisms use single transport connections to send the request
-and to receive the response. They severely lag the capability of using two
-transport connections for the request and the response (either One-Way or
-Two-Way). So both these mechanisms fail to address the problem of long
-running transactions (the transport connection may time-out before the
-operation completes). A possible solution would be to use two separate
-transport connections for request and response. The asynchronous behavior
-that we gain using this solution can be called <b>Transport Level
-Asynchrony</b>.</p>
-
-<p>By <strong>combining API Level Asynchrony &amp; Transport Level
-Asynchrony</strong> we can obtain four different invocation patterns for Web
-services as shown in the following table.</p>
-<a name="table1"></a>
-
-<table width="100%" border="1" cellpadding="0" cellspacing="0">
-  <tbody>
-    <tr>
-      <td width="33%" height="19"><p><strong>API
-        (Blocking/Non-Blocking)</strong></p>
-      </td>
-      <td width="33%"><p><strong>Dual Transports (Yes/No)</strong></p>
-      </td>
-      <td width="33%"><p><strong>Description</strong></p>
-      </td>
-    </tr>
-    <tr>
-      <td width="33%" height="19"><p>Blocking</p>
-      </td>
-      <td width="33%"><p>No</p>
-      </td>
-      <td width="33%"><p>The simplest and more familiar invocation pattern</p>
-      </td>
-    </tr>
-    <tr>
-      <td width="33%" height="19"><p>Non-Blocking</p>
-      </td>
-      <td width="33%"><p>No</p>
-      </td>
-      <td width="33%"><p>Using callbacks or polling</p>
-      </td>
-    </tr>
-    <tr>
-      <td width="33%" height="19"><p>Blocking</p>
-      </td>
-      <td width="33%"><p>Yes</p>
-      </td>
-      <td width="33%"><p>This is useful when the service operation is IN-OUT
-        in nature but the transport used is One-Way (e.g. SMTP)</p>
-      </td>
-    </tr>
-    <tr>
-      <td width="33%" height="19"><p>Non-Blocking</p>
-      </td>
-      <td width="33%"><p>Yes</p>
-      </td>
-      <td width="33%"><p>This is can be used to gain the maximum asynchronous
-        behavior. Non blocking in the API level and also in the transport
-        level</p>
-      </td>
-    </tr>
-  </tbody>
-</table>
-
-<p>Axis2 provides the user with all these possibilities to invoke Web
-services.</p>
-
-<p>Following section present clients that use different possibilities
-presented above to invoke a Web Service using <code>ServiceClient</code>s.
-All samples mentioned in this guide are located at the <b><font
-color="#000000">"samples\userguide\src"</font></b> directory of the binary
-distribution.</p>
-
-<p>This section presents four types of clients.</p>
-<ol>
-  <li>Request-Response, Blocking Client</li>
-  <li>One Way Client</li>
-  <li>Request-Response, Non-Blocking that uses one transport connection</li>
-  <li>Request-Response, Non-Blocking that uses two transport connections</li>
-</ol>
-<a name="EchoBlockingClient"></a>
-
-<h4>Request-Response, Blocking Client</h4>
-
-<p>Axis2 provides the user with several invocation patterns for Web services,
-ranging from pure blocking single channel invocations to non-blocking dual
-channel invocations. Let's first see how we can write a client to invoke
-"echo" operation of "MyService" using the simplest blocking invocation. The
-client code you need to write is as follows.</p>
-<source><pre>  try {
-            OMElement payload = ClientUtil.getEchoOMElement();
-            <span style="color: rgb(36, 193, 19);">            
-            Options options = new Options();
-            options.setTo(targetEPR); // this sets the location of MyService service
-            
-            ServiceClient serviceClient = new ServiceClient();
-            serviceClient.setOptions(options);
-
-            OMElement result = serviceClient.sendReceive(payload);
-            </span>
-            System.out.println(result);
-
-        } catch (AxisFault axisFault) {
-            axisFault.printStackTrace();
-        } 
-}</pre>
-</source>
-<p>1. The lines highlighted in green lines show the set of operations that
-you need to perform in order to invoke a Web service.</p>
-
-<p>2. The rest is used to create the OMElement that needs to be sent and
-display the response OMElement.</p>
-
-<p>To test this client, use the provided ant build file that can be found in
-the "<strong>Axis2_HOME/samples/userguide</strong>" directory. Run the
-"run.client.blocking" target. If you can see the response OMElement printed
-in your command line, then you have successfully tested the client.</p>
-<a name="PingClient"></a>
-
-<h4>One Way Client</h4>
-
-<p>In the Web service "MyService" we had an IN-ONLY operation with the name
-"ping" (see <a href="userguide.html#Web_Services_Using_Axis2">Creating a New Web Service</a>). Let's write a client to invoke this operation. The client
-code is as follows:</p>
-<pre> try {
-       OMElement payload = ClientUtil.getPingOMElement();
-       Options options = new Options();
-       options.setTo(targetEPR);
-       ServiceClient serviceClient = new ServiceClient();
-       serviceClient.setOptions(options);
-       serviceClient.fireAndForget(payload);
-        /**
-         * We have to block this thread untill we send the request , the problem
-         * is if we go out of the main thread , then request wont send ,so
-         * you have to wait some time :)
-         */
-       Thread.sleep(500);
-     } 
-catch (AxisFault axisFault) {
-            axisFault.printStackTrace();
-     }</pre>
-
-<p>Since we are accessing an IN-ONLY operation we can directly use the
-<code>fireAndForget()</code> in ServiceClient to invoke this operation. This
-will not block the invocation and will return the control immediately back to
-the client. You can test this client by running the target "run.client.ping"
-of the ant build file at "<strong>Axis2Home/samples/userguide</strong>".</p>
-
-<p>We have now invoked the two operations in our service. Are we done? No!
-There's a lot more to explore. Let's see some other ways to invoke the same
-operations.</p>
-<a name="EchoNonBlockingClient"></a>
-
-<h4>Request-Response, Non-Blocking that uses one transport connection</h4>
-
-<p>In the "EchoBlockingClient" once the
-<code>serviceClient.sendReceive(payload);</code> is called, the client is
-blocked till the operation is complete. This behavior is not desirable when
-there are many Web service invocations to be done in a single client
-application or within a GUI. A solution would be to use a Non-Blocking API to
-invoke Web services. Axis2 provides a callback based non-blocking API for
-users.</p>
-
-<p>A sample client for this can be found under
-"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
-the name "EchoNonBlockingClient". If we consider the changes that users may
-have to do with respect to the "EchoBlockingClient" that we have already
-seen, it will be as follows:</p>
-<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
-
-<p>The invocation accepts a callback object as a parameter. Axis2 client API
-provides an abstract Callback with the following methods:</p>
-<pre>public abstract void onComplete(AsyncResult result);
-public abstract void onError(Exception e);
-public boolean isComplete() {}</pre>
-
-<p>The user is expected to implement the "onComplete " and "onError " methods
-of their extended call back class. The Axis2 engine calls the "onComplete"
-method once the Web service response is received by the Axis2 Client API
-(ServiceClient). This will eliminate the blocking nature of the Web service
-invocation and provide users with the flexibility to use Non Blocking API for
-Web service Clients.</p>
-
-<p>To run the sample client ("EchoNonBlockingClient") you can simply use the
-<code>run.client.nonblocking</code> target of the ant file found at the
-"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
-<a name="EchoNonBlockingDualClient"></a>
-
-<h4>Request-Response, Non-Blocking that uses two transport connections</h4>
-
-<p>The solution provided by the Non-Blocking API has one limitation when it
-comes to Web service invocations which take a long time to complete. The
-limitation is due to the use of single transport connections to invoke the
-Web service and to retrieve the response. In other words, client API provides
-a non blocking invocation mechanism for users, but the request and the
-response come in a single transport (Two-Way transport) connection (like
-HTTP). Long running Web service invocations or Web service invocations using
-One-Way transports (like SMTP) cannot be utilized by simply using a non
-blocking invocation.</p>
-
-<p>The trivial solution is to use separate transport connections (either
-One-Way or Two-Way) for the request and response. The next problem that needs
-to be solved is the correlation (correlating the request and the response).
-<a href="http://www.w3.org/2002/ws/addr/" target="_blank">WS-Addressing</a>
-provides a neat solution to this using &lt;wsa:MessageID&gt; and
-&lt;wsa:RelatesTo&gt; headers. Axis2 provides support for addressing based
-correlation mechanism and a complying Client API to invoke Web services with
-two transport connections. (Core of Axis2 does not depend on WS-Addressing,
-but contains a set of parameters like in addressing that can be populated in
-any means. WS-Addressing is one of the uses that may populate them. Even the
-transports can populate these. Hence Axis2 has the flexibility to use
-different versions of addressing)</p>
-
-<p>Users can select between Blocking or Non-Blocking APIs for the Web service
-clients with two transport connections. By simply using a boolean flag, the
-same API can be used to invoke Web services (IN-OUT operations) using two
-separate transport connections. Let's see how it's done using an example.
-Following code fragment shows how to invoke the same "echo" operation using
-Non-Blocking API with two transport connections<strong>. The ultimate
-asynchrony!!</strong></p>
-<pre>  try {
-            OMElement payload = ClientUtil.getEchoOMElement();
-
-            Options options = new Options();
-            options.setTo(targetEPR);
-            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
-            options.setUseSeparateListener(true);
-            options.setAction("urn:echo");  // this is the action mapping we put within the service.xml
-
-            //Callback to handle the response
-            Callback callback = new Callback() {
-                public void onComplete(AsyncResult result) {
-                    System.out.println(result.getResponseEnvelope());
-                }
-
-                public void onError(Exception e) {
-                    e.printStackTrace();
-                }
-            };
-            //Non-Blocking Invocation            
-            sender = new ServiceClient();            
-            sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
-            sender.setOptions(options);            
-            sender.sendReceiveNonBlocking(payload, callback);            
-            //Wait till the callback receives the response.            
-            while (!callback.isComplete()) {                
-             Thread.sleep(1000);            
-            }            
-            //Need to close the Client Side Listener.        
-            } catch (AxisFault axisFault) {            
-              axisFault.printStackTrace();
-            } catch (Exception ex) {
-              ex.printStackTrace();
-            } finally {
-            try {
-                sender.cleanup();
-            } catch (AxisFault axisFault) {
-                //have to ignore this
-            }
-        }</pre>
-
-<p>The boolean flag (value true) in the
-<b><code>options.setUseSeparateListener(...)</code></b> method informs the
-Axis2 engine to use separate transport connections for request and response.
-Finally <b><code>sender.cleanup()</code></b> informs the Axis2 engine to stop
-the client side listener started to retrieve the response.</p>
-
-<p>To run the sample client ("EchoNonBlockingDualClient") you can simply use
-the "run.client.nonblockingdual" target of the ant file found at the
-"<strong>Axis2_HOME/samples/userguide/</strong>" directory.</p>
-</body>
-</html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="">
+  <title></title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body>
+<a name="Web_Service_Clients_Using_Axis2"></a>
+
+<h1>Writing Web Service Clients Using Axis2's Primary APIs</h1>
+
+<p>This section presents complex yet powerful <strong>XML based client
+API</strong> which is intended for advanced users. However, if you are a new
+user we recommend using code generation given in the <a
+href="adv-userguide.html">Advance User's Guide</a>.</p>
+
+<p>Web services can be used to provide a wide-range of functionality to the
+user from simple, less time consuming operations such as "getStockQuote" to
+time consuming business services. When we utilize (invoke using client
+applications) these Web services we cannot use simple generic invocation
+paradigms that suite all the timing complexities involved in the service
+operations. For example, if we use a single transport channel (such as HTTP)
+to invoke a Web service with an IN-OUT operation that takes a long time to
+complete, then most often we may end up with "connection time outs". On the
+other hand, if there are simultaneous service invocations that we need to
+perform from a single client application, then the use of a "blocking" client
+API will degrade the performance of the client application. Similarly, there
+are various other consequences such as One-Way transports that come into play
+when we need them. Let's try to analyze some common service invocation
+paradigms.</p>
+
+<p>Many Web service engines provide users with a Blocking and Non-Blocking
+client APIs.</p>
+<ul>
+  <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
+    invocation is called, the client application hangs and only gets control
+    back when the operation completes, after which the client receives a
+    response or a fault. This is the simplest way of invoking Web services
+    and it also suites many business situations.</p>
+  </li>
+  <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
+    hence once a service invocation is called, the client application
+    immediately gets the control back and the response is retrieved using the
+    callback object provided. This approach provides the flexibility to the
+    client application to invoke several Web services simultaneously without
+    blocking the operation already invoked.</p>
+  </li>
+</ul>
+
+<p>Both these mechanisms work in the API level. Let's name the asynchronous
+behavior that we can get using the Non-Blocking API as <b>API Level
+Asynchrony.</b></p>
+
+<p>Both these mechanisms use single transport connections to send the request
+and to receive the response. They severely lag the capability of using two
+transport connections for the request and the response (either One-Way or
+Two-Way). So both these mechanisms fail to address the problem of long
+running transactions (the transport connection may time-out before the
+operation completes). A possible solution would be to use two separate
+transport connections for request and response. The asynchronous behavior
+that we gain using this solution can be called <b>Transport Level
+Asynchrony</b>.</p>
+
+<p>By <strong>combining API Level Asynchrony &amp; Transport Level
+Asynchrony</strong> we can obtain four different invocation patterns for Web
+services as shown in the following table.</p>
+<a name="table1"></a>
+
+<table width="100%" border="1" cellpadding="0" cellspacing="0">
+  <tbody>
+    <tr>
+      <td width="33%" height="19"><p><strong>API
+        (Blocking/Non-Blocking)</strong></p>
+      </td>
+      <td width="33%"><p><strong>Dual Transports (Yes/No)</strong></p>
+      </td>
+      <td width="33%"><p><strong>Description</strong></p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>The simplest and more familiar invocation pattern</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>No</p>
+      </td>
+      <td width="33%"><p>Using callbacks or polling</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is useful when the service operation is IN-OUT
+        in nature but the transport used is One-Way (e.g. SMTP)</p>
+      </td>
+    </tr>
+    <tr>
+      <td width="33%" height="19"><p>Non-Blocking</p>
+      </td>
+      <td width="33%"><p>Yes</p>
+      </td>
+      <td width="33%"><p>This is can be used to gain the maximum asynchronous
+        behavior. Non blocking in the API level and also in the transport
+        level</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<p>Axis2 provides the user with all these possibilities to invoke Web
+services.</p>
+
+<p>Following section present clients that use different possibilities
+presented above to invoke a Web Service using <code>ServiceClient</code>s.
+All samples mentioned in this guide are located at the <b><font
+color="#000000">"samples\userguide\src"</font></b> directory of the binary
+distribution.</p>
+
+<p>This section presents four types of clients.</p>
+<ol>
+  <li>Request-Response, Blocking Client</li>
+  <li>One Way Client</li>
+  <li>Request-Response, Non-Blocking that uses one transport connection</li>
+  <li>Request-Response, Non-Blocking that uses two transport connections</li>
+</ol>
+<a name="EchoBlockingClient"></a>
+
+<h4>Request-Response, Blocking Client</h4>
+
+<p>Axis2 provides the user with several invocation patterns for Web services,
+ranging from pure blocking single channel invocations to non-blocking dual
+channel invocations. Let's first see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest blocking invocation. The
+client code you need to write is as follows.</p>
+<source><pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+            <span style="color: rgb(36, 193, 19);">            
+            Options options = new Options();
+            options.setTo(targetEPR); // this sets the location of MyService service
+            
+            ServiceClient serviceClient = new ServiceClient();
+            serviceClient.setOptions(options);
+
+            OMElement result = serviceClient.sendReceive(payload);
+            </span>
+            System.out.println(result);
+
+        } catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+        } 
+}</pre>
+</source>
+<p>1. The lines highlighted in green lines show the set of operations that
+you need to perform in order to invoke a Web service.</p>
+
+<p>2. The rest is used to create the OMElement that needs to be sent and
+display the response OMElement.</p>
+
+<p>To test this client, use the provided ant build file that can be found in
+the "<strong>Axis2_HOME/samples/userguide</strong>" directory. Run the
+"run.client.blocking" target. If you can see the response OMElement printed
+in your command line, then you have successfully tested the client.</p>
+<a name="PingClient"></a>
+
+<h4>One Way Client</h4>
+
+<p>In the Web service "MyService" we had an IN-ONLY operation with the name
+"ping" (see <a href="adv-userguide.html#Web_Services_Using_Axis2">Creating a New Web Service</a>). Let's write a client to invoke this operation. The client
+code is as follows:</p>
+<pre> try {
+       OMElement payload = ClientUtil.getPingOMElement();
+       Options options = new Options();
+       options.setTo(targetEPR);
+       ServiceClient serviceClient = new ServiceClient();
+       serviceClient.setOptions(options);
+       serviceClient.fireAndForget(payload);
+        /**
+         * We have to block this thread untill we send the request , the problem
+         * is if we go out of the main thread , then request wont send ,so
+         * you have to wait some time :)
+         */
+       Thread.sleep(500);
+     } 
+catch (AxisFault axisFault) {
+            axisFault.printStackTrace();
+     }</pre>
+
+<p>Since we are accessing an IN-ONLY operation we can directly use the
+<code>fireAndForget()</code> in ServiceClient to invoke this operation. This
+will not block the invocation and will return the control immediately back to
+the client. You can test this client by running the target "run.client.ping"
+of the ant build file at "<strong>Axis2Home/samples/userguide</strong>".</p>
+
+<p>We have now invoked the two operations in our service. Are we done? No!
+There's a lot more to explore. Let's see some other ways to invoke the same
+operations.</p>
+<a name="EchoNonBlockingClient"></a>
+
+<h4>Request-Response, Non-Blocking that uses one transport connection</h4>
+
+<p>In the "EchoBlockingClient" once the
+<code>serviceClient.sendReceive(payload);</code> is called, the client is
+blocked till the operation is complete. This behavior is not desirable when
+there are many Web service invocations to be done in a single client
+application or within a GUI. A solution would be to use a Non-Blocking API to
+invoke Web services. Axis2 provides a callback based non-blocking API for
+users.</p>
+
+<p>A sample client for this can be found under
+"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
+the name "EchoNonBlockingClient". If we consider the changes that users may
+have to do with respect to the "EchoBlockingClient" that we have already
+seen, it will be as follows:</p>
+<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
+
+<p>The invocation accepts a callback object as a parameter. Axis2 client API
+provides an abstract Callback with the following methods:</p>
+<pre>public abstract void onComplete(AsyncResult result);
+public abstract void onError(Exception e);
+public boolean isComplete() {}</pre>
+
+<p>The user is expected to implement the "onComplete " and "onError " methods
+of their extended call back class. The Axis2 engine calls the "onComplete"
+method once the Web service response is received by the Axis2 Client API
+(ServiceClient). This will eliminate the blocking nature of the Web service
+invocation and provide users with the flexibility to use Non Blocking API for
+Web service Clients.</p>
+
+<p>To run the sample client ("EchoNonBlockingClient") you can simply use the
+<code>run.client.nonblocking</code> target of the ant file found at the
+"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
+<a name="EchoNonBlockingDualClient"></a>
+
+<h4>Request-Response, Non-Blocking that uses two transport connections</h4>
+
+<p>The solution provided by the Non-Blocking API has one limitation when it
+comes to Web service invocations which take a long time to complete. The
+limitation is due to the use of single transport connections to invoke the
+Web service and to retrieve the response. In other words, client API provides
+a non blocking invocation mechanism for users, but the request and the
+response come in a single transport (Two-Way transport) connection (like
+HTTP). Long running Web service invocations or Web service invocations using
+One-Way transports (like SMTP) cannot be utilized by simply using a non
+blocking invocation.</p>
+
+<p>The trivial solution is to use separate transport connections (either
+One-Way or Two-Way) for the request and response. The next problem that needs
+to be solved is the correlation (correlating the request and the response).
+<a href="http://www.w3.org/2002/ws/addr/" target="_blank">WS-Addressing</a>
+provides a neat solution to this using &lt;wsa:MessageID&gt; and
+&lt;wsa:RelatesTo&gt; headers. Axis2 provides support for addressing based
+correlation mechanism and a complying Client API to invoke Web services with
+two transport connections. (Core of Axis2 does not depend on WS-Addressing,
+but contains a set of parameters like in addressing that can be populated in
+any means. WS-Addressing is one of the uses that may populate them. Even the
+transports can populate these. Hence Axis2 has the flexibility to use
+different versions of addressing)</p>
+
+<p>Users can select between Blocking or Non-Blocking APIs for the Web service
+clients with two transport connections. By simply using a boolean flag, the
+same API can be used to invoke Web services (IN-OUT operations) using two
+separate transport connections. Let's see how it's done using an example.
+Following code fragment shows how to invoke the same "echo" operation using
+Non-Blocking API with two transport connections<strong>. The ultimate
+asynchrony!!</strong></p>
+<pre>  try {
+            OMElement payload = ClientUtil.getEchoOMElement();
+
+            Options options = new Options();
+            options.setTo(targetEPR);
+            options.setTransportInProtocol(Constants.TRANSPORT_HTTP);
+            options.setUseSeparateListener(true);
+            options.setAction("urn:echo");  // this is the action mapping we put within the service.xml
+
+            //Callback to handle the response
+            Callback callback = new Callback() {
+                public void onComplete(AsyncResult result) {
+                    System.out.println(result.getResponseEnvelope());
+                }
+
+                public void onError(Exception e) {
+                    e.printStackTrace();
+                }
+            };
+            //Non-Blocking Invocation            
+            sender = new ServiceClient();            
+            sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+            sender.setOptions(options);            
+            sender.sendReceiveNonBlocking(payload, callback);            
+            //Wait till the callback receives the response.            
+            while (!callback.isComplete()) {                
+             Thread.sleep(1000);            
+            }            
+            //Need to close the Client Side Listener.        
+            } catch (AxisFault axisFault) {            
+              axisFault.printStackTrace();
+            } catch (Exception ex) {
+              ex.printStackTrace();
+            } finally {
+            try {
+                sender.cleanup();
+            } catch (AxisFault axisFault) {
+                //have to ignore this
+            }
+        }</pre>
+
+<p>The boolean flag (value true) in the
+<b><code>options.setUseSeparateListener(...)</code></b> method informs the
+Axis2 engine to use separate transport connections for request and response.
+Finally <b><code>sender.cleanup()</code></b> informs the Axis2 engine to stop
+the client side listener started to retrieve the response.</p>
+
+<p>To run the sample client ("EchoNonBlockingDualClient") you can simply use
+the "run.client.nonblockingdual" target of the ant file found at the
+"<strong>Axis2_HOME/samples/userguide/</strong>" directory.</p>
+</body>
+</html>

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig01.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig01.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig01.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig02.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig02.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig02.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig03.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig03.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig03.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig04.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig04.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig04.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig05.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig05.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig05.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig06.jpg
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig06.jpg?view=auto&rev=488985
==============================================================================
Binary file - no diff available.

Propchange: webservices/axis2/branches/java/1_1/xdocs/1_1/images/fig06.jpg
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/installationguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/installationguide.html?view=diff&rev=488985&r1=488984&r2=488985
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/installationguide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/installationguide.html Wed Dec 20 01:04:27 2006
@@ -1,400 +1,400 @@
-<html>
-
-<head>
-    <meta http-equiv="content-type" content="">
-    <title>Axis2 Installation Guide</title>
-  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
-</head>
-
-<body lang="en">
-
-<h1 align="center">Apache Axis2 Installation Guide</h1>
-
-<p>This document will give you information on Axis2 distribution packages,
-    system prerequisites &amp; setting up environment variables and tools
-    followed by detailed instructions on installation methods.</p>
-
-<p><i>Send your feedback to: <a
-        href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
-    subject with [Axis2]. To subscribe to mailing list see <a
-        href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
-
-<h2>Contents</h2>
-<ul>
-    <li><a href="#Download_Axis2">Download Axis2</a></li>
-    <li><a href="#requirements">System Requirements</a></li>
-    <li><a href="#standalone">Installation Using Standard Binary Distribution</a>
-                <ul>
-                    <li><a href="#standalone1">Install the Apache Axis2 Binary Distribution</a></li>
-                    <li><a href="#standalone2">Starting up Axis2 Standalone Server</a></li>
-                    <li><a href="#standalone3">Building WAR File Using Standard Binary Distribution</a></li>
-                    <li><a href="#standalone4">Getting Familiar with the Axis2 Convenient Scripts</a></li>
-                </ul>
-    </li>
-    <li><a href="#build_war"></a></li>
-    <li><a href="#servlet_container">Installing Axis2 in a Servlet
-        Container</a></li>
-    <li><a href="#upload">Uploading Services</a></li>
-    <li><a href="#advanced">Advanced</a>
-        <ul>
-            <li><a href="#source">Axis2 Source Distribution</a>
-                <ul>
-                    <li><a href="#_Toc96698083">Setting up the Environment and
-                        Tools</a></li>
-                    <li><a href="#_Toc96698085">Building Axis2 Binaries and WAR file
-                        Using the Source Distribution</a></li>
-                </ul>
-            </li>
-        </ul>
-    </li>
-</ul>
-<a name="Download_Axis2"></a>
-
-<h2>Download Axis2</h2>
-
-<p>Axis2 is distributed in several convenient distribution packages and can
-    be installed either as a standalone server or as part of a J2EE compliant
-    servlet container. Axis2 is distributed under the Apache License, version
-    2.0. This Installation Guide will mainly focus on running Apache Axis2 using
-    the Standard Binary Distribution.</p>
-
-<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> distribution packages
-    of the Apache Axis2 1.1 version (latest).<p/>
-<p><a href="http://ws.apache.org/axis2/download.cgi">Download</a> distribution packages of all versions of Apache Axis2.</p>
-
-<p>The Distribution Packages Provided are as follows:</p>
-
-<a name="std-bin" id="std-bin"></a>
-<h3>1. Standard Binary Distribution</h3>
-
-<p>This is the complete version of Axis2 and include samples and convenient scripts as
-    well. 
-</p>
-
-<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Standard
-    Binary Distribution</p>
-<a name="war1"></a>
-
-<h3>2. WAR (Web Archive) Distribution</h3>
-
-<p>This will be the Web application of Axis2 which can be deployed in most of
-    the servlet containers.</p>
-
-<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> WAR (Web Archive)
-    Distribution</p>
-
-<h3>3. Documents Distribution</h3>
-
-<p>This will contain all the documentation in one package. The package
-    includes the xdocs and the Java API docs of this project.</p>
-
-<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Documents
-    Distribution</p>
-
-<h3>4. Source Distribution</h3>
-
-<p>This will contain the sources of Axis2 standard distribution, and is
-    mainly for the benefit of the advance users. One can generate a binary
-    distribution using the source by typing <span class="style1">$maven
-dist-bin. </span> You need to set up the Axis2 environment before
-    running this command. Step by step details on how to create the binary
-    distribution is available in the <a href="#advanced">Advanced</a> section.</p>
-
-<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Source
-    Distribution</p>
-
-<a name="requirements"></a>
-<h2>System Requirements</h2>
-
-<table border="2">
-    <caption></caption>
-    <tbody>
-        <tr>
-            <td>Java Development Kit (JDK)
-            </td>
-            <td>1.4 or later (For instructions on setting up the JDK in different operating systems,
-                visit
-                <a href="http://java.sun.com/">http://java.sun.com</a>)</td>
-        </tr>
-        <tr>
-            <td>Disk</td>
-            <td>Approximately 11 MB separately for standard binary distribution
-            </td>
-        </tr>
-        <tr>
-            <td>Operating system</td>
-            <td>Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu,
-                Gentoo</td>
-        </tr>
-        <tr>
-            <td><strong>Build Tool</strong>-<a href="http://ant.apache.org/">Apache Ant</a>  
-             <p>To run samples and to build war from Axis2 binary distribution.</p></td>
-            <td>Version 1.6.5 or higher(<a
-                    href="http://ant.apache.org/bindownload.cgi">download</a>).</td>
-        </tr>
-        <tr>
-            <td><strong>Build Tool</strong>- <a href="http://maven.apache.org/maven-1.x/">Apache
-                Maven 1.x</a>
-
-                <p>Required <em>only</em> for building Axis2 from Source
-                    Distribution</p>
-            </td>
-            <td>1.0.2 or higher in Maven 1.x series (<a
-                    href="http://maven.apache.org/maven-1.x/start/download.html">download</a>).
-                <strong>Please download maven 1.x version. Axis2 does not support maven 2.</strong></td>
-        </tr>
-    </tbody>
-</table>
-
-<a name="standalone"></a>
-<h2>Installation Using Standard Binary Distribution</h2>
-<a name="standalone1"></a>
-<h3>1. Download and Install the Apache Axis2 Binary Distribution</h3>
-<p> Download and install a Java Development Kit (JDK) release (version 1.4 or later) from <a href="http://java.sun.com/j2se/"
-> here .</a> Install the JDK according to the instructions included with the release.Set an environment 
-variable JAVA_HOME to the pathname of the directory into which you installed the JDK release.</p>
-
-<p>Download and unpack the <a
-        href="http://ws.apache.org/axis2/download/1_1/download.cgi">Axis2 Standard Binary Distribution</a>
-        into a convenient location so that the distribution resides in its own directory. Set an 
-        environment variables AXIS2_HOME to the pathname of the extracted directory of Axis2 (Eg: /opt/axis2-1.1).
-</p>
-<a name="standalone2"></a>
-<h3>2. Starting up Axis2 Standalone Server</h3>
-
-<p> Standalone Axis2 server can be started by executing the following commands: <br/>
-      $AXIS2_HOME\bin\axis2server.bat (Windows) <br/>
-      $AXIS2_HOME/bin/axis2server.sh  (Unix)
- <p>After startup, the default web services included with Axis2 will be
-available by visiting http://localhost:8080/axis2/services/</p>
-
-<a name="standalone3"></a>
-<h3>3. Building the Axis2 Web Application (axis2.war) Using Standard Binary Distribution</h3>
-<p> Download and install Apache Ant (version 1.6.5 or later) from <a href="http://ant.apache.org/bindownload.cgi"
-> here .</a> Install the Apache Ant according to the instructions included with the Ant release.</p>
-
-<p>Locate the ant build file (build.xml) inside the webapp directory which resides in your Axis2 home
- directory (i.e:- $AXIS_HOME/webapp)". Run the Ant build by executing "ant create.war" inside the $AXIS2_HOME/webapps folder. 
-You can find the generated axis2.war inside the $AXIS2_HOME/dist directory. All the services and modules that are present in the
-AXIS2_HOME/repository will be packed in to the created axis2.war together with the Axis2 configuration found
-at $AXIS2_HOME/conf/axis2.xml.</p>
-<p> You can read the <a href="#servlet_container">installing Axis2 in a servlet container</a> to figure 
-out how to deploy the Axis2 web application in a servlet container. </p>
-
-<a name="standalone4"></a>
-<h3>4. Getting Familiar with the Axis2 Convenient Scripts</h3>
-<p>It is advised to add the $AXIS2_HOME/bin to the PATH, so that you'll be able to run the following scripts from any where.</p>
-
-<table border="1">
-<tr>
-	<td><b>Script Name</b></td>
-	<td><b>Description</b></td>
-</tr>
-<tr>
-	<td>axis2.{bat|sh}</td>
-	<td>You can use this script to run web service clients written using Axis2.
-	This script calls the "java" command after adding the classpath for Axis2 dependent libraries (*.jar files present in your AXIS2_HOME/lib), 
-	setting the Axis2 repository location (AXIS2_HOME/repository) and setting the Axis2 configuration file location(AXIS2_HOME/conf/axis2.xml) for you. With this you can be relieved from setting all the above Axis2 specific parameters.<br/>
-	
-	<p><em>Usage : axis2.{sh.bat}  [-options] class [args...]</em></p>	    
-</td>
-</tr>
-<tr>
-	<td>axis2server.{sh|bat}</td>
-	<td>This script will start an standalone Axis2 server using the AXIS2_HOME/repository as the
-	 Axis2 repository and the AXIS2_HOME/conf/axis2.xml as the Axis2 configuration file.  This will start all the transport listeners listed in the AXIS2_HOME/conf/axis2.xml.
-	<p>As an example, if you want to deploy a service using standalone Axis2 server,then copy your 
-	service archive to the AXIS2_HOME/repository/services directory. After that go to the "Transport Ins" section of the AXIS2_HOME/conf/axis2.xml and configure the transport receivers (simpleHttpServer in port 8080 is listed by default). Then invoke this script.</p> </td>
-</tr>
-<tr>
-	<td>wsdl2java.{bat|sh}</td>
-	<td>This script generates java code according to a given WSDL file to handle Web service invocations 
-	(Client side Stubs). This script also has the ability to generate service skeletons according to the given WSDL.<br/>
-	<p><em>Usage:  WSDL2Java.{sh|bat} [OPTION]... -uri &lt;Location of WSDL> </em></p>
-	<p>Eg:  WSDL2Java.sh -uri ../wsdl/Axis2Sample.wsdl </p>
-	<p>A more detailed reference about this script can be found <a href="reference.html">here</a></p></td>	
-</tr>
-<tr>
-	<td>java2wsdl.{bat|sh} </td>
-	<td>This script generates the appropriate WSDL file for a given java class.<br/>
-	<em><p>Usage:  Java2WSDL.{sh|bat} [OPTION]... -cn &lt;fully qualified class name> </em></p>
-	<p>Eg:  Java2WSDL.sh -cn ../samples/test/searchTool.Search</p>
-	<p>A more detailed reference about this script can be found <a href="reference.html">here</a></p>
-	</td>
-</tr>
-</table>
-
-
-<a name="servlet_container"></a>
-<h2>Installing Axis2 in a Servlet Container</h2>
-<p>Which ever the distribution, installing Axis2 in a J2EE compliant servlet
-    container is as follows:</p>
-<ol>
-    <li>Build the Axis2 WAR
-        file using the Axis2 Standard Binary Distribution. (Alternatively you can
-         <a href="http://ws.apache.org/axis2/download/1_1/download.cgi">download</a> the axis2.war
-        or you can build axis2.war using the <a href="#war">Source
-        Distribution</a>.</li>
-    <li>Drop the war in the webapps folder of the servlet container. Most
-        servlet containers will automatically install war. (some servlet
-        containers may require a restart in order to capture the new web
-        application. Refer your servlet container documentation for more
-        information about this.)</li>
-    <li>Once the WAR is successfully installed, test it by pointing the web
-        browser to the <strong>http://&lt;host :port&gt;/axis2. </strong>It
-        should produce the following page which is the <strong>Axis2 Web
-        Application Home Page</strong>.</li>
-
-    <p align="center"><strong><img src="images/clip_image006.jpg"
-                                   alt=""></strong></p>
-    <li>Use the link "Validate" to ensure that everything is fine and smooth.
-        If the validation fails then the war has failed to install properly or
-        some essential jars are missing. At such a situation the documentation of
-        the particular servlet container should be consulted to find the problem.
-        The following page is a successful validation. Note the statement core
-        Axis2 libraries are present.</li>
-</ol>
-
-<p align="center"><img src="images/happyaxis.jpg"></p>
-<a name="upload"></a>
-
-<p><strong>Note:</strong> For any Application server specific installation
-    information please refer <a href="app_server.html">Application Server
-    Specific Configuration Guide</a>.</p>
-
-<h2>Uploading Services</h2>
-<ol>
-    <p>The Axis2 Web application also provides an interface to upload services.
-        Once a service is created according to the service specification as
-        described in <a name="userguide.html" target="_blank">User's Guide that jar
-        file can be uploaded using the upload page.</a></p>
-
-    <p align="center"><strong><img src="images/clip_image010.jpg"
-                                   alt=""></strong></p>
-
-    <p>The uploaded jar files will be stored in the default service directory.
-        For Axis2 this will be the &lt;webapps&gt;/axis2/WEB-INF/services
-        directory. Once a service is uploaded it will be installed instantly.</p>
-    <a name="hot_deployment"></a>
-    <p>Since Axis2 supports <strong>hot deployment</strong> one can drop the
-        service jar directly through the file system to the above mentioned
-        services directory. It will also cause the service to be automatically
-        installed without the container being restarted.</p>
-
-    <p>Use the 'Services' link on the Web Application home page to check the
-        successful installation of a service. The services and the operations of
-        successfully installed services will be displayed in the available services
-        page.</p>
-
-    <p align="center"><img src="images/clip_image012.jpg" alt=""></p>
-
-    <p></p>
-
-    <p>If the service has deployment time errors it will list those services as
-        faulty services. If you click on the link you can see the deployment fault
-        error message(s).</p>
-
-    <p align="center"><img src="images/faultservice.jpg" alt=""></p>
-
-    <p>Deployment time error message</p>
-
-    <p align="center"><strong><img src="images/faultmsg.jpg"
-                                   alt=""></strong></p>
-
-    <p></p>
-
-    <p>Axis2 Administration is all about configuring Axis2 at the run time and
-        the configuration will be transient. More descriptions are available in <a
-            href="webadminguide.html" target="_blank">Axis2 Web Administration
-        Guide</a></p>
-</ol>
-<a name="advanced"></a>
-<h2>Advanced</h2>
-<a name="source"></a>
-<h2>Axis2 Source Distribution</h2>
-<a name="_Toc96698083"></a>
-Using the Source Distribution both binary files (which is downloadable as the </a><a href="#std-bin">Standard Binary
-Distribution</a>) and axis2.war file (which is downloadable as the <a href="#war1">WAR distribution</a>) can be built using maven commands.
-
-<p>Required jar files do not come with the distribution and they will also
-    have to be built by running the maven command. Before we go any further it is
-    necessary to install <a href="http://maven.apache.org/maven-1.x/"
-                            target="_blank">Maven</aandsettheEnvironment.Thenextsectionwillguideyouhowtodojustthat.>
-</a></p>
-<a name="env-src"></a>
-<h3>Setting Up the Environment and Tools</h3>
-<a name="maven"></a>
-
-<h4>Maven</h4>
-
-<p>The Axis2 build is based on <a href="http://maven.apache.org/maven-1.x/"
-                                  target="_blank">Maven </a>. Hence the only prerequisite to build
-    Axis2 from
-    source distribution is to have Maven installed. Extensive instruction guides
-    are available at the Maven site. This guide however contains the easiest path
-    for quick environment setting. Advanced users who wish to know more about
-    Maven can visit <a href="http://maven.apache.org/maven-1.x/start/index.html"
-                       target="_blank">here </a>.</p>
-<ul>
-    <li>MS Windows</li>
-</ul>
-<ol>
-    <li>Download and run the Windows installer package for Maven.</li>
-    <li>Set the 'Environment Variables' ( create system variable MAVEN_HOME and
-        edit path. eg: "C:\Program Files\Apache Software Foundation\maven-1.0.2";
-        path %MAVEN_HOME%\bin)</li>
-    <li>Make sure that system variable JAVA_HOME is set to the location of your
-        JDK, eg. C:\Program Files\Java\jdk1.5.0_02</li>
-    <li>Run maven --version to verify that it is correctly installed.</li>
-</ol>
-
-<p align="center"><img alt="clip_image002 (15K)"
-                       src="images/clip_image002.jpg" height="211" width="477"></p>
-<ul>
-    <li>Unix based OS (Linux etc)</li>
-</ul>
-
-<p>The tar ball or the zip archive is the best option. Once the archive is
-    downloaded expand it to a directory of choice and set the environment
-    variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well. More
-    instructions for installing Maven in Unix based operating systems can be
-    found <a href="http://maven.apache.org/download.html#Installation"
-             target="_blank">here </a>.</p>
-
-<p>Once maven is properly installed you can start building Axis2.</p>
-
-<p><a href="../faq.html#d4">Maven commands that are frequently used</a> in
-    Axis2 are listed on the <a href="../faq.html">FAQs</a> page.</p>
-<a name="_Toc96698085"></a>
-
-<h3>Building Binaries and WAR File Using the Source Distribution</h3>
-
-<p>The Source Distribution is available as a zipped archive. All the
-    necessary build scripts are included with the source distribution. Once the
-    source archive is expanded into a directory of choice, moving to the
-    particular directory and running <code>maven</code> command will build the
-    Axis2 jar file.</p>
-
-<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg"><br
-        clear="all">
-</p>
-
-<p>Once the command completes, the binaries (jar files in this case) can be
-    found at a newly created "target" directory.</p>
-
-<p><strong>Note: For the first Maven build (if the maven repository is not
-    built first) it will take a while since required jars need to be downloaded.
-    However this is a once only process and will not affect any successive
-    builds.</strong></p>
-<a name="war"></a>
-
-<p><strong></strong>The default maven build will however build only the Axis2
-    jar file. To obtain a <strong>WAR (Web Archive)</strong>, <code>maven
-    war</code> command should be issued. This will create a complete WAR with the
-    name axis2.war inside the target directory.</p>
-
-<p>Once this build step is complete, the binaries are ready to be
-    deployed.</p>
-<a name="_Toc96698086"></a>
-</body>
-</html>
+<html>
+
+<head>
+    <meta http-equiv="content-type" content="">
+    <title>Axis2 Installation Guide</title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
+</head>
+
+<body lang="en">
+
+<h1 align="center">Apache Axis2 Installation Guide</h1>
+
+<p>This document will give you information on Axis2 distribution packages,
+    system prerequisites &amp; setting up environment variables and tools
+    followed by detailed instructions on installation methods.</p>
+
+<p><i>Send your feedback to: <a
+        href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>. Prefix
+    subject with [Axis2]. To subscribe to mailing list see <a
+        href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<h2>Contents</h2>
+<ul>
+    <li><a href="#Download_Axis2">Download Axis2</a></li>
+    <li><a href="#requirements">System Requirements</a></li>
+    <li><a href="#standalone">Installation Using Standard Binary Distribution</a>
+                <ul>
+                    <li><a href="#standalone1">Install the Apache Axis2 Binary Distribution</a></li>
+                    <li><a href="#standalone2">Starting up Axis2 Standalone Server</a></li>
+                    <li><a href="#standalone3">Building WAR File Using Standard Binary Distribution</a></li>
+                    <li><a href="#standalone4">Getting Familiar with the Axis2 Convenient Scripts</a></li>
+                </ul>
+    </li>
+    <li><a href="#build_war"></a></li>
+    <li><a href="#servlet_container">Installing Axis2 in a Servlet
+        Container</a></li>
+    <li><a href="#upload">Uploading Services</a></li>
+    <li><a href="#advanced">Advanced</a>
+        <ul>
+            <li><a href="#source">Axis2 Source Distribution</a>
+                <ul>
+                    <li><a href="#_Toc96698083">Setting up the Environment and
+                        Tools</a></li>
+                    <li><a href="#_Toc96698085">Building Axis2 Binaries and WAR file
+                        Using the Source Distribution</a></li>
+                </ul>
+            </li>
+        </ul>
+    </li>
+</ul>
+<a name="Download_Axis2"></a>
+
+<h2>Download Axis2</h2>
+
+<p>Axis2 is distributed in several convenient distribution packages and can
+    be installed either as a standalone server or as part of a J2EE compliant
+    servlet container. Axis2 is distributed under the Apache License, version
+    2.0. This Installation Guide will mainly focus on running Apache Axis2 using
+    the Standard Binary Distribution.</p>
+
+<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> distribution packages
+    of the Apache Axis2 1.1 version (latest).<p/>
+<p><a href="http://ws.apache.org/axis2/download.cgi">Download</a> distribution packages of all versions of Apache Axis2.</p>
+
+<p>The Distribution Packages Provided are as follows:</p>
+
+<a name="std-bin" id="std-bin"></a>
+<h3>1. Standard Binary Distribution</h3>
+
+<p>This is the complete version of Axis2 and include samples and convenient scripts as
+    well. 
+</p>
+
+<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Standard
+    Binary Distribution</p>
+<a name="war1"></a>
+
+<h3>2. WAR (Web Archive) Distribution</h3>
+
+<p>This will be the Web application of Axis2 which can be deployed in most of
+    the servlet containers.</p>
+
+<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> WAR (Web Archive)
+    Distribution</p>
+
+<h3>3. Documents Distribution</h3>
+
+<p>This will contain all the documentation in one package. The package
+    includes the xdocs and the Java API docs of this project.</p>
+
+<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Documents
+    Distribution</p>
+
+<h3>4. Source Distribution</h3>
+
+<p>This will contain the sources of Axis2 standard distribution, and is
+    mainly for the benefit of the advance users. One can generate a binary
+    distribution using the source by typing <span class="style1">$maven
+dist-bin. </span> You need to set up the Axis2 environment before
+    running this command. Step by step details on how to create the binary
+    distribution is available in the <a href="#advanced">Advanced</a> section.</p>
+
+<p><a href="http://ws.apache.org/axis2/download/1_1/download.cgi">Download</a> Source
+    Distribution</p>
+
+<a name="requirements"></a>
+<h2>System Requirements</h2>
+
+<table border="2">
+    <caption></caption>
+    <tbody>
+        <tr>
+            <td>Java Development Kit (JDK)
+            </td>
+            <td>1.4 or later (For instructions on setting up the JDK in different operating systems,
+                visit
+                <a href="http://java.sun.com/">http://java.sun.com</a>)</td>
+        </tr>
+        <tr>
+            <td>Disk</td>
+            <td>Approximately 11 MB separately for standard binary distribution
+            </td>
+        </tr>
+        <tr>
+            <td>Operating system</td>
+            <td>Tested on Windows XP, Linux, Mac OS X, Fedora core, Ubuntu,
+                Gentoo</td>
+        </tr>
+        <tr>
+            <td><strong>Build Tool</strong>-<a href="http://ant.apache.org/">Apache Ant</a>  
+             <p>To run samples and to build war from Axis2 binary distribution.</p></td>
+            <td>Version 1.6.5 or higher(<a
+                    href="http://ant.apache.org/bindownload.cgi">download</a>).</td>
+        </tr>
+        <tr>
+            <td><strong>Build Tool</strong>- <a href="http://maven.apache.org/maven-1.x/">Apache
+                Maven 1.x</a>
+
+                <p>Required <em>only</em> for building Axis2 from Source
+                    Distribution</p>
+            </td>
+            <td>1.0.2 or higher in Maven 1.x series (<a
+                    href="http://maven.apache.org/maven-1.x/start/download.html">download</a>).
+                <strong>Please download maven 1.x version. Axis2 does not support maven 2.</strong></td>
+        </tr>
+    </tbody>
+</table>
+
+<a name="standalone"></a>
+<h2>Installation Using Standard Binary Distribution</h2>
+<a name="standalone1"></a>
+<h3>1. Download and Install the Apache Axis2 Binary Distribution</h3>
+<p> Download and install a Java Development Kit (JDK) release (version 1.4 or later) from <a href="http://java.sun.com/j2se/"
+> here .</a> Install the JDK according to the instructions included with the release.Set an environment 
+variable JAVA_HOME to the pathname of the directory into which you installed the JDK release.</p>
+
+<p>Download and unpack the <a
+        href="http://ws.apache.org/axis2/download/1_1/download.cgi">Axis2 Standard Binary Distribution</a>
+        into a convenient location so that the distribution resides in its own directory. Set an 
+        environment variables AXIS2_HOME to the pathname of the extracted directory of Axis2 (Eg: /opt/axis2-1.1).
+</p>
+<a name="standalone2"></a>
+<h3>2. Starting up Axis2 Standalone Server</h3>
+
+<p> Standalone Axis2 server can be started by executing the following commands: <br/>
+      $AXIS2_HOME\bin\axis2server.bat (Windows) <br/>
+      $AXIS2_HOME/bin/axis2server.sh  (Unix)
+ <p>After startup, the default web services included with Axis2 will be
+available by visiting http://localhost:8080/axis2/services/</p>
+
+<a name="standalone3"></a>
+<h3>3. Building the Axis2 Web Application (axis2.war) Using Standard Binary Distribution</h3>
+<p> Download and install Apache Ant (version 1.6.5 or later) from <a href="http://ant.apache.org/bindownload.cgi"
+> here .</a> Install the Apache Ant according to the instructions included with the Ant release.</p>
+
+<p>Locate the ant build file (build.xml) inside the webapp directory which resides in your Axis2 home
+ directory (i.e:- $AXIS_HOME/webapp)". Run the Ant build by executing "ant create.war" inside the $AXIS2_HOME/webapps folder. 
+You can find the generated axis2.war inside the $AXIS2_HOME/dist directory. All the services and modules that are present in the
+AXIS2_HOME/repository will be packed in to the created axis2.war together with the Axis2 configuration found
+at $AXIS2_HOME/conf/axis2.xml.</p>
+<p> You can read the <a href="#servlet_container">installing Axis2 in a servlet container</a> to figure 
+out how to deploy the Axis2 web application in a servlet container. </p>
+
+<a name="standalone4"></a>
+<h3>4. Getting Familiar with the Axis2 Convenient Scripts</h3>
+<p>It is advised to add the $AXIS2_HOME/bin to the PATH, so that you'll be able to run the following scripts from any where.</p>
+
+<table border="1">
+<tr>
+	<td><b>Script Name</b></td>
+	<td><b>Description</b></td>
+</tr>
+<tr>
+	<td>axis2.{bat|sh}</td>
+	<td>You can use this script to run web service clients written using Axis2.
+	This script calls the "java" command after adding the classpath for Axis2 dependent libraries (*.jar files present in your AXIS2_HOME/lib), 
+	setting the Axis2 repository location (AXIS2_HOME/repository) and setting the Axis2 configuration file location(AXIS2_HOME/conf/axis2.xml) for you. With this you can be relieved from setting all the above Axis2 specific parameters.<br/>
+	
+	<p><em>Usage : axis2.{sh.bat}  [-options] class [args...]</em></p>	    
+</td>
+</tr>
+<tr>
+	<td>axis2server.{sh|bat}</td>
+	<td>This script will start an standalone Axis2 server using the AXIS2_HOME/repository as the
+	 Axis2 repository and the AXIS2_HOME/conf/axis2.xml as the Axis2 configuration file.  This will start all the transport listeners listed in the AXIS2_HOME/conf/axis2.xml.
+	<p>As an example, if you want to deploy a service using standalone Axis2 server,then copy your 
+	service archive to the AXIS2_HOME/repository/services directory. After that go to the "Transport Ins" section of the AXIS2_HOME/conf/axis2.xml and configure the transport receivers (simpleHttpServer in port 8080 is listed by default). Then invoke this script.</p> </td>
+</tr>
+<tr>
+	<td>wsdl2java.{bat|sh}</td>
+	<td>This script generates java code according to a given WSDL file to handle Web service invocations 
+	(Client side Stubs). This script also has the ability to generate service skeletons according to the given WSDL.<br/>
+	<p><em>Usage:  WSDL2Java.{sh|bat} [OPTION]... -uri &lt;Location of WSDL> </em></p>
+	<p>Eg:  WSDL2Java.sh -uri ../wsdl/Axis2Sample.wsdl </p>
+	<p>A more detailed reference about this script can be found <a href="reference.html">here</a></p></td>	
+</tr>
+<tr>
+	<td>java2wsdl.{bat|sh} </td>
+	<td>This script generates the appropriate WSDL file for a given java class.<br/>
+	<em><p>Usage:  Java2WSDL.{sh|bat} [OPTION]... -cn &lt;fully qualified class name> </em></p>
+	<p>Eg:  Java2WSDL.sh -cn ../samples/test/searchTool.Search</p>
+	<p>A more detailed reference about this script can be found <a href="reference.html">here</a></p>
+	</td>
+</tr>
+</table>
+
+
+<a name="servlet_container"></a>
+<h2>Installing Axis2 in a Servlet Container</h2>
+<p>Which ever the distribution, installing Axis2 in a J2EE compliant servlet
+    container is as follows:</p>
+<ol>
+    <li>Build the Axis2 WAR
+        file using the Axis2 Standard Binary Distribution. (Alternatively you can
+         <a href="http://ws.apache.org/axis2/download/1_1/download.cgi">download</a> the axis2.war
+        or you can build axis2.war using the <a href="#war">Source
+        Distribution</a>.</li>
+    <li>Drop the war in the webapps folder of the servlet container. Most
+        servlet containers will automatically install war. (some servlet
+        containers may require a restart in order to capture the new web
+        application. Refer your servlet container documentation for more
+        information about this.)</li>
+    <li>Once the WAR is successfully installed, test it by pointing the web
+        browser to the <strong>http://&lt;host :port&gt;/axis2. </strong>It
+        should produce the following page which is the <strong>Axis2 Web
+        Application Home Page</strong>.</li>
+
+    <p align="center"><strong><img src="images/clip_image006.jpg"
+                                   alt=""></strong></p>
+    <li>Use the link "Validate" to ensure that everything is fine and smooth.
+        If the validation fails then the war has failed to install properly or
+        some essential jars are missing. At such a situation the documentation of
+        the particular servlet container should be consulted to find the problem.
+        The following page is a successful validation. Note the statement core
+        Axis2 libraries are present.</li>
+</ol>
+
+<p align="center"><img src="images/happyaxis.jpg"></p>
+<a name="upload"></a>
+
+<p><strong>Note:</strong> For any Application server specific installation
+    information please refer <a href="app_server.html">Application Server
+    Specific Configuration Guide</a>.</p>
+
+<h2>Uploading Services</h2>
+<ol>
+    <p>The Axis2 Web application also provides an interface to upload services.
+        Once a service is created according to the service specification as
+        described in <a name="adv-userguide.html" target="_blank">Advance User's Guide</a> that jar
+        file can be uploaded using the upload page.</p>
+
+    <p align="center"><strong><img src="images/clip_image010.jpg"
+                                   alt=""></strong></p>
+
+    <p>The uploaded jar files will be stored in the default service directory.
+        For Axis2 this will be the &lt;webapps&gt;/axis2/WEB-INF/services
+        directory. Once a service is uploaded it will be installed instantly.</p>
+    <a name="hot_deployment"></a>
+    <p>Since Axis2 supports <strong>hot deployment</strong> one can drop the
+        service jar directly through the file system to the above mentioned
+        services directory. It will also cause the service to be automatically
+        installed without the container being restarted.</p>
+
+    <p>Use the 'Services' link on the Web Application home page to check the
+        successful installation of a service. The services and the operations of
+        successfully installed services will be displayed in the available services
+        page.</p>
+
+    <p align="center"><img src="images/clip_image012.jpg" alt=""></p>
+
+    <p></p>
+
+    <p>If the service has deployment time errors it will list those services as
+        faulty services. If you click on the link you can see the deployment fault
+        error message(s).</p>
+
+    <p align="center"><img src="images/faultservice.jpg" alt=""></p>
+
+    <p>Deployment time error message</p>
+
+    <p align="center"><strong><img src="images/faultmsg.jpg"
+                                   alt=""></strong></p>
+
+    <p></p>
+
+    <p>Axis2 Administration is all about configuring Axis2 at the run time and
+        the configuration will be transient. More descriptions are available in <a
+            href="webadminguide.html" target="_blank">Axis2 Web Administration
+        Guide</a></p>
+</ol>
+<a name="advanced"></a>
+<h2>Advanced</h2>
+<a name="source"></a>
+<h2>Axis2 Source Distribution</h2>
+<a name="_Toc96698083"></a>
+Using the Source Distribution both binary files (which is downloadable as the </a><a href="#std-bin">Standard Binary
+Distribution</a>) and axis2.war file (which is downloadable as the <a href="#war1">WAR distribution</a>) can be built using maven commands.
+
+<p>Required jar files do not come with the distribution and they will also
+    have to be built by running the maven command. Before we go any further it is
+    necessary to install <a href="http://maven.apache.org/maven-1.x/"
+                            target="_blank">Maven</aandsettheEnvironment.Thenextsectionwillguideyouhowtodojustthat.>
+</a></p>
+<a name="env-src"></a>
+<h3>Setting Up the Environment and Tools</h3>
+<a name="maven"></a>
+
+<h4>Maven</h4>
+
+<p>The Axis2 build is based on <a href="http://maven.apache.org/maven-1.x/"
+                                  target="_blank">Maven </a>. Hence the only prerequisite to build
+    Axis2 from
+    source distribution is to have Maven installed. Extensive instruction guides
+    are available at the Maven site. This guide however contains the easiest path
+    for quick environment setting. Advanced users who wish to know more about
+    Maven can visit <a href="http://maven.apache.org/maven-1.x/start/index.html"
+                       target="_blank">here </a>.</p>
+<ul>
+    <li>MS Windows</li>
+</ul>
+<ol>
+    <li>Download and run the Windows installer package for Maven.</li>
+    <li>Set the 'Environment Variables' ( create system variable MAVEN_HOME and
+        edit path. eg: "C:\Program Files\Apache Software Foundation\maven-1.0.2";
+        path %MAVEN_HOME%\bin)</li>
+    <li>Make sure that system variable JAVA_HOME is set to the location of your
+        JDK, eg. C:\Program Files\Java\jdk1.5.0_02</li>
+    <li>Run maven --version to verify that it is correctly installed.</li>
+</ol>
+
+<p align="center"><img alt="clip_image002 (15K)"
+                       src="images/clip_image002.jpg" height="211" width="477"></p>
+<ul>
+    <li>Unix based OS (Linux etc)</li>
+</ul>
+
+<p>The tar ball or the zip archive is the best option. Once the archive is
+    downloaded expand it to a directory of choice and set the environment
+    variable MAVEN_HOME and add MAVEN_HOME/bin to the path as well. More
+    instructions for installing Maven in Unix based operating systems can be
+    found <a href="http://maven.apache.org/download.html#Installation"
+             target="_blank">here </a>.</p>
+
+<p>Once maven is properly installed you can start building Axis2.</p>
+
+<p><a href="../faq.html#d4">Maven commands that are frequently used</a> in
+    Axis2 are listed on the <a href="../faq.html">FAQs</a> page.</p>
+<a name="_Toc96698085"></a>
+
+<h3>Building Binaries and WAR File Using the Source Distribution</h3>
+
+<p>The Source Distribution is available as a zipped archive. All the
+    necessary build scripts are included with the source distribution. Once the
+    source archive is expanded into a directory of choice, moving to the
+    particular directory and running <code>maven</code> command will build the
+    Axis2 jar file.</p>
+
+<p align="center"><img alt="clip_image004 (43K)" src="images/maven.jpg"><br
+        clear="all">
+</p>
+
+<p>Once the command completes, the binaries (jar files in this case) can be
+    found at a newly created "target" directory.</p>
+
+<p><strong>Note: For the first Maven build (if the maven repository is not
+    built first) it will take a while since required jars need to be downloaded.
+    However this is a once only process and will not affect any successive
+    builds.</strong></p>
+<a name="war"></a>
+
+<p><strong></strong>The default maven build will however build only the Axis2
+    jar file. To obtain a <strong>WAR (Web Archive)</strong>, <code>maven
+    war</code> command should be issued. This will create a complete WAR with the
+    name axis2.war inside the target directory.</p>
+
+<p>Once this build step is complete, the binaries are ready to be
+    deployed.</p>
+<a name="_Toc96698086"></a>
+</body>
+</html>



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


Mime
View raw message