axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cha...@apache.org
Subject svn commit: r463189 - /webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
Date Thu, 12 Oct 2006 11:08:00 GMT
Author: chatra
Date: Thu Oct 12 04:07:59 2006
New Revision: 463189

URL: http://svn.apache.org/viewvc?view=rev&rev=463189
Log:
reviewed and committed jira AXIS2-1353. Thanks saliya

Modified:
    webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html

Modified: webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html?view=diff&rev=463189&r1=463188&r2=463189
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html (original)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/userguide.html Thu Oct 12 04:07:59 2006
@@ -4,374 +4,404 @@
   <meta http-equiv="content-type" content="">
   <title>Axis2 User's Guide</title>
 </head>
-
-<body lang="en-US" dir="ltr">
-<h1 align="center"><a name="_Toc96697849" id="_Toc96697849">Apache</a>
Axis2
+<body dir="ltr" lang="en-US">
+<h1 align="center"><a name="_Toc96697849" id="_Toc96697849">Apache</a>
+Axis2
 User's Guide</h1>
-
-<p>This guide will help you get started with Axis2, the next generation of
+<p>This guide will help you get started with Axis2, the next generation
+of
 Apache Axis! It describes in details 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 which are shipped with the
+service clients using Axis2; how to write custom modules and how to use
+them
+with a Web service. Advanced Topics and Samples which are shipped with
+the
 binary distribution of Axis2, are also discussed.</p>
 <h2><a name="Introduction">Introduction</a></h2>
-
 <p>This User's Guide is written based on <a
-href="../download/1_1/download.html/#std-bin">Axis2 standard binary
+ href="../download/1_1/download.html/#std-bin">Axis2 standard binary
 distribution</a>. The standard binary distribution can be directly <a
-href="[preferred]/ws/axis2/1_1/axis2-std-1.1-bin.zip"
-title="[preferred]/ws/axis2/1_1/axis2-std-1.1-bin.zip">downloaded</a> or
-built using the <a href="../download/1_1/download.html#src">standard source
+ href="%5Bpreferred%5D/ws/axis2/1_1/axis2-std-1.1-bin.zip"
+ title="[preferred]/ws/axis2/1_1/axis2-std-1.1-bin.zip">downloaded</a>
+or
+built using the <a href="../download/1_1/download.html#src">standard
+source
 distribution</a>. If you choose to go for the latter, then <a
-href="installationguide.html">Installation Guide</a> will instruct you on how
+ href="installationguide.html">Installation Guide</a> will instruct you
+on how
 to build Axis2 Standard Binary Distribution using the Source.</p>
-
-<p>We hope you enjoy using Axis2. Please note that this is an open-source
-effort. If you feel the code could use some new features or fixes, please get
+<p>We hope you enjoy using Axis2. Please note that this is an
+open-source
+effort. If you feel the code could use some new features or fixes,
+please get
 involved and lend us a hand! The Axis developer community welcomes your
 participation.</p>
-
 <p>Let us know what you think! Send your feedback on Axis2 to "<a
-href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>". Make sure
+ href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a>".
+Make sure
 to prefix the subject of the mail with [Axis2].</p>
-
 <h2><a name="Web_Services_Using_Axis2">Getting Started</a></h2>
-
-
-<p>First two sections of the user guide will walk you through writing and deploying
a new Web Service using Axis2, and writing a Web Service client using Axis2. Next section
- <a href="#config"> Configuring Axis2</a> - provides a introduction to important
configuration options in Axis2. Final section - <a href="#advanced">Advanced Topics</a>
- provides references for other features</p>
-
-<p>In this section, we will learn how to write and deploy Web services using
+<p>First two sections of the user guide will walk you through writing
+and deploying a new Web Service using Axis2, and writing a Web Service
+client using Axis2. Next section - <a href="#config"> Configuring Axis2</a>
+- provides a introduction to important configuration options in Axis2.
+Final section - <a href="#advanced">Advanced Topics</a> - provides
+references for other features</p>
+<p>In this 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/1_1/download.html/#std-bin">Axis2 standard binary
+ href="../download/1_1/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. <a href="installationguide.html" target="_blank">Installation Guide</a>
-gives you step by step instructions on just how to build axis2.war and deploy
+<p>Please deploy axis2.war in your servlet container and ensure that it
+works
+fine. <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>
-
 <h2> Creating a new Web Service</h2>
