axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r541579 [3/18] - in /webservices/axis2/trunk/java/xdocs: ./ @axis2_version_dir@/ @axis2_version_dir@/adb/ @axis2_version_dir@/adb/images/ @axis2_version_dir@/images/ @axis2_version_dir@/images/archi-guide/ @axis2_version_dir@/images/usergui...
Date Fri, 25 May 2007 08:09:37 GMT
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html Fri May 25 01:09:03 2007
@@ -0,0 +1,518 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 Advanced User's Guide</title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+  media="all">
+<body dir="ltr" lang="en-US">
+<a name="_Toc96697849" id="_Toc96697849"></a>
+<h1 align="center">Apache Axis2 Advanced User's Guide</h1>
+<p>This guide will help you get started with Axis2, the next generation of
+Apache Axis! It gives a detail description on how to write Web services and
+Web service clients using Axis2, how to write custom modules, and how to use
+them with a Web service. Advanced Topics and Samples that are shipped with
+the binary distribution of Axis2, are also discussed.</p>
+<a name="Introduction"></a>
+<p>This user guide is written based on <a
+href="../download/@axis2_version_dir@/download.html/#std-bin">Axis2 Standard Binary
+Distribution</a>. The Standard Binary Distribution can be directly <a
+href="../download/@axis2_version_dir@/download.html/#std-bin">downloaded</a> or built using
+the <a href="../download/@axis2_version_dir@/download.html#src">Source Distribution</a>. If
+you choose the latter, then the <a href="installationguide.html">Installation
+Guide</a> will instruct you on how to build Axis2 Standard Binary
+Distribution using the source.</p>
+<p>Please note that Axis2 is an open-source effort. If you feel the code
+could use some new features or fixes, please get involved and lend us a hand!
+The Axis developer community welcomes your participation.</p>
+<p>Let us know what you think! Send your feedback to "<a
+(Subscription details are available on the <a
+href="">Axis2 site</a>.) Kindly
+prefix the subject of the mail with [Axis2].</p>
+<h2>Getting Started</h2>
+<p>The first two sections of the user guide explain how to write and deploy a
+new Web Service using Axis2, and how to write a Web Service client using
+Axis2. The next section - <a href="#config"> Configuring Axis2</a> - provides
+an introduction to important configuration options in Axis2. The final
+section - <a href="#advanced">Advanced Topics</a> - provides references to
+other features</p>
+<p>In this (first) section, we will learn how to write and deploy Web
+services using Axis2. All the samples mentioned in this guide are located in
+the <b>"samples/userguide/src"</b> directory of <a
+href="../download/@axis2_version_dir@/download.html/#std-bin">Axis2 standard binary
+<p>Please deploy axis2.war in your servlet container and ensure that it works
+fine. The <a href="installationguide.html" target="_blank">Installation
+Guide</a> gives you step-by-step instructions on just how to build axis2.war
+and deploy it in your servlet container.</p>
+<a name="ws_codegen"></a><a name="Web_Services_Using_Axis2"></a>
+<h2>Creating a New Web Service</h2>
+<p>If you are interested in how to write a Web Service client using Axis2, it
+is decribed under <a href="#client">Writing a Web Service Client</a>. Axis2
+provides two ways to create new Web Services, using <strong>code
+generation</strong> and using <strong>XML based primary APIs</strong>. The
+following section explains how to start from a WSDL, and create a new service
+with code generation. For the XML based primary API, please refer to the
+section <a href="xmlbased-server.html">Writing Web Services Using Axis2's
+Primary APIs</a> for more information. However, if you are a new user, it is
+better to follow the code generation approach first (given below)</p>
+<h3>Starting with WSDL, Creating and Deploying a Service</h3>
+<p>We start with a WSDL, however if you do not have a WSDL and need to create
+a WSDL from a java class, please use the <a
+href="reference.html#wsdl2java">Java2WSDL tool</a> and create a WSDL. As you
+might already know, a WSDL description of a service provides a precise
+definition of a Web Service. Axis2 can process the WSDL and generate java
+code that does most of the work for you. At the server side, we call them
+Skeletons, and at the client side, Stubs.</p>
+This method of writing a Web service with Axis2 involves four steps:
+  <li>Generate the skeleton code.</li>
+  <li>Add business logic.</li>
+  <li>Create a *.aar archive (Axis Archive) for the Web service.</li>
+  <li>Deploy the Web service.</li>
+<a name="Step1_:Generate_skeleton"></a>
+<h3>Step1: Generate Skeleton Code</h3>
+<p>To generate the skeleton and required classes, you can use the WSDL2Java
+tool provided in Axis2. This tool is located in the bin directory of the
+distribution and can be executed using the provided scripts (.bat or .sh).
+The tool's parameter list can be found in the <a
+href="reference.html#wsdl2code">Axis2 Reference Document</a>.</p>
+<p>The parameters for the wsdl2java tool in our example are as follows.
+Please note that we use xmlbeans as the data binding framework, and generated
+code will be sent to the samples directory. Other data binding tools you can
+use are adb (Axis data binding) and jaxme (<a
+href="">JaxMe data binding</a>)</p>
+<pre> -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans 
+-o ../samples -p org.apache.axis2.userguide</pre>
+<p>This will generate the required classes in the <b>"sample/src"</b>
+directory, and the schema classes in the
+directory<strong></strong>. Note that these are not source files and should
+be available in the class path in order to compile the generated classes.</p>
+<a name="Step2_Implement_Business_Logic"></a>
+<h3>Step 2: Implement Business Logic</h3>
+<p>Now you should fill the business logic in the skeleton class. You can find
+the skeleton class among the
+generated classes in the
+<strong>"samples/src/org/apache/axis2/userguide</strong> directory. Let's
+fill the <code>echoString(..)</code> method in the skeleton as shown below.
+Our sample WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong>
+directory has three operations: echoString, echoStringArray, echoStruct. To
+see how the others will look when they are filled up, see <a
+href="src/Axis2SampleDocLitServiceCode.html">Code Listing For
+Axis2SampleDocLitService Service</a></p>
+<source><pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument 
+    echoString(org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {
+    //Use the factory to create the output document.
+    org.apache.axis2.userguide.xsd.EchoStringReturnDocument retDoc = 
+           org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();
+    //send the string back.
+    retDoc.setEchoStringReturn(param4.getEchoStringParam());
+   return retDoc;<br></pre>
+</source><a name="Step4_Create_archive"></a>
+<h3>Step 3: Create Archive File</h3>
+<p>An Axis2 service must be bundled as a service archive. The next step is to
+package the classes in an .aar (axis2 archive) and deploy it in Axis2. There
+is an ant file generated with the code; it will generate the Axis2 service
+archive for you. However, if you do not want to use ant, you can create an
+archive with the following steps :</p>
+  <li>Compile the generated code.</li>
+  <li>Copy <strong>"resources/schemaorg_apache_xmlbeans</strong>" xmlbeans
+    classes to your class folder.</li>
+  <li>Among the generated files, there will be a services.xml file, which is
+    the deployment descriptor for Axis2 service.[<a
+    href="reference.html#servicedd">learn more about it</a>]. Copy the
+    resources/service.xml to META-INF/services.xml</li>
+  <p>(To write your own service.xml file, see the sub section in <a
+  href="xmlbased-server.html#Step2_:Write_the_services_xml_file">Writing Web
+  Services Using Axis2's Primary APIs</a> )</p>
+  <li>Create the archive using content of the class folder. Change the
+    directory to the class folder and run <code>jar -cf
+    &lt;service-name&gt;.aar</code> to create the archive.</li>
+<p>Once the archive is created, the content of the JAR should look like
+<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
+<a name="Step5_Deploy_web_service"></a>
+<h3>Step 4: Deploy Web Service</h3>
+<p>The service can be deployed by simply dropping the ".aar" file into the
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
+We recommend using <a href="">Apache Tomcat</a> as
+the servlet container. <strong>Please Note that the services directory is
+available only after axis2.war is exploded by Tomcat. However, the easiest
+way to do it is to start Tomcat after axis2.war is copied to the webapps
+directory</strong> (if you have not already started). Check the "Services"
+link on the <a href="http://localhost:8080/axis2/" target="_blank">Home page
+of Axis2 Web Application</a> (http://localhost:8080/axis2) and see whether
+the Axis2SampleDocLitService is displayed under the deployed services.</p>
+<p>We recommend using the exploded configuration to deploy Axis2 WAR in
+<strong>WebLogic and WebSphere</strong> application servers to support the
+hotupdate/ hotdeployment features in Axis2. See <a
+href="app_server.html#weblogic_websphere">Application Server Specific
+Configuration Guide</a> for details.</p>
+<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
+Service" tool in the Axis2 Web Application's Administration module. (See the
+<a href="webadminguide.html" target="_blank">Web Administration Guide</a> for
+more information)</p>
+<a name="client"></a>
+<h2>Writing a Web Service Client</h2>
+<p>Axis2 also provides a more complex, yet powerful XML based client API
+which is intended for advanced users. Read <a href="dii.html">Writing Web
+Service Clients Using Axis2's Primary APIs</a> to learn more about it.
+However, if you are a new user, we recommend using the <strong>code
+generation</strong> approach presented below.</p>
+<h3>Generate Stubs</h3>
+<p>Let's see how we could generate java code (Stub) to handle the client side
+Web Service invocation for you. This can be done by running the WSDL2Java
+tool using the following arguments</p>
+<source><pre> -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans 
+     -o ../samples/src -p org.apache.axis2.userguide</pre>
+<p>This will generate client side stubs and xmlbeans types for your types.
+The Stub class that you need to use will be of the form
+<strong>&lt;service-name&gt;Stub</strong>. In our example, it will be called
+<p>Axis2 clients can invoke Web Services both in a blocking and non-blocking
+manner. In a blocking invocation, the client waits till the service performs
+its task without proceeding to the next step. Normally, the client waits till
+the response to the particular request arrives. In a non-blocking invocation,
+the client proceeds to the next step immediately, and the responses (if any)
+are handled using a Callback mechanism. Please note that some explanations
+use the terms Synchronous and Asynchronous to describe the similar invocation
+<h3>Do a Blocking Invocation</h3>
+<p>The following code fragment shows the necessary code calling
+<code>echoString</code> operation of the
+<code>Axis2SampleDocLitService</code> that we have already deployed. The code
+is extremely simple to understand and the explanations are in the form of
+<source><pre>     try {
+               org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub 
+                  = new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+                    "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+                //Create the request document to be sent.
+                org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =
+                org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
+                reqDoc.setEchoStringParam("Axis2 Echo");
+                //invokes the Web service.
+                org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc = 
+                stub.echoString(reqDoc);
+                System.out.println(resDoc.getEchoStringReturn());
+               } catch (java.rmi.RemoteException e) {
+                  e.printStackTrace();
+              }</pre>
+<p>First argument of <code>Axis2SampleDocLitPortTypeStub</code> should be the
+Axis2 repository for the client. Here we use null to make the stub use
+default configurations. However, you can make Axis2 use your own repository
+by providing it here. You can find more information about this from the <a
+href="#config">Axis2 Configuration section</a>. You can find code to invoke
+other operations from <a href="src/Axis2SampleDocLitServiceCode.html">Code
+Listing For Axis2SampleDocLitService Service</a></p>
+<h3>Do a Non-Blocking Invocation</h3>
+<p>The stubs also include a method that allows you to do a non-blocking
+innovation. For each method in the Service, there will be a method
+<strong>start&lt;method-name&gt;</strong>. These methods accept a callback
+object, which would be called when the response is received. Sample code that
+does an asynchronous interaction is given below.</p>
+<source><pre>try {
+         org.apache.axis2.userguide.Axis2SampleDocLitServiceStub stub
+           = new org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,
+             "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
+             //implementing the callback online
+            org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler callback =
+            new org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler() {
+                    public void receiveResultechoString(
+                      org.apache.axis2.userguide.xsd.EchoStringReturnDocument resDoc) {
+                       System.out.println(resDoc.getEchoStringReturn());
+                       }
+            };
+        org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc = 
+          org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();
+           reqDoc.setEchoStringParam("Axis2 Echo");
+           stub.startechoString(reqDoc, callback);
+        } catch (java.rmi.RemoteException e) {
+          e.printStackTrace();
+       }</pre>
+<p>Even though the above code does a non-blocking invocation at the client
+API, the transport connection may still operate in a blocking fashion. For
+example, a single HTTP connection can be used to create a Web Service request
+and to get the response when a blocking invocation happens at the transport
+level. To perform a "true" non-blocking invocation in which two separate
+transport connections are used for the request and the response, please add
+the following code segment after creating the stub. It will force Axis2 to
+use two transport connections for the request and the response while the
+client uses a Callback to process the response.</p>
+<source><pre>stub._getServiceClient().engageModule(new QName("addressing"));
+<p>Once those options are set, Axis2 client does the following:</p>
+  <li>Starts a new Transport Listener(Server) at the client side.</li>
+  <li>Sets the address of the Transport Listener, as the ReplyTo
+    WS-Addressing Header of the request message</li>
+  <li>According to the WS-Addressing rules, the Server will process the
+    request message and send the response back to the ReplyTo address.</li>
+  <li>Client accepts the response, processes it and invokes the callback with
+    the response parameters.</li>
+<h3>Using Your Own Repository</h3>
+<p>You could use your own repository with Axis2 Client, code below shows how
+to do this.</p>
+<source><pre>String axis2Repo = ...
+String axis2xml = ...
+ConfigurationContext configContext =
+ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo, axis2xml);
+Service1Stub stub1 = new Service1Stub(configContext,...);
+//invoke Service1
+Service2Stub stub2 = new Service2Stub(configContext,...);
+//invoke Service2</pre>
+<p>Note by creating the <code>ConfigurationContext</code> outside and passing
+it to the stubs, you could make number of stubs to use same repository, thus
+saving the configuration loading overhead from each request.</p>
+<a name="config"></a>
+<h2>Configuring Axis2</h2>
+<h3>Axis2 Repository</h3>
+<p>Axis2 configuration is based on a repository and standard archive format.
+A repository is a directory in the file system, and it should have the
+  <li><strong>axis2.xml</strong>, the Axis2 global deployment descriptor in
+    conf/axis2.xml file</li>
+  <li><strong>services</strong> directory, which will have the service
+    archives</li>
+  <li><strong>modules</strong> directory (optional), which will have the
+    module archives</li>
+<p>Both services and modules will be identified and deployed once their
+archives are copied to the corresponding directories. At the server side,
+users should specify the repository folder at the time of starting the Axis2
+Server (e.g. HTTP or TCP). In Tomcat, <code>webapps/axis2/WEB-INF</code>
+folder acts as the repository. At the client side, binary distribution can
+itself be a repository. You can copy the conf directory which includes the
+axis2.xml file from the exploded axis2.war and edit it to change the global
+configurations repository.</p>
+<h3>Global Configurations</h3>
+<p>The Global configuration can be changed by editing the axis2.xml file,
+refer to the <a href="axis2config.html#Global_Configuration">Axis2
+Configuration Guide</a> for more information.</p>
+<h3>Add New Services</h3>
+<p>New services can be written either using WSDL based code generation as we
+did, or from scratch as explained in <a href="xmlbased-server.html">Writing
+Web Services Using Axis2's Primary APIs</a>.  Read <a
+href="xmlbased-server.html">Creating a Service from Scratch</a> for more
+information. Also refer to <a
+href="axis2config.html#Service_Configuration">Axis2 Configuration Guide</a>
+for a reference on <strong>services.xml</strong> file.</p>
+<h3 name="module_engage">Engaging Modules</h3>
+<p>Each module(.mar file) provides extensions to Axis2. A module can be
+deployed by copying it to the modules directory in the repository. Then it
+becomes available and can be engaged at a global, service or operation scope.
+Once engaged, it becomes active (adds handlers to the execution flow) at the
+respective scope. Please refer to <a href="Axis2ArchitectureGuide.html">Axis2
+architecture guide</a> for detailed explanation. The following table explains
+the semantics of scope, and how to engage modules in those scopes.</p>
+<table border="1">
+  <tbody>
+    <tr>
+      <th>Scope</th>
+      <th>Semantics</th>
+      <th>How to Engage</th>
+    </tr>
+    <tr>
+      <td>Global</td>
+      <td>Add handlers in the module to all the services. Addressing Handler
+        can be only engaged as global</td>
+      <td>By adding a &lt;module ref="addressing"/&gt; to the Axis2 xml file
+        or calling
+        <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+        at client side</td>
+    </tr>
+    <tr>
+      <td>Service</td>
+      <td>Add handlers in the module to a specific service</td>
+      <td>By adding a &lt;module ref="addressing"/&gt; to a service.xml file
+        in a service archive</td>
+    </tr>
+    <tr>
+      <td>Operation</td>
+      <td>Add handlers in the module to a specific operation</td>
+      <td>By adding a &lt;module ref="addressing"/&gt; inside an operation
+        tag of a service.xml file in a service archive</td>
+    </tr>
+  </tbody>
+<p>* If a handler is added to a service or an operation, it will be invoked
+for every request received by that service or operation</p>
+<p>Axis2 provides a number of built in Modules (such as <a
+href="">addressing</a>,<a href="">Security</a>, <a href="">WS-Reliable
+Messaging</a>), and they can be engaged as shown above. Please refer to each
+module on how to use and configure them. You can also <a
+href="modules.html">create your own modules with Axis2</a>. Also refer to <a
+href="axis2config.html#Global_Configuration">Axis2 Configuration Guide</a>
+for a reference on the module.xml file.</p>
+<h3>WS-Addressing Support</h3>
+<p>WS-Addressing support for Axis2 is implemented by the addressing module.
+To enable addressing, you need to engage the addressing module in both server
+and client sides.</p>
+  <li>To <strong>enable</strong> addressing at the server side, you need to
+    copy the addressing.mar file to the modules directory of the server's
+    axis2 repository. To engage the module, add a &lt;module
+    ref="addressing"/&gt; to axis2.xml. The <strong>Addressing module can be
+    engaged only at global level.</strong></li>
+  <li>To <strong>enable</strong> addressing at the client side, you should
+    add it to the repository and provide the repository as an argument to the
+    <a href="dii.html">ServiceClient</a> or <a href="#client">generated
+    stub</a> or have it in your classpath.</li>
+  <li>To <strong>engage</strong> the addressing module, you should either add
+    &lt;module ref="addressing"/&gt; to the axis2.xml file at the client side
+    or call
+    <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+  </li>
+<a name="advanced"></a>
+<h2>Advanced Topics</h2>
+<p>By default, Axis2 is configured to use HTTP as the transport. However,
+Axis2 supports HTTP, SMTP, TCP and JMS transports. You can also write your
+own transports, and deploy them by adding new transportReceiver or
+transportSender tags to axis2.xml. To learn how to configure and use
+different transports, please refer to the following documents.</p>
+  <li><a href="tcp-transport.html" target="_blank">TCP Transport</a></li>
+  <li><a href="mail-transport.html" target="_blank">Mail Transport</a></li>
+  <li><a href="http-transport.html" target="_blank">HTTP Transports</a></li>
+  <li><a href="jms-transport.html" target="_blank">JMS Transports</a></li>
+<p>Axis2 provides attachment support using <a
+href="">MTOM</a>. Please refer to <a
+href="mtom-guide.html" target="_blank">MTOM with Axis2</a> for more
+<p>Axis2 provides Security support using <a
+Rampart</a>. Please refer to <a
+href="../modules/wss4j/1_0/security-module.html" target="_blank">Securing
+SOAP Messages with Apache Rampart</a> for more information.</p>
+<h3>REST Web Service</h3>
+<p>Please refer to <a href="rest-ws.html" target="_blank">RESTful Web
+Services</a> for more information.</p>
+<h3>Pluggable Data Binding</h3>
+<p>Axis2 ships with Axis Data Binding(ADB) as the default data binding
+framework. However, data binding frameworks are pluggable to Axis2, and
+therefore you can use other data binding frameworks with Axis2. Please refer
+to the following documents for more information.</p>
+<h4>Axis2 Data Binding(ADB)</h4>
+  <li><a href="adb/adb-howto.html" target="_blank">Axis2 Databinding
+    Framework</a></li>
+  <li><a href="adb/adb-codegen-integration.html" target="_blank">ADB
+    Integration With Axis2</a></li>
+  <li><a href="adb/adb-advanced.html">Advanced Axis2 Databinding Framework
+    Features</a></li>
+  <li><a href="adb/adb-tweaking.html">ADB Tweaking Guide</a></li>
+<a href="jibx/jibx-codegen-integration.html">JiBX Integration With Axis2</a>
+<h3>Other Topics</h3>
+  <li><a href="spring.html" target="_blank">Axis2 Integration With The Spring
+    Framework</a></li>
+  <li><a href="WS_policy.html" target="_blank">Web Services Policy Support In
+    Axis2</a></li>
+  <li><a href="axis2config.html#Global_Configuration">Axis2 Configuration
+    Guide</a></li>
+  <li><a href="Axis2-rpc-support.html">Axis2 RPC Support</a></li>
+  <li><a href="migration.html">Migrating from Apache Axis 1.x to Axis
+  2</a></li>
+  <li><a href="modules.html">Writing your Own Axis2 Module</a></li>
+  <li><a href="soapmonitor-module.html">Using the SOAP Monitor</a></li>
+  <li><a href="xmlbased-server.html">Writing Web Services Using Axis2's
+    Primary APIs</a></li>
+  <li><a href="dii.html">Writing Web Service Clients Using Axis2's Primary
+    APIs</a></li>
+  <li><a href="app_server.html">Application Server Specific Configuration
+    Guide</a></li>

Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/app_server.html
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/app_server.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/app_server.html Fri May 25 01:09:03 2007
@@ -0,0 +1,97 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+       "">
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+  <title>Application Server Specific Configuration Guide</title>
+  <meta content="amaya 9.2.1, see" />
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+  media="all" />
+<h1>Application Server Specific Configuration Guide</h1>
+<p>This document provides configuration information required for your
+Application Server to run Apache Axis2 to its fullest potential.</p>
+<p>Send your feedback or questions to: <a
+( Subscription details are available on the <a
+href="">Axis2 site</a>.) Kindly
+prefix subject with [Axis2].</p>
+<h3>WebLogic/ WebSphere</h3>
+<p><strong>1. Use exploded configuration to deploy Axis2 WAR</strong></p>
+<p>We recommend using the exploded configuration to deploy Axis2 WAR in
+WebLogic and WebSphere application servers to support the hotupdate/
+hotdeployment features in Axis2. However, if you do want to deploy custom
+WARs, say in a clustering environment, you need to add two additional files
+into the WEB-INF named "services.list" and "modules.list" under the modules
+and services directory respectively.</p>
+  <li><b>WEB-INF/services/services.list</b> : should list all the services
+    (aar files) that you want to expose.</li>
+  <li><b>WEB-INF/modules/modules.list</b> : should list all the modules (mar
+    files) that you want to use.</li>
+NOTE: In both cases, please list one entry per line.
+<p>WebLogic ships with JARs that conflict with JARs present in Axis2.
+Therefore use &lt;prefer-web-inf-classes&gt; to ensure that JARs packaged in
+Axis2 WAR are picked up from WEB-INF/lib. You can do this by setting the
+&lt;prefer-web-inf-classes&gt; element in WEB-INF/weblogic.xml to true. An
+example of weblogic.xml is shown below:</p>
+ &lt;container-descriptor&gt;
+    &lt;prefer-web-inf-classes&gt;true&lt;/prefer-web-inf-classes&gt;
+  &lt;/container-descriptor&gt;
+<p>If set to true, the &lt;prefer-web-inf-classes&gt; element will force
+WebLogic's classloader to load classes located in the WEB-INF directory of a
+Web application in preference to application or system classes. This is a
+recommended approach since it only impacts a single Web module.</p>
+<p>Please refer to the following documents in WebLogic/ WebSphere for more
+  <li><a
+    href="">WebLogic
+    ServerApplication Classloading</a>- For more information on how
+    WebLogic's class loader works</li>
+  <li><a
+    href="">Redeploying
+    a Web Application in Exploded Directory Format</a></li>
+  <li><a
+    href="">Deploying
+    the Web application in exploded form</a></li>
+<p><strong>2. Lack of namespacing on serialised items</strong></p>
+<p>BEA WebLogic Server 9.0 comes with its own StAX implementation. This
+results in lack of namespacing on serialised items. In turn, WeLogic server
+(WLS) breaks with AXIOM on the WLS classpath. Hence a filtering classloader
+is required:</p>
+<p>Adding the following to weblogic-application.xml should resolve the
+<p>Note that the classes - Xerces, StAX API, Woodstox need to be on the
+application classpath</p>

Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/axis2config.html
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/axis2config.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/axis2config.html Fri May 25 01:09:03 2007
@@ -0,0 +1,459 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+  <meta http-equiv="content-type" content="">
+  <title>Axis2 Configuration Documents</title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+  media="all">
+<body lang="en">
+<h1>Axis2 Configuration Guide</h1>
+<p>In Axis2, there are three kinds of configuration files to configure the
+system. The first one is to configure the whole system (global
+configuration), the second one is to configure a service (service
+configuration), and the third one is to configure a module (module
+configuration). This document explains the above configurations in detail.</p>
+  <li><a href="#Global_Configuration">Global Configuration
+  (axis2.xml)</a></li>
+  <li><a href="#Service_Configuration">Service Configuration
+    (services.xml)</a></li>
+  <li><a href="#Module_Configuration">Module Configuration
+  (module.xml)</a></li>
+<a name="Global_Configuration"></a>
+<h2>Global Configuration</h2>
+  <li>Writing axis2.xml</li>
+<p>All the configurations that require starting Axis2 are obtained from
+axis2.xml. The way to specify them is extremely simple and easy. The document
+is all about the proper way of specifying the configurations in axis2.xml.
+There are six top level elements that can be seen in the configuration file
+and can be listed as follows:</p>
+  <li><a href="#Parameter">Parameter</a></li>
+  <li><a href="#Receiver">Transport Receiver</a></li>
+  <li><a href="#Sender">Transport Sender</a></li>
+  <li><a href="#Phase_Order">Phase Order</a></li>
+  <li><a href="#References">Module References</a></li>
+  <li><a href="#Listeners">Listeners (Observers)</a></li>
+<a name="Parameter"></a>
+<p>In Axis2, a parameter is nothing but a name value pair. Each and every top
+level parameter available in the axis2.xml (direct sub elements of the root
+element) will be transformed into properties in AxisConfiguration. Therefore,
+the top level parameters in the configuration document can be accessed via
+AxisConfiguration in the running system. The correct way of defining a
+parameter is shown below:</p>
+  &lt;parameter name="name of the parameter" &gt;parameter value &lt;/parameter&gt;</pre>
+</source><a name="Receiver"></a>
+<h3>Transport Receiver</h3>
+<p>Depending on the underlying transport on which Axis2 is going to run, you
+need to have different transport receivers. The way you add them to the
+system is as follows:</p>
+&lt;transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer"&gt;
+        &lt;parameter name="port" &gt;6060&lt;/parameter&gt;
+ &lt;/transportReceiver&gt; 
+ </pre>
+</source>The above elements show the way of defining transport receivers in
+axis2.xml. Here the name attribute of the 'transportReceiver' element is the
+name of the transport receiver. It can be HTTP, TCP, SMTP, CommonsHTTP etc,.
+When the system starts up or when you set the transport at the client side,
+you can use these transport names to load the appropriate transport. Class
+attribute is to specify actual java classes that implement required
+interfaces for the transport. Any transport can have zero or more parameters,
+and if there are any, those parameters can be accessed via the corresponding
+transport receiver. <a name="Sender"></a>
+<h3>Transport Sender</h3>
+<p>Just as the transport receivers, you can register transport senders in the
+system, and later at run time, the senders can be used to send the messages.
+For example, consider Axis2 running under Apache Tomcat. Then Axis2 can use
+TCP transport senders to send messages rather than HTTP. The method of
+specifying transport senders is as follows:</p>
+&lt;transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
+        &lt;parameter name="PROTOCOL" locked="xsd:false"&gt;HTTP/1.0&lt;/parameter&gt;
+ &lt;/transportSender&gt; 
+ </pre>
+<strong>name:</strong> Name of the transport (you can have HTTP and HHTP1 as
+the transport name)
+<p><strong>class:</strong> Implementation class of the corresponding
+transport. Just as the transport receivers, transport senders can have zero
+or more parameters, and if there are any, then it can be accessed via the
+corresponding transport sender.</p>
+<a name="Phase_Order"></a>
+<h3>Phase Order</h3>
+<p>Specifying the order of phases in the execution chain has to be done using
+the phase order element. It will look as follows:</p>
+<pre>&lt;phaseOrder type="InFlow"&gt;
+         &lt;phase name="TransportIn"/&gt;
+         .
+         .
+&lt;/phaseOrder&gt;   </pre>
+<p>The most interesting thing is that you can add handlers here as well. If
+you want to add a handler that should go into that phase, you can directly do
+that by adding a handler element into it. In addition to that, there is no
+hard coding work for the handler chain anywhere in Axis2 (at any Axis*). So
+all those configurations are also done in the phase order element. The
+complete configurations will look as follows: <source></p>
+<pre>&lt;phaseOrder type="InFlow"&gt;
+        &lt;!--   Global phases    --&gt;
+         &lt;phase name="Transport"&gt;
+            &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;
+                &lt;order phase="Transport"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;
+                &lt;order phase="Transport"/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;phase name="Security"/&gt;
+        &lt;phase name="PreDispatch"/&gt;
+        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
+            &lt;handler name="AddressingBasedDispatcher"
+                     class="org.apache.axis2.engine.AddressingBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--   Global phases   --&gt;
+        &lt;!--   After the Dispatch phase module author or service author can add any phase he wants    --&gt;
+        &lt;phase name="OperationInPhase"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="OutFlow"&gt;
+        &lt;!--   user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutPhase"/&gt;
+        &lt;!--  Global phases  --&gt;
+        &lt;!--  these phases will run irrespective of the service  --&gt;
+        &lt;phase name="MessageOut"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="InFaultFlow"&gt;
+        &lt;phase name="PreDispatch"/&gt;
+        &lt;phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"&gt;
+            &lt;handler name="RequestURIBasedDispatcher"
+                     class="org.apache.axis2.engine.RequestURIBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="SOAPActionBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPActionBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="AddressingBasedDispatcher"
+                     class="org.apache.axis2.engine.AddressingBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="SOAPMessageBodyBasedDispatcher"
+                     class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+            &lt;handler name="InstanceDispatcher"
+                     class="org.apache.axis2.engine.InstanceDispatcher"&gt;
+                &lt;order phase="Dispatch"/&gt;
+            &lt;/handler&gt;
+        &lt;/phase&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationInFaultPhase"/&gt;
+    &lt;/phaseOrder&gt;
+    &lt;phaseOrder type="OutFaultFlow"&gt;
+        &lt;!--      user can add his own phases to this area  --&gt;
+        &lt;phase name="OperationOutFaultPhase"/&gt;
+        &lt;phase name="PolicyDetermination"/&gt;
+        &lt;phase name="MessageOut"/&gt;
+    &lt;/phaseOrder&gt;</pre>
+<p><strong>type:</strong> the attribute represents the type of the flow. It
+can only be one of the following:</p>
+  <li>InFlow</li>
+  <li>OutFlow</li>
+  <li>InFaultFlow</li>
+  <li>OutFaultFlow</li>
+<p>In addition to that, the only child element that is allowed inside
+"phaseOrder" is the "phase" element which represents the available phases in
+the execution chain. The method of specifying phases inside "phaseOrder" is
+as follows:</p>
+<pre> &lt;phase name="Transport"/&gt;</pre>
+<p><strong>name:</strong> Name of the phase. <br>
+<p>There are a number of things that one has to keep in mind when changing a
+<p>For the phaseOrder types <strong>"InFlow"</strong> and
+  <li>All the phases that are above the "Dispatch" phase, including the
+    "Dispatch" phase, are known as "Global phases" . You can add any number
+    of new phases here and they will be considered global.</li>
+  <li>In these two phaseOrder types, the phases added after the "Dispatch"
+    phase are known as "Operation phases".</li>
+<p>For the phaseOrder types <strong>"OutFlow"</strong> and
+  <li>All the phases that are below the "MessageOut" phase, including the
+    "MessageOut" phase, are known as "Global phases". You can add new phases
+    according to your requirement.</li>
+  <li>The phases added before the "MessageOut" phase are known as "Operation
+    phases".</li>
+  <p><strong>Note :</strong> If you look closely at the default axis2.xml,
+  you will be able to clearly identify it.</p>
+<a name="References"></a>
+<h3>Module References</h3>
+<p>If you want to engage a module, system wide, you can do it by adding a top
+level module element in axis2.xml. It should look as follows:</p>
+<pre>&lt;module ref="addressing"/&gt;  </pre>
+<p><strong>ref:</strong> the module name which is going to be engaged, system
+<a name="Listeners"></a>
+<h3><strong>Listeners (Observers)</strong></h3>
+<p>In Axis2, AxisConfiguration is observable so that you can register
+observers into that. They will be automatically informed whenever a change
+occurs in AxisConfiguration. In the current implementation, the observers are
+informed of the following events:</p>
+  <li>Deploying a Service</li>
+  <li>Removing a service</li>
+  <li>Activate/Inactivate Service</li>
+  <li>Module deploy</li>
+  <li>Module remove</li>
+<p>Registering Observers is very useful for additional features such as RSS
+feed generation, which will provide service information to subscribers. The
+correct way of registering observers should as follows:</p>
+<pre>&lt;listener class="org.apache.axis2.ObserverIMPL"&gt;
+    &lt;parameter name="RSS_URL" &gt;;/parameter&gt;
+  &lt;/listener&gt;</pre>
+<p><strong>class:</strong> Represents an Implementation class of observer,
+and it should be noted that the Implementation class should implement
+AxisObserver interface, and the class has to be available in the classpath.
+<a name="Service_Configuration"></a></p>
+<h2><font>Service Configuration</font></h2>
+  <li><font>Writing services.xml</font></li>
+<p><font>The description of services are specified using services.xml. Each
+service archive file needs to have a services.xml in order to be a valid
+service and it should be available in the META-INF directory of the archive
+file. A very simple services.xml is shown below:</font></p>
+<source><pre>&lt;service name="name of the service" scope="name of the scope" class="full qualifide name the service lifecycle class"   targetNamespace="target namespase for the service"&gt;
+    &lt;description&gt; The description of the service  &lt;/description&gt;  
+    &lt;transports&gt; 
+       &lt;transport&gt;HTTP&lt;/transport&gt;
+    &lt;/transports&gt;
+    &lt;schema schemaNamespace="schema namespace"/&gt; 
+    &lt;messageReceivers&gt;
+            &lt;messageReceiver mep=""
+                             class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/&gt;
+    &lt;/messageReceivers&gt;
+     &lt;parameter name="ServiceClass" locked="xsd:false"&gt;org.apache.axis2.sample.echo.EchoImpl&lt;/parameter&gt;
+    &lt;operation name="echoString" mep="operation MEP"&gt; 
+        &lt;actionMapping&gt;Mapping to action&lt;/actionMapping&gt;
+        &lt;module ref=" a module name "/&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;
+  &lt;/service&gt;</pre>
+<p><strong>name</strong>: The service name will be the name of the archive
+file if the .aar file contains only one service, or else the name of the
+service will be the name given by the name attribute.</p>
+<p><strong>scope</strong>: (Optional Attribute) The time period during which
+runtime information of the deployed services will be available. Scope is of
+several types- "Application", "SOAPSession", "TransportSession", "Request".
+The default value (if you don't enter any value) will be "Request"</p>
+<p><strong>class</strong>: (Optional attribute) The full qualified name of
+the service lifecycle implementation class. ServiceLifeCycle class is usefull
+when you want to do some tasks when the system starts and when it
+<p><strong>targetNamespace</strong>: (Optional Attribute) Target name space
+of the service. This value will be used when generating the WSDL. If you do
+not specify this value, the value will be calculated from the package name of
+the service impl class.</p>
+<p><font><strong>description</strong>: (Optional) If you want to display any
+description about the service via Axis2 web-admin module, then the
+description can be specified here.</font></p>
+<p><strong>transports</strong> : (Optional) The transports to which the
+service is going to be exposed. If the transport element is not present, then
+the service will be exposed in all the transports available in the system.
+The transport child element specifies the transport prefix (the name of the
+transport specified in axis2.xml).</p>
+<p><b>parameters:</b> A services.xml can have any number of top level
+parameters and all the specified parameters will be transformed into service
+properties in the corresponding AxisService. There is a compulsory parameter
+in services.xml called ServiceClass that specifies the Java class, which
+performs the above transformation. This class is loaded by the
+<p><b>operations :</b> If the service impl class is Java, then all the public
+methods in that service will be exposed. If the user wants to override it, he
+has to add the "operation" tag and override it. In a non-Java scenario or if
+you do not have a service class, then all the operations the user wants to
+expose by the service has to be indicated in the services.xml. It is
+specified as follows:</p>
+<pre>    &lt;operation name="echoString"&gt;
+        &lt;module ref=" a module name "/&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+    &lt;/operation&gt;</pre>
+<p>The only compulsory attribute here is "name", which represents the
+operation name that is going to be exposed. Any operation can contain module
+references as well as any number of parameters. The most interesting thing is
+that you can register custom message receivers per operation. Then the
+registered message receiver will be the message receiver for the
+corresponding operation. If you do not specify the message receiver, then the
+default message receiver will perform the operation. <br>
+<a name="Module_Configuration"></a></p>
+<h2>Module Configuration</h2>
+  <li>Writing module.xml</li>
+<p>The description of the module is specified using the module.xml. Each
+module archive file needs to have a module.xml in order to be a valid module,
+and it should be available in the META-INF directory of the archive file. <br>
+<p>A very simple module.xml is shown below:</p>
+<pre>&lt;module class="org.apache.module.Module1Impl"&gt;
+    &lt;InFlow&gt;
+        .
+        .
+    &lt;/InFlow&gt;
+    &lt;OutFlow&gt;
+        .
+        .
+    &lt;/OutFlow&gt;
+    &lt;OutFaultFlow&gt;
+        .   
+        .
+    &lt;/OutFaultFlow&gt;
+    &lt;InFaultFlow&gt;
+        .         
+        .
+    &lt;/InFaultFlow&gt;
+    &lt;operation name="creatSeq" mep="MEP_URI_IN_OUT"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+        &lt;parameter name="para1" locked="xsd:true"&gt;10&lt;/parameter&gt;
+    &lt;/operation&gt;
+<p><strong>class:</strong> (Optional attribute) Indicates the module
+implementation class. A module may or may not contain a module implementation
+class since the module can also be a collection of handlers. If a module
+contains an implementation class that implements the
+org.apache.axis2.modules.Module interface at deployment, its
+<code>init();</code> method will be called.</p>
+<p><b>parameter:</b> A module can contain any number of parameters and all
+the listed parameters in the module.xml will be transformed into the
+corresponding AxisModule of the module.</p>
+<p><b>flow: </b>Defining of handlers in a module has to be done inside flows.
+There are four types of flows as listed below.</p>
+<p>You can add any number of handlers into a flow, and those handlers will be
+available in the corresponding chains at runtime, when they are engaged.</p>
+  <li>InFlow</li>
+  <li>OutFlow</li>
+  <li>InFaultFlow</li>
+  <li>OutFaultFlow</li>
+<p><b>operations: </b> If a module wants to add an operation when it is
+engaged into a service, it can be done by adding an operation tag in
+module.xml. The method of specifying the operation is the same as operation
+in services.xml.</p>
+<p><b>handler:</b> The Handler element consists of compulsory and optional
+attributes. The method of defining a handler will look as follows:</p>
+<pre>&lt;handler name="handler1" class="handlerClass "&gt;
+            &lt;order phase="userphase1" /&gt;
+ &lt;/handler&gt;</pre>
+<p><b><i>Compulsory Attributes</i></b> <br>
+<b>name:</b> Name of the handler.<br>
+<b>class:</b> Handler implementation class.<br>
+<b>phase:</b> Name of the phase that the handler should remain, in the
+execution chain. <br>
+<i><b>Optional Attributes :</b></i><br>
+<b>phaseLast:</b> Indicates that the handler is the last handler of the
+<b>phaseFirst:</b> Indicate that the handler is the first handler of the
+<b>before :</b> Indicates that the current handler should be invoked before
+the handler specified by the before handler<br>
+<b>after:</b> Indicates that the current handler should be invoked after the
+handler specified by the after handler<br>

Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/contents.html
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/contents.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/contents.html Fri May 25 01:09:03 2007
@@ -0,0 +1,254 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+  <title>Axis2/Java @axis2_version@ Documentation Home</title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+  media="all">
+<body lang="en">
+<h1>Apache Axis2/Java Version @axis2_version@ Documentation Index</h1>
+<p>Apache Axis2, the third generation Web services engine is more efficient,
+more modular and more XML-oriented than its predecessor <a
+href="">Apache Axis</a>. It is carefully designed
+to support the easy addition of plug-in modules that extend its functionality
+for features such as security and increased reliability.</p>
+<p>Apache Axis2 Version @axis2_version@ comes to you with performance
+improvements and bug fixes over the 1.1 release.</p>
+<p>This page will take you through the list of documents that we have in
+store for you.</p>
+<h2>Apache Axis2 User's Guide</h2>
+<p>You can get started with Axis2 with the assistance of the following
+documents. They will guide you through the Axis2 download, installation (both
+as a standalone Web services engine and as part of a J2EE compliant servlet
+container), and instructions on how to write Web services and Web services
+client using Apache Axis2.</p>
+  <li><a href="userguide.html#intro">Introduction</a>- Gives you an
+    introduction to what Axis2 is, the life cycle of a Web services message,
+    how Axis2 handles SOAP messages and also includes a basic description on
+    Axis2 distributions, and how Axis2 behaves as part of a Web application
+    or as a standalone client that is not part of a J2EE application.</li>
+  <li><a href="installationguide.html">Download and Installation</a>- Lists
+    the different distribution packages offered by Axis2 and gives in-depth
+    instructions on the installation of the standalone method and as part of
+    a J2EE servlet container.</li>
+  <li><a href="userguide-installingtesting.html">Testing Client Code</a> -
+    The best way to make sure that your system is running Axis2 is to install
+    and test both a service and a client. This document describes this
+    process in easy to understand steps.</li>
+  <li><a href="userguide-introtoservices.html">Introduction to Services</a> -
+    The term "Web services" can apply to a number of different ways of
+    sending information back and forth. However, this guide focuses on the
+    sending and receiving of SOAP messages and Message Exchange Patterns
+    (MEPs).</li>
+  <li><a href="userguide-creatingclients.html">Creating Clients from WSDL</a>
+    - When it comes to creating a Web service client, you can do it manually
+    as described in the next document. However, in most cases, you will have
+    a Web Service Description Language (WSDL) definition that describes the
+    messages that clients should send and expect to receive. Axis2 provides
+    several ways to use this definition to automatically generate a client.
+    This document explains how to create a client using WSDL definitions.</li>
+  <li><a href="userguide-buildingservices.html">Building Services from
+    Scratch</a> - Now that you know how to use Axis2 to generate clients from
+    WSDL as described in the document before, this document digs a little
+    deeper, showing you how to create services, and how to create both
+    services and clients "from scratch", so to speak.</li>
+  <li><a href="userguide-samples.html">Samples</a> - The Axis2 Standard
+    Distribution provides a number of samples you can use as a guide for
+    implementing specific features and capabilities. These services are
+    listed in this document along with basic introductions for each one.</li>
+  <li><a href="userguide-forfurtherstudy.html">For Further Study</a> - This
+    section lists resource documents for further study.
+    <ul>
+      <li><a href="pojoguide.html">POJO Web Services using Apache
+        Axis2</a>-This guide will show you how to create a Plain Old Java
+        Object (POJO) for deploying using Apache Axis2 on Apache Tomcat.
+        POJOs are fast to build and easy to maintain, which means you'll save
+        a lot of time building and debugging your code</li>
+      <li><a href="quickstartguide.html">Axis2 Quick Start Guide</a>-The
+        purpose of this guide is to get you started on creating services and
+        clients using Axis2 as quickly as possible. It demonstrates how to
+        create Web services using a variety of different technologies.</></li>
+    </ul>
+  </li>
+Also see our <a href="../faq.html">FAQ page</a> to answer those common
+questions in mind.
+<h2>How To</h2>
+<p>This section deals with more advanced topics including Axis2 support
+features such as Transports, Attachments, Pluggable Data Binding, Security,
+and REST Web services in detail.</p>
+  <li><a href="webadminguide.html">Web Administrator's Guide</a> - Detailed
+    instructions on the administration console of Axis2 Web application,
+    which provides run-time configuration of Axis2.</li>
+  <li><a href="migration.html">Migrating from Axis 1.x to Axis 2</a> -
+    Guiding Axis 1.x users in upgrading to Axis2</li>
+  <li><a href="app_server.html">Application Server Specific Configuration
+    Guide</a> - Provides extra configuration information required for
+    application servers to run Axis2 to its fullest potential</li>
+  <li><a href="">AXIOM
+    Tutorial</a>-An introduction to Axis2's Object Model</li>
+  <li><a href="rest-ws.html">REST Support</a>-Introduction on
+    Representational State Transfer</li>
+  <li><a href="Axis2-rpc-support.html">Axis2 RPC Support</a> - This document
+    talks about the Axis2's Remote Procedure Calls support in a set of easy
+    to understand implementation steps</li>
+  <li><a href="mtom-guide.html">MTOM Guide -Sending Binary Data with SOAP</a>
+    - Explains how to send binary data using the SOAP Message Transmission
+    Optimization Mechanism</li>
+  <li><a href="axis2config.html">Axis2 Configuration Guide</a> - Explains the
+    three configurations in Axis2: global, service, and module</li>
+  <li><a href="soapmonitor-module.html">SOAP Monitor How-to</a> - A guide on
+    the utilities used to monitor the SOAP messages that invoke Web services,
+    along with the results of those messages</li>
+  <li><a href="WS_policy.html">Web Services Policy Support In Axis2</a> -
+    Introduction to the role of Web services policy in Axis2</li>
+  <li><a href="spring.html">Spring Framework</a> - A guide on how to use
+    Axis2 with the Spring Framework</li>
+  <li><a href="json_support.html">JSON Support</a> - This document explains
+    how to use JSON support implementation in Axis2. Includes details on test
+    cases and samples</li>
+  <li><a href="ejb-provider.html">Guide to using EJB Provider in Axis2</a> -
+    This guide explains how to use an EJB provider in Axis2 using an
+  example</li>
+<p><strong>Data Bindings:</strong></p>
+  <li><a href="adb/adb-howto.html">ADB How-to</a> - A guide on the Axis2
+    Databinding Framework (ADB)</li>
+  <li><a href="adb/adb-advanced.html">Advanced ADB Framework Features</a> -
+    Provides an insight into the newly added advanced features of ADB</li>
+  <li><a href="adb/adb-tweaking.html">Tweaking the ADB Code Generator</a> -
+    Explains the available mechanisms to extend ADB</li>
+  <li><a href="adb/adb-codegen-integration.html">ADB Integration with
+    Axis2</a> - A guide to writing an extension using the integrator in order
+    to integrate ADB with Axis2</li>
+  <li><a href="jibx/jibx-codegen-integration.html">JiBX Integration With
+    Axis2</a> - A guide to using JiBX with Axis2 in order to expose existing
+    Java code as a Web service and to implement a client for an existing Web
+    service</li>
+  <li><a href="tcp-transport.html">TCP Transport</a> - A guide to sending and
+    receiving SOAP messages via TCP in Axis2</li>
+  <li><a href="mail-transport.html">Mail Transport</a> - Explains how to
+    invoke a service using a Mail transport</li>
+  <li><a href="mail-configuration.html">Mail Transport Configuration</a> - A
+    guide to configuring Axis2 in order to get mail transport working</li>
+  <li><a>HTTP Transports</a> - A description on HTTP sender and HTTP receiver
+    in Axis2</li>
+  <li><a href="jms-transport.html">JMS Transport</a> - A description on JMS
+    sender and JMS receiver in Axis2</li>
+  <li><a href="transport_howto.html">Write Your Own Axis2 Transport</a> - A
+    quick and easy guide to create your own Axis2 Transport protocol</li>
+<p><strong>Axis2 Tools:</strong></p>
+  <li><a href="../tools/@axis2_version_dir@/CodegenToolReference.html">Code
+    Generator Tool Guide for Command Line and Ant Tasks</a> - Lists command
+    line and Ant task references. How to build a file using custom Ant tasks
+    and how to invoke a Code Generator from Ant</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/eclipse/wsdl2java-plugin.html">Code
+    Generator Wizard Guide for Eclipse Plug-in</a> - Explains the usage of
+    the code generator Eclipse plug-in for WSDL2Java and/or Java2WSDL
+    operations</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/eclipse/servicearchiver-plugin.html">Service
+    Archive Generator Wizard Guide for Eclipse Plug-in</a> - Describes the
+    functionality of the Eclipse plugin service archive generator tool</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/idea/Idea_plug-in_userguide.html">Code
+    Generator Wizard Guide for IntelliJ IDEA Plug-in</a> - A guide on the
+    usage of the IDEA code generation plug-in to create service archives and
+    generate Java class files from WSDL files</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/maven-plugins/maven-aar-plugin.html">Maven2
+    AAR Plug-in Guide</a> - A guide to generate an Axis 2 service file (AAR
+    file) using the Maven plug-in.</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/maven-plugins/maven-java2wsdl-plugin.html">Maven2
+    Java2WSDL Plug-in Guide</a> - A guide to using Java2WSDL Maven 2 Plug-in
+    that takes a Java class as input and generates a WSDL, which describes a
+    Web service for invoking the class methods</li>
+  <li><a
+    href="../tools/@axis2_version_dir@/maven-plugins/maven-wsdl2code-plugin.html">Maven2
+    WSDL2Code Plug-in Guide</a> - A guide to using this plugin that takes as
+    input a WSDL and generates client and server stubs for calling or
+    implementing a Web service matching the WSDL.</li>
+<h2>Apache Axis2 Developers</h2>
+  <li><a href="adv-userguide.html">Advanced User's Guide</a> - A quick start
+    user's guide for more experienced users and developers on how to install,
+    create Web services and Web service clients using Axis2.
+    <ul>
+      <li><a href="adv-userguide.html#introduction">Introduction</a> -
+        Outlines the overall direction of the user guide, with a high level
+        introduction on Axis2</li>
+      <li><a href="installationguide.html">Download and Installation</a> -
+        Lists the different distribution packages offered by Axis2, and the
+        installations for the standalone and as part of a J2EE servlet
+        container methods.</li>
+      <li><a href="adv-userguide.html#ws_codegen">Creating a new Web Service
+        with Code Generation</a> - Axis2 provides two ways to create new Web
+        Services: using code generation and XML based primary APIs. This
+        section explains how to start from a WSDL, and create a new Service
+        with code generation</li>
+      <li><a href="xmlbased-server.html">Writing Web Services Using Axis2's
+        Primary APIs</a> - Explains how to create new Web Services using XML
+        based primary APIs</li>
+      <li><a href="adv-userguide.html#client">Writing a Web Service Client
+        with Code Generation </a>- Axis2 also provides a more complex, yet
+        powerful XML based client API that is intended for advanced users.
+        However, if you are a new user we recommend using the code generation
+        approach presented below</li>
+      <li><a href="dii.html">Writing Web Service Clients Using Axis2's
+        Primary APIs</a> - This section presents complex yet powerful XML
+        based client APIs, which is intended for advanced users to write Web
+        services clients</li>
+      <li><a href="adv-userguide.html#config">Configuring Axis2</a> - Axis2
+        configuration is based on a repository and standard archive formats.
+        Here you will find details on how to configure Axis2. You will also
+        find reference documents that lead to greater detail in this
+      area.</li>
+    </ul>
+  </li>
+  <li><a href="Axis2ArchitectureGuide.html">Axis2 Architecture Guide</a> -
+    Introduction to Axis2's modular architecture</li>
+  <!--<li><a href="api/index.html">Online Java Docs</a>-Java API
+  documentation</li>-->
+  <li><a
+    href="">Online
+    Java Docs</a> - Java API documentation</li>
+  <li><a href="../refLib.html">Reference Library</a> - This document provides
+    additional information to developers on WS-* specifications, Java
+    language specifications, Subversion (SVN) control etc.</li>
+<p>Gives you a list of published articles, tutorials and Questions-Answers on
+Apache Axis2. <a href="../articles.html">Check them out</a> for that extra
+knowledge on the next generation Web services engine Apache Axis2. Be
+Informed and up-to-date!</p>

Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html
--- webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html (added)
+++ webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html Fri May 25 01:09:03 2007
@@ -0,0 +1,329 @@
+  <meta http-equiv="content-type" content="">
+  <title></title>
+  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+  media="all">
+<a name="Web_Service_Clients_Using_Axis2"></a>
+<h1>Writing Web Service Clients Using Axis2's Primary APIs</h1>
+<p>This section presents a 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, quick 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 Blocking and Non-Blocking
+client APIs.</p>
+  <li><p style="margin-bottom: 0in"><b>Blocking API</b> - Once the service
+    invocation is called, the client application hangs and only regains
+    control 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 regains control and the response is retrieved using the
+    callback object provided. This approach provides flexibility to the
+    client application to invoke several Web services simultaneously without
+    blocking the operation already invoked.</p>
+  </li>
+<p>Both mechanisms work at the API level. Let's name the asynchronous
+behavior that we can get using the Non-Blocking API as <b>API Level
+<p>Both 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
+<p>By <strong>combining API Level Asynchrony and 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 at the API level and also at the transport
+        level.</p>
+      </td>
+    </tr>
+  </tbody>
+<p>Axis2 provides the user with all these possibilities to invoke Web
+<p>The following section presents clients that use the different
+possibilities presented above to invoke a Web Service using
+<code>ServiceClient</code>s. All the 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>
+  <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>
+<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. First let us see how we can write a client to invoke the
+"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();
+        } 
+<p>1. The lines highlighted in green 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 the 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
+"" of the Ant build file at
+<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
+<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
+<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 in 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 that take a long time to complete. The
+limitation is due to the use of single transport connections to invoke the
+Web service and 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
+<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="" 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 an addressing based
+correlation mechanism and a complying Client API to invoke Web services with
+two transport connections. (The core of Axis2 does not depend on
+WS-Addressing, but contains a set of parameters, like in addressing, that can
+be populated by any method. WS-Addressing is one of the uses that may
+populate them. Even the transports can populate them. Hence, Axis2 has the
+flexibility to use different versions of addressing)</p>
+<p>Users can select between Blocking and 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. The 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 the request and
+response. Finally <b><code>sender.cleanup()</code></b> informs the Axis2
+engine to stop the client side listener, which started to retrieve the
+<p>To run the sample client ("EchoNonBlockingDualClient") you can simply use
+the "run.client.nonblockingdual" target of the Ant file found in the
+"<strong>Axis2_HOME/samples/userguide/</strong>" directory.</p>

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message