You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ch...@apache.org on 2007/05/25 10:09:37 UTC
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...
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/adv-userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/adv-userguide.html?view=auto&rev=541579
==============================================================================
--- 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">
+<html>
+<head>
+ <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">
+</head>
+
+<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>
+
+<h2>Introduction</h2>
+
+<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
+href="mailto:axis-user@ws.apache.org?subject=[Axis2]">axis-user@ws.apache.org</a>".
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">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
+distribution</a>.</p>
+
+<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:
+<ol>
+ <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>
+</ol>
+<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="http://ws.apache.org/jaxme/">JaxMe data binding</a>)</p>
+<pre>wsdl2java.sh -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
+<strong>"samples/resources/schemaorg_apache_xmlbeans"</strong>
+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 -Axis2SampleDocLitServiceSkeleton.java- 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>
+<ol>
+ <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
+ <service-name>.aar</code> to create the archive.</li>
+</ol>
+
+<p>Once the archive is created, the content of the JAR should look like
+this.</p>
+
+<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
+border="0"></p>
+<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="http://tomcat.apache.org/">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>wsdl2java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl -d xmlbeans
+ -o ../samples/src -p org.apache.axis2.userguide</pre>
+</source>
+<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><service-name>Stub</strong>. In our example, it will be called
+"Axis2SampleDocLitServiceStub.java"</p>
+
+<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
+strategies.</p>
+
+<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
+comments.</p>
+<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>
+</source>
+<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<method-name></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>
+</source>
+<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"));
+stub._getServiceClient().getOptions().setUseSeparateListener(true);</pre>
+</source>
+<p>Once those options are set, Axis2 client does the following:</p>
+<ol>
+ <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>
+</ol>
+
+<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>
+</source>
+<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
+following:</p>
+<ol>
+ <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>
+</ol>
+
+<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 <module ref="addressing"/> 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 <module ref="addressing"/> 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 <module ref="addressing"/> inside an operation
+ tag of a service.xml file in a service archive</td>
+ </tr>
+ </tbody>
+</table>
+
+<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>
+<ol>
+ <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 <module
+ ref="addressing"/> 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
+ <module ref="addressing"/> to the axis2.xml file at the client side
+ or call
+ <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+ </li>
+</ol>
+<a name="advanced"></a>
+
+<h2>Advanced Topics</h2>
+
+<h3>Transports</h3>
+
+<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>
+<ol>
+ <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>
+</ol>
+
+<h3>Attachments</h3>
+
+<p>Axis2 provides attachment support using <a
+href="http://www.w3.org/TR/soap12-mtom/">MTOM</a>. Please refer to <a
+href="mtom-guide.html" target="_blank">MTOM with Axis2</a> for more
+information.</p>
+
+<h3>Security</h3>
+
+<p>Axis2 provides Security support using <a
+href="http://ws.apache.org/axis2/modules/rampart/1_0/security-module.html">Apache
+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>
+<ol>
+ <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>
+</ol>
+
+<h4>JiBX</h4>
+<a href="jibx/jibx-codegen-integration.html">JiBX Integration With Axis2</a>
+
+<h3>Other Topics</h3>
+<ol>
+ <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>
+</ol>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/app_server.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/app_server.html?view=auto&rev=541579
==============================================================================
--- 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"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html>
+<head>
+ <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 http://www.w3.org/Amaya/" />
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all" />
+</head>
+
+<body>
+<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
+href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a>.
+( Subscription details are available on the <a
+href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
+prefix subject with [Axis2].</p>
+<a></a>
+
+<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>
+<ul>
+ <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>
+</ul>
+NOTE: In both cases, please list one entry per line.
+
+<p>WebLogic ships with JARs that conflict with JARs present in Axis2.
+Therefore use <prefer-web-inf-classes> to ensure that JARs packaged in
+Axis2 WAR are picked up from WEB-INF/lib. You can do this by setting the
+<prefer-web-inf-classes> element in WEB-INF/weblogic.xml to true. An
+example of weblogic.xml is shown below:</p>
+<pre><weblogic-web-app>
+ <container-descriptor>
+ <prefer-web-inf-classes>true</prefer-web-inf-classes>
+ </container-descriptor>
+</weblogic-web-app></pre>
+
+<p>If set to true, the <prefer-web-inf-classes> 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
+information:</p>
+<ul>
+ <li><a
+ href="http://e-docs.bea.com/wls/docs81/programming/classloading.html">WebLogic
+ ServerApplication Classloading</a>- For more information on how
+ WebLogic's class loader works</li>
+ <li><a
+ href="http://e-docs.bea.com/wls/docs81/webapp/deployment.html">Redeploying
+ a Web Application in Exploded Directory Format</a></li>
+ <li><a
+ href="http://publib.boulder.ibm.com/infocenter/wsiihelp/v8r3/index.jsp?topic=/com.ibm.websphere.ii.product.ce.doc/configuring/iiyviigdepwebexpl.htm">Deploying
+ the Web application in exploded form</a></li>
+</ul>
+
+<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></p>
+
+<p>Adding the following to weblogic-application.xml should resolve the
+issue:</p>
+<pre><prefer-application-packages>
+<package-name>com.ctc.wstx.*</package-name>
+<package-name>javax.xml.*</package-name>
+<package-name>org.apache.*</package-name>
+</prefer-application-packages></pre>
+
+<p></p>
+
+<p>Note that the classes - Xerces, StAX API, Woodstox need to be on the
+application classpath</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/axis2config.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/axis2config.html?view=auto&rev=541579
==============================================================================
--- 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">
+<html>
+<head>
+ <meta http-equiv="content-type" content="">
+ <title>Axis2 Configuration Documents</title>
+ <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
+ media="all">
+</head>
+
+<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>
+
+<h2>Content</h2>
+<ul>
+ <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>
+</ul>
+<a name="Global_Configuration"></a>
+
+<h2>Global Configuration</h2>
+<ul>
+ <li>Writing axis2.xml</li>
+</ul>
+
+<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>
+<ul>
+ <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>
+</ul>
+<a name="Parameter"></a>
+
+<h3>Parameter</h3>
+
+<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>
+<source><pre>
+ <parameter name="name of the parameter" >parameter value </parameter></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>
+<pre>
+<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
+ <parameter name="port" >6060</parameter>
+ </transportReceiver>
+ </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>
+<pre>
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
+ </transportSender>
+ </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><phaseOrder type="InFlow">
+ <phase name="TransportIn"/>
+ .
+ .
+</phaseOrder> </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><phaseOrder type="InFlow">
+ <!-- Global phases -->
+ <phase name="Transport">
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher">
+ <order phase="Transport"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
+ <order phase="Transport"/>
+ </handler>
+ </phase>
+ <phase name="Security"/>
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.engine.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ </phase>
+ <!-- Global phases -->
+ <!-- After the Dispatch phase module author or service author can add any phase he wants -->
+ <phase name="OperationInPhase"/>
+ </phaseOrder>
+ <phaseOrder type="OutFlow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutPhase"/>
+ <!-- Global phases -->
+ <!-- these phases will run irrespective of the service -->
+ <phase name="MessageOut"/>
+ <phase name="PolicyDetermination"/>
+ </phaseOrder>
+ <phaseOrder type="InFaultFlow">
+ <phase name="PreDispatch"/>
+ <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.engine.AddressingBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher">
+ <order phase="Dispatch"/>
+ </handler>
+ </phase>
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationInFaultPhase"/>
+ </phaseOrder>
+ <phaseOrder type="OutFaultFlow">
+ <!-- user can add his own phases to this area -->
+ <phase name="OperationOutFaultPhase"/>
+ <phase name="PolicyDetermination"/>
+ <phase name="MessageOut"/>
+ </phaseOrder></pre>
+</source>
+<p><strong>type:</strong> the attribute represents the type of the flow. It
+can only be one of the following:</p>
+<ul>
+ <li>InFlow</li>
+ <li>OutFlow</li>
+ <li>InFaultFlow</li>
+ <li>OutFaultFlow</li>
+</ul>
+
+<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> <phase name="Transport"/></pre>
+</source>
+<p><strong>name:</strong> Name of the phase. <br>
+</p>
+
+<p>There are a number of things that one has to keep in mind when changing a
+phaseOrder:</p>
+
+<p>For the phaseOrder types <strong>"InFlow"</strong> and
+<strong>"InFaultFlow"</strong></p>
+<ul>
+ <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>
+</ul>
+
+<p>For the phaseOrder types <strong>"OutFlow"</strong> and
+<strong>"OutFaultFlow"</strong></p>
+<ul>
+ <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>
+</ul>
+<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><module ref="addressing"/> </pre>
+</source>
+<p><strong>ref:</strong> the module name which is going to be engaged, system
+wide.</p>
+<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>
+<ul>
+ <li>Deploying a Service</li>
+ <li>Removing a service</li>
+ <li>Activate/Inactivate Service</li>
+ <li>Module deploy</li>
+ <li>Module remove</li>
+</ul>
+
+<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><listener class="org.apache.axis2.ObserverIMPL">
+ <parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
+ </listener></pre>
+</source>
+<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>
+<ul>
+ <li><font>Writing services.xml</font></li>
+</ul>
+
+<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><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">
+ <description> The description of the service </description>
+
+ <transports>
+ <transport>HTTP</transport>
+ </transports>
+
+ <schema schemaNamespace="schema namespace"/>
+
+ <messageReceivers>
+ <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
+ class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
+ </messageReceivers>
+
+ <parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
+
+ <operation name="echoString" mep="operation MEP">
+ <actionMapping>Mapping to action</actionMapping>
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ </service></pre>
+</source>
+<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
+shutdowns.</p>
+
+<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
+MessageReceiver.</p>
+
+<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> <operation name="echoString">
+ <module ref=" a module name "/>
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation></pre>
+</source>
+<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>
+<ul>
+ <li>Writing module.xml</li>
+</ul>
+
+<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>
+
+<p>A very simple module.xml is shown below:</p>
+<pre><module class="org.apache.module.Module1Impl">
+ <InFlow>
+ .
+ .
+ </InFlow>
+ <OutFlow>
+ .
+ .
+ </OutFlow>
+
+ <OutFaultFlow>
+ .
+ .
+ </OutFaultFlow>
+
+ <InFaultFlow>
+ .
+ .
+ </InFaultFlow>
+
+ <operation name="creatSeq" mep="MEP_URI_IN_OUT">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ <parameter name="para1" locked="xsd:true">10</parameter>
+ </operation>
+</module></pre>
+</source>
+<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>
+<ul>
+ <li>InFlow</li>
+ <li>OutFlow</li>
+ <li>InFaultFlow</li>
+ <li>OutFaultFlow</li>
+</ul>
+
+<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><handler name="handler1" class="handlerClass ">
+ <order phase="userphase1" />
+ </handler></pre>
+</source>
+<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>
+<br>
+<i><b>Optional Attributes :</b></i><br>
+<b>phaseLast:</b> Indicates that the handler is the last handler of the
+phase.<br>
+<b>phaseFirst:</b> Indicate that the handler is the first handler of the
+phase.<br>
+<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>
+</p>
+
+<p><br>
+</p>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/contents.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/contents.html?view=auto&rev=541579
==============================================================================
--- 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"
+"http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <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">
+</head>
+
+<body lang="en">
+<h1>Apache Axis2/Java Version @axis2_version@ Documentation Index</h1>
+
+<h2>Introduction</h2>
+
+<p>Apache Axis2, the third generation Web services engine is more efficient,
+more modular and more XML-oriented than its predecessor <a
+href="http://ws.apache.org/axis/">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>
+<ul>
+ <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>
+</ul>
+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>
+<ul>
+ <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="http://ws.apache.org/commons/axiom/OMTutorial.html">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>
+</ul>
+
+<p><strong>Data Bindings:</strong></p>
+<ul>
+ <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>
+</ul>
+
+<p><strong>Transports:</strong></p>
+<ul>
+ <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>
+</ul>
+
+<p><strong>Axis2 Tools:</strong></p>
+<ul>
+ <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>
+</ul>
+
+<h2>Apache Axis2 Developers</h2>
+<ul>
+ <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="http://ws.apache.org/axis2/@axis2_version_dir@/api/index.html">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>
+</ul>
+
+<h2>References</h2>
+
+<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>
+</body>
+</html>
Added: webservices/axis2/trunk/java/xdocs/@axis2_version_dir@/dii.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/%40axis2_version_dir%40/dii.html?view=auto&rev=541579
==============================================================================
--- 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 @@
+<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 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>
+<ul>
+ <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>
+</ul>
+
+<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
+Asynchrony.</b></p>
+
+<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
+Asynchrony</b>.</p>
+
+<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>
+</table>
+
+<p>Axis2 provides the user with all these possibilities to invoke Web
+services.</p>
+
+<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>
+<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. 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();
+ }
+}</pre>
+</source>
+<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
+"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 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
+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 <wsa:MessageID> and
+<wsa:RelatesTo> 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
+response.</p>
+
+<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>
+</body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org