-
-<p>If you are looking for "How to Write a Web Service Client using Axis2?" please go
to the <a href="#client">next section</a>. Axis2 provides two ways to create new
Web Services, using code generation and using XML based primary APIs. 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>
-
+<p>If you are looking for "How to Write a Web Service Client using
+Axis2?" please go to the <a href="#client">next section</a>. Axis2
+provides two ways to create new Web Services, using code generation and
+using XML based primary APIs. 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, Create and Deploy 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 try <a href="reference.html#wsdl2java">Java2WSDL tool</a> and create a
WSDL. As you might already know, a WSDL description of a Service provides precise definition
of a Web Service. Axis2 could process the WSDL and generate java code that does most of work
for you. At the server side we call them Skeletons and at the client side Stubs.</p>
-
-
-
+<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 try <a href="reference.html#wsdl2java">Java2WSDL tool</a> and
+create a WSDL. As you might already know, a WSDL description of a
+Service provides precise definition of a Web Service. Axis2 could
+process the WSDL and generate java code that does most of 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>Create a *.aar archive (Axis Archive) for the Web service</li>
   <li>Deploy the Web service</li>
 </ol>
-
 <h3><a name="Step1_:Generate_skeleton">Step1: Generate Skeleton Code</a></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 from <a href="reference.html#wsdl2code">Axis2
Reference Document</a>.</p>
-
-
-<p>The parameters for wsdl2java tool in our example are as follows. Please not that,
we use xmlbeans as the data binding framework and generated code will be sent to samples directory.
Other data binding tools you could use are adb (Axis data binding) and jaxme (<a href="http://ws.apache.org/jaxme/">JaxMe
data binding</a>)</p>
-
-<pre style="margin-bottom: 0.2in">WSDL2Java.sh -uri ../samples/wsdl/Axis2SampleDocLit.wsdl
-ss -sd -d xmlbeans -o ../samples -p org.apache.axis2.userguide</pre>
-
+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 from <a
+ href="reference.html#wsdl2code">Axis2 Reference Document</a>.</p>
+<p>The parameters for wsdl2java tool in our example are as follows.
+Please not that, we use xmlbeans as the data binding framework and
+generated code will be sent to samples directory. Other data binding
+tools you could use are adb (Axis data binding) and jaxme (<a
+ href="http://ws.apache.org/jaxme/">JaxMe data binding</a>)</p>
+<pre style="margin-bottom: 0.2in;">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
 <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>
-
+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>
 <h3><a name="Step2_Implement_Business_Logic">Step 2: Implement Business
 Logic</a></h3>
-
-
-<p>Now you should fill in 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 echoString(..) 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 others will look when they are filled up see <a
href="src/Axis2SampleDocLitServiceCode.html">Code Listing For Axis2SampleDocLitService
Service</a></p>
-
-
-<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.
-   EchoStringReturnDocument retDoc = EchoStringReturnDocument.Factory.newInstance();
-   //send the string back.
-   retDoc.setEchoStringReturn(param4.getEchoStringParam());
-   return retDoc;
- }</pre>
-
-
-
+<p>Now you should fill in 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 echoString(..) 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 others will look when they are filled up see <a
+ href="src/Axis2SampleDocLitServiceCode.html">Code Listing For
+Axis2SampleDocLitService Service</a></p>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString<br>
  (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) throws Exception {<br>
  //Use the factory to create the output document.<br>   org.apache.axis2.userguide.xsd.EchoStringReturnDocument
retDoc = org.apache.axis2.userguide.xsd.EchoStringReturnDocument.Factory.newInstance();<br>
  //send the string back.<br>   retDoc.setEchoStringReturn(param4.getEchoStringParam());<br>
  return retDoc;<br> }</pre>
 <h3><a name="Step4_Create_archive">Step 3: Create Archive File</a></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, that will generate the Axis2 service archive for you.
-However if you do not want to use ant, you could create archive with following steps</p>
-
+<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, that will generate
+the Axis2 service archive for you.
+However if you do not want to use ant, you could create archive with
+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 service.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>
-	<li>Create the archive using content of the class folder. Change directory to class
folder and run <code>jar -cf &lt;service-name&gt;.aar</code> to create
the archive</li>
-</ol>	
-	
-<p>Once the archive is created, the content of the jar should look like this</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 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>
+  <li>Create the archive using content of the class folder. Change
+directory to class folder and run <code>jar -cf
+&lt;service-name&gt;.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>
-
+ border="0"></p>
 <h3><a name="Step5_Deploy_web_service">Step 4: Deploy Web Service</a></h3>
-
 <p>The service can be deployed by simply dropping the ".aar" file in to
 "services" directory in "/webapps/axis2/WEB-INF" of your servlet
-container. We recommend using <a href="http://tomcat.apache.org/">Apache Tomcat</a>
as servlet container. 
-<strong>Please Note that the services directory is available only after axis2.war is
exploded by Tomcat. However easiest way to do it is to start the tomcat after axis2.war is
copied to the webapps directory.</strong> (if you have not already started) and
-check the link "Services" 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 shown under
the deployed services.</p>
-
-<p>Note: Axis2 provides an easy way to deploy Web Services using the "Upload
-Service" tool on Axis2 Web Application's Administration module. (See the <a
-href="webadminguide.html" target="_blank">Web Administration Guide</a> for
+container. We recommend using <a href="http://tomcat.apache.org/">Apache
+Tomcat</a> as 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 link "Services" 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 shown under the deployed services.</p>
+<p>Note: Axis2 provides an easy way to deploy Web Services using the
+"Upload
+Service" tool on Axis2 Web Application's Administration module. (See
+the <a href="webadminguide.html" target="_blank">Web Administration
+Guide</a> for
 more information on this)</p>
-
-
-
 <h2><a name="client">Writing a Web Service Client</a></h2>
-
-
-<p>Axis2 also provides a more complex, yet powerful <strong>XML based client
API</strong> 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 code generation approach presented below</p>
-
+<p>Axis2 also provides a more complex, yet powerful <strong>XML based
+client API</strong> 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 code generation approach presented below</p>
 <h3>Generate Stubs</h3>
-<p>Lets see how we could generate java code (Stub) to handle the client side Web Service
invocation for you.
-That can be done by running the WSDL2Java tool using following arguments</a>
-
-<pre style="margin-bottom: 0.2in">WSDL2Java.sh -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>.
For our example it will be called  "Axis2SampleDocLitServiceStub.java"</p>
-
-<p>Axis2 clients can invoke Web Services both in 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 any 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>
-
+<p>Lets see how we could generate java code (Stub) to handle the client
+side Web Service invocation for you.
+That can be done by running the WSDL2Java tool using following
+arguments
+</p>
+<pre style="margin-bottom: 0.2in;">WSDL2Java.sh -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>.
+For our example it will be called "Axis2SampleDocLitServiceStub.java"</p>
+<p>Axis2 clients can invoke Web Services both in 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 any 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 very simple to understand and the explanations are in
-the form of comments. The Axis home and Axis repository may be used interchangeably.</p>
-<pre>try {
-     Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
-                                "http://localhost:8080/axis2/services/Axis2SampleDocLitService");
-     //Create the request document to be sent.
-     EchoStringParamDocument  reqDoc= EchoStringParamDocument.Factory.newInstance();
-     reqDoc.setEchoStringParam("Axis2 Echo");
-     //invokes the Web service.
-     EchoStringReturnDocument resDoc=stub.echoString(reqDoc);
-     System.out.println(resDoc.getEchoStringReturn());
-
-    } catch (Exception e) {
-        e.printStackTrace();
-    }
-</pre>
-
-
-<p>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 could make Axis2 use your own repository by providing it here. You could find
more information about this from <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>
-
-
-
+<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 very simple to understand and the explanations
+are in
+the form of comments. The terms Axis home and Axis repository may be
+used interchangeably.</p>
+<pre>     try {<br>            org.apache.axis2.userguide.Axis2SampleDocLitServiceStub
stub = new<br>                    org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,<br>
                   "http://localhost:8080/axis2/services/Axis2SampleDocLitService");<br>
           <br>            //Create the request document to be sent.<br>     
      org.apache.axis2.userguide.xsd.EchoStringParamDocument reqDoc =<br>          
         org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();<br>
           reqDoc.setEchoStringParam("Axis2 Echo");<br>            <br>      
     //invokes the Web service.<br>            org.apache.axis2.userguide.xsd.EchoStringReturnDocument
resDoc = stub.echoString(reqDoc);<br>            System.out.println(resDoc.getEchoStringReturn());<br><br>
       } catch (java.rmi.RemoteException e) {<br>            e.printStackTrace();<br>
       }<br></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 could make Axis2 use your
+own repository by providing it here. You could find more information
+about this from <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 includes 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. 
-
-<pre>
-Axis2SampleDocLitServiceStub stub =  new Axis2SampleDocLitServiceStub(null,"http://localhost:8080/axis2/services/Axis2SampleDocLitService");
-//implementing the callback online
-Axis2SampleDocLitServiceCallbackHandler callback = new Axis2SampleDocLitServiceCallbackHandler()
{
-	public void receiveResultechoString(EchoStringReturnDocument resDoc) {
-		System.out.println(resDoc.getEchoStringReturn());
-	}
-	....
-	
-};
-EchoStringParamDocument  reqDoc= EchoStringParamDocument.Factory.newInstance();
-reqDoc.setEchoStringParam("Axis2 Echo");
-stub.startechoString(reqDoc, callback);
-</pre>
-
-
-<p>Even though the above code does a non-blocking invocation at the client API, still
the transport connection may operate in blocking fashion; for example a single HTTP connection
can be used to make the Web Service request and to get the response where 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 response please add the following code
segment after creating the stub. These will force Axis2 to use transport connections for the
request and response while the client uses a Callback to process the response.</p>
-
-<pre>
-stub._getServiceClient().engageModule(new QName("addressing"));
-stub._getServiceClient().getOptions().setUseSeparateListener(true);
-</pre>
-
+<p>The stubs also includes 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>
+<pre>        try {<br>            org.apache.axis2.userguide.Axis2SampleDocLitServiceStub
stub = new<br>                    org.apache.axis2.userguide.Axis2SampleDocLitServiceStub(null,<br>
                   "http://localhost:8080/axis2/services/Axis2SampleDocLitService");<br><br>
           //implementing the callback online<br>            org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler
callback =<br>                    new org.apache.axis2.userguide.Axis2SampleDocLitServiceCallbackHandler()
{<br><br>                public void receiveResultechoString(org.apache.axis2.userguide.xsd.EchoStringReturnDocument
resDoc) {<br>                    System.out.println(resDoc.getEchoStringReturn());<br>
               }<br>            };<br><br>            org.apache.axis2.userguide.xsd.EchoStringParamDocument
reqDoc = <br>                    org.apache.axis2.userguide.xsd.EchoStringParamDocument.Factory.newInstance();<br>
           reqDoc.setEchoStringParam("Axis2
  Echo");<br>            stub.startechoString(reqDoc, callback);<br>        }
catch (java.rmi.RemoteException e) {<br>            e.printStackTrace();<br> 
      }<br></pre>
+<p>Even though the above code does a non-blocking invocation at the
+client API, still the transport connection may operate in blocking
+fashion; for example a single HTTP connection can be used to make the
+Web Service request and to get the response where 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. These 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>
+<pre>stub._getServiceClient().engageModule(new QName("addressing"));<br>stub._getServiceClient().getOptions().setUseSeparateListener(true);<br></pre>
 <p>Once those options are set, Axis2 client does following</p>
 <ol>
-	<li>Start a new Transport Listener(Server) at the client side</li>
-	<li>Set the address of the Transport Listener, as the ReplyTo WS-Addressing Header
of the request Message</li>
-	<li>According to the WS-Addressing rules, 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>
-
+  <li>Start a new Transport Listener(Server) at the client side</li>
+  <li>Set the address of the Transport Listener, as the ReplyTo
+WS-Addressing Header of the request Message</li>
+  <li>According to the WS-Addressing rules, 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, Following code shows how to
do this. </p>
-<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 
-the <code>ConfigurationContext</code> out side 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>
-
+<p>You could use your own repository with Axis2 Client, Following code
+shows how to do this. </p>
+<pre>String axis2Repo = ...<br>String axis2xml = ...<br>ConfigurationContext
configContext = <br>	ConfigurationContextFactory.createConfigurationContextFromFileSystem(axis2Repo,
axis2xml);<br>Service1Stub stub1 = new Service1Stub(configContext,...);<br>//invoke
Service1<br><br>Service2Stub stub2 = new Service2Stub(configContext,...);<br>//invoke
Service2<br>.....<br></pre>
+<p>Note by creating the the <code>ConfigurationContext</code> out side
+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>
 <h2> <a name="config">Configuring Axis2</a></h2>
 <h3>Axis2 repository</h3>
-<p>Axis2 configuration is based on a repository and standard archives formats. A repository
is a directory in file system
-and it should have followings.  </p>
+<p>Axis2 configuration is based on a repository and standard archives
+formats. A repository is a directory in the file system
+and it should have the followings. </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 service archives</li>
-	<li>optional <strong>modules</strong> directory, which will have module
archives</li>
+  <li><strong>axis2.xml</strong>, the Axis2 global deployment
+descriptor in conf/axis2.xml file</li>
+  <li><strong>services</strong> directory, which will have service
+archives</li>
+  <li>optional <strong>modules</strong> directory, which will have
+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 a
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 global configurations</p>
-
+<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 a 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 global configurations repository.
+</p>
 <h3>Global Configurations</h3>
-<p>The Global configuration can be changed by editing the axis2.xml file, look at the
<a href="axis2config.html#Global_Configuration">Axis2 Configuration Guide</a>
for more information</p>
-
+<p>The Global configuration can be changed by editing the axis2.xml
+file, look at 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 the scratch as explained <a href="xmlbased-server.html">here</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>service.xml</strong> file.</p>
-
+<p>New Services can be written either using WSDL based code generation
+as we did, or from the scratch as explained <a
+ href="xmlbased-server.html">here</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 in to the modules directory in repository. Then it becomes available and can be
engaged at global, service or operation sopes. Once engaged it becomes active (add handlers
to the execution flow) at the respective scope. Please refer to <a href="Axis2ArchitectureGuide.html">Axis2
architecture guide</a> for detailed explanation. Following table explains the semantics
of scope and how to engage modules in those scopes.</p>
-
+<p>Each module(.mar file) provides extensions to Axis2. A module can be
+deployed by copying it in to the modules directory in the repository.
+Then it becomes available and can be engaged at global, service or
+operation scopes. Once engaged it becomes active (add handlers to the
+execution flow) at the respective scope. Please refer to <a
+ href="Axis2ArchitectureGuide.html">Axis2 architecture guide</a> for
+detailed explanation. Following table explains the semantics of scope
+and how to engage modules in those scopes.</p>
 <table border="1">
-	<tr><th>Scope</th><th>Semantics</th><th>how to engage</th>
-	<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 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 service.xml
file in 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; to inside
a operation tag of service.xml file in service archive</td></tr>
+  <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 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 service.xml
+file in 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; to inside a
+operation tag of service.xml file in service archive</td>
+    </tr>
+  </tbody>
 </table>
-
-<p>* If a handler is added to a service, or a operation it will be invoked for every
request received by that service or operation</p>
-
-<p>Axis2 provides 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 for 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 module.xml file.</p>. 
-
+<p>* If a handler is added to a service, or a operation it will be
+invoked for every request received by that service or operation</p>
+<p>Axis2 provides 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 for 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 module.xml file.</p>
+.
 <h3>WS-Addressing support</h3>
-
-<p>WS-Addressing support for Axis2 is implemented as the addressing module. To enable
addressing you need to engage the addressing module in both server and client sides. In order
to do this</p>
-
+<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. In order to do this</p>
 <ol>
-	<li>To <strong>enable</strong> addressing at the server side you need
to copy addressing.mar file to modules directory of server's axis2 repository. To engage module
add a &lt;module ref="addressing"/&gt; to axis2.xml. <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 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> addressing module you should either add
&lt;module ref="addressing"/&gt; to axis2.xml file at the client side or call <pre>stub._getServiceClient().engageModule(moduleName)</pre></li>
+  <li>To <strong>enable</strong> addressing at the server side you
+need to copy addressing.mar file to modules directory of server's axis2
+repository. To engage module add a &lt;module ref="addressing"/&gt; to
+axis2.xml. <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 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> addressing module you should either
+add &lt;module ref="addressing"/&gt; to axis2.xml file at the client
+side or call
+    <pre>stub._getServiceClient().engageModule(moduleName)</pre>
+  </li>
 </ol>
-
-
 <h2><a name="advanced">Advanced Topics</a></h2>
-
 <h3>Transports</h3>
-
-<p>Axis2 is by default 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 following documents.</p> 
-
+<p>Axis2 is by default 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 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>
+  <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>
-
+<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 the <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>
- 
+<p>Axis2 provides Security support using the <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>
-
+<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 ship with Axis Data Binding(ADB) as the default data binding framework, however
the data binding frameworks are pluggable to axis2, and you could use other data binding frameworks
with Axis2. Please refer to following documents for more information.</p>
-
+<p>Axis2 ship with Axis Data Binding(ADB) as the default data binding
+framework, however the data binding frameworks are pluggable to axis2,
+and you could use other data binding frameworks with Axis2. Please
+refer to 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>
+  <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="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>
 </ol>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 </body>
 </html>



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


Mime
View raw message