You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2006/04/20 07:32:07 UTC
svn commit: r395490 [2/3] - in /webservices/axis2/trunk/java/xdocs: ./
latest/
Modified: webservices/axis2/trunk/java/xdocs/latest/userguide2.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/userguide2.html?rev=395490&r1=395489&r2=395490&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/userguide2.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/userguide2.html Wed Apr 19 22:32:05 2006
@@ -1,394 +1,396 @@
-<!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 User's Guide</title>
- <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
-</head>
-
-<body lang="en-US" dir="ltr">
-<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
-
-<p><i>Version 1.0</i></p>
-<i>User Feedback: <a
-href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>
-
-<p align="right">Pages: <a href="userguide.html">Content</a>, <a
-href="userguide1.html">1</a>, <b>2</b>, <a href="userguide3.html">3</a>, <a
-href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
-
-<p><b><font size="4">Note (on samples):</font></b> In this page of the user's
-guide we will look at how to write and deploy Web Services using Axis2. All
-the user's guide samples are located in the <b>"samples/userguide/src"</b>
-directory of the binary distribution.</p>
-
-<h2><a name="Web_Services_Using_Axis2">Web Services Using Axis2</a></h2>
-
-<p>Before starting, please check whether you have deployed the "axis2.war" in
-your servlet container and it is working properly. (See <a
-href="installationguide.html" target="_blank">Installation Guide</a>). User
-can select any of the following two ways of writing web services using
-Axis2. </p>
-<ol>
- <li><a href="#Writing_Web_Services_Using Axis2's_Primary_APIs">Use Axis2's
- primary interfaces (APIs) and implement the business logic.</a></li>
- <li><p><a href="#Writing_Web_Services_by_Code_Generating_Skeleton">Start
- from the WSDL ->Code generate the Skeleton ->Implement the Business
- Logic.</a></p>
- </li>
-</ol>
-
-<h3><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">Writing Web
-Services Using Axis2's Primary APIs</a></h3>
-
-<h4><a name="Creating_Web_Service__MyService_">Creating Web Service
-(MyService)</a></h4>
-
-<p>First let's see how we can write a simple Web Service (MyService) using
-Axis2's primary interfaces and deploy it. For this purpose we will create a
-Web Service with two operations as follows.</p>
-<pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
-public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and
- //responds with another OMElement after processing.</pre>
-
-<p>Complete code for this example Web Service (MyService) can be found in the
-"Axis2Home/samples/userguide/src" directory under "userguide/example1"
-package. As you can see, the two operations are very simple and need no
-explanations on what they do. Now let's see how we can write the deployment
-descriptors for the service and deploy it.</p>
-
-<h4><a name="How_to_write_the_Web_Service_">How to write the Web
-Service?</a></h4>
-Writing a new Web Service with Axis2 involve four steps:
-<ol>
- <li><p style="margin-bottom: 0in">Write the Implementation Class</p>
- </li>
- <li><p style="margin-bottom: 0in">Write a services.xml file to explain the
- Web Service</p>
- </li>
- <li><p style="margin-bottom: 0in">create a *.aar archive (Axis Archive) for
- the Web Service</p>
- </li>
- <li><p>Deploy the Web Service</p>
- </li>
-</ol>
-
-<h4><a name="Step1_:Write_the_Implementation_Class">Step1 :Write the
-Implementation Class</a></h4>
-
-<p>Provides a implementation class that provide the business logic for the
-Web Service, it should have methods that match the operations in the Web
-Service. Unless you have data binding the signature of the methods can have
-one parameter of type OMElement.</p>
-<pre>public class MyService{
- public void ping(OMElement element){
- ......
- }
- public OMElement echo(OMElement element){
- ......
- }
-}</pre>
-
-<h4><a name="Step2_:Write_the_services_xml_file">Step2 :Write the
-services.xml file</a></h4>
-
-<p>Axis2 uses "services.xml" to keep configurations for a Web Service. Each
-Web Service deployed in Axis2 needs a "services.xml" containing the
-configurations. "services.xml" for MyService will be as follows.</p>
-<pre><service >
- <description>
- This is a sample Web Service with two operations, echo and ping.
- </description>
- <parameter name="ServiceClass" locked="false">userguide.example1.MyService</parameter>
- <operation name="echo">
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
- </operation>
- <operation name="ping">
- <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
- </operation>
- </service></pre>
-
-<p><em>The above XML tags can be explained as follows:</em></p>
-
-<p>Name of the service will be the name of the archive file , if and only if
-the services.xml contains only one service element.</p>
-
-<p>Next comes the description and the service class.</p>
-
-<p>The next two xml tags describe the operations that are available in this
-service with respective message receivers. For the "echo" operation we have
-used a <strong>RawXMLINOutMessageReceiver</strong> since it is an IN-OUT
-operation. For IN-ONLY operation "ping", we have used
-<strong>RawXMLINOnlyMessageReceiver</strong> as the message receiver.</p>
-
-<p>You can write a services.xml file to include a group of services instead
-of a single service. This makes management and deployment of a set of related
-services very easy. At runtime you can share information between these
-services within a single interaction using the ServiceGroupContext. If you
-hope to use this functionality, the services.xml file should have following
-format.</p>
-<pre><serviceGroup>
- <service name="Service1">
- <!-- details for Service1 -->
- </service>
- <service name="Service2">
- <!-- details for Service2 -->
- </service>
- <module ref="ModuleName" />
- <parameter name="serviceGroupParam1" locked="false">value 1</parameter>
-</serviceGroup></pre>
-
-<p>Note : name of the service is a compulsory attribute</p>
-
-<h4><a name="Step3_:Create_the_Web_Service_Archive">Step3 :Create the Web
-Service Archive</a></h4>
-
-<p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web
-Services. Therefore, for MyService we will use "MyService.aar" with the
-"services.xml" packaged in the META-INF as shown in the following picture.</p>
-
-<p><img src="images/userguide/ServiceItems.jpg" name="Graphic1"
-align="bottom" width="176" height="91" border="0"></p>
-
-<p>To create "MyService.aar" user can first create a jar file containing all
-the files necessary for the service and then rename the "jar" to "aar" so
-that Axis2 understands it as a service archive. This has already been created
-in the "Axis2Home/samples/userguide" directory. Now let's use it...</p>
-
-<h4><a name="Step4_:Deploy_the_Web_Service">Step4 :Deploy the Web
-Service</a></h4>
-
-<p>Deploying the service is just a matter of dropping the ".aar" in to
-"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
-your servlet container, hence copy the "MyService.aar" into the
-"<b>services</b>" directory. Once these steps are completed, start the
-servlet container (if you have not already started) and check the link
-"Services" on the <a href="http://localhost:8080/axis2/index.jsp"
-target="_blank">Home Page of Axis2 Web Application</a>
-(http://localhost:8080/axis2/index.jsp) and see whether the MyService is
-deployed properly. If you can see the following output then you have
-successfully deployed MyService on Axis2.</p>
-
-<p align="center"><img src="images/userguide/MyServiceDeployed.jpg"
-name="Graphic2" align="bottom" border="0"></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>
-
-<h3><a name="Writing_Web_Services_by_Code_Generating_Skeleton">Writing Web
-Services by Code Generating Skeleton</a></h3>
-
-<p>This is the second method of writing Web Services using Axis2. Let's see
-how we can generate the skeleton from a given WSDL and implement the business
-logic using Axis2. For this we use Axis2SampleDocLit.wsdl that can be found
-in the <b>wsdl</b> directory under samples.</p>
-
-<h4><a name="WSDL2Java_Tool">WSDL2Java Tool</a></h4>
-
-<p>To generate the skeleton and the 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 is as follows and user can specify these
-values depending on their requirements.</p>
-<pre>Usage WSDL2Code -uri <Location of WSDL> : WSDL file location
--o <output Location> : output file location
--a : Generate async style code only. Default is off
--s : Generate sync style code only. Default is off. takes precedence over -a
--p <package name> : set custom package name
--l <language> : valid languages are java and csharp. Default is java
--t : Generate TestCase to test the generated code
--ss : Generate server side code (i.e. skeletons). Default is off
--sd : Generate service descriptor (i.e. services.xml). Default is off. Valid with -ss
--d <databinding> : valid databinding(s) are adb, xmlbeans and jaxme. Default is adb
--g Generates all the classes. valid only with the -ss
--pn <port_name> : name of port in the presence of multiple ports
--sn <service_name> : name of service in the presence of multiple services
--u : unpacks the databinding classes
--r <repository_path> : path of the repository against which code is generated</pre>
-
-<p>We will use the tool with the following parameters and generate the
-skeleton and the other required classes.</p>
-
-<p>Windows users can use the following command in the console:</p>
-<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ..\samples -p org.apache.axis2.userguide</pre>
-
-<p>Linux users should switch the file separator:</p>
-<pre style="margin-bottom: 0.2in">WSDL2Java -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>src</b> directory inside
-samples, and the schema classes in <strong>schemaorg_apache_xmlbeans</strong>
-directory which is inside resources directory also inside samples
-dir<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>
-
-<h4><a name="Implement_the_Business_Logic">Implement the Business
-Logic</a></h4>
-
-<p>Locate the skeleton class that can be found under src/userguide directory
-with the name "Axis2SampleDocLitPortTypeSkeleton.java". This is the skeleton
-for our web service and we can now easily implement the business logic. The
-WSDL we have used has three operations:<!--<li><p style="margin-bottom: 0in">echoVoid - Operation that does not
-accept any input parameters and also provide no out put parameters. Just
-perform some task </p>
-</li>-->
-</p>
-<ul>
- <li><p style="margin-bottom: 0in">echoString - Operation that echoes a
- String value </p>
- </li>
- <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
- string array as the input and echoes them back</p>
- </li>
- <li><p>echoStruct - Operation that accept a Struct as the input and echoes
- them back.</p>
- </li>
-</ul>
-<!--<h4>echoVoid </h4>
-
-<p>Locate the following code segment in the
-"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business logic. For
-the explanation purpose we do not need anything to be implemented here.</p>
-<pre>public void echoVoid(){
-//Todo fill this with the necessary business logic
-}</pre> -->
-
-<h4><a name="echoString">echoString</a></h4>
-
-<p>Locate the following code segment in the
-"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business logic as
-shown below.</p>
-<pre> public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString
- (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) {
- //To do fill this with the necessary business logic
- return null;
- }</pre>
-
-<p>Once filled with the business logic it will be as follows. The code is
-simple and the explanations are given as comments.</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>Similarly following code fragments shows how you can fill the business
-logic for our first web service.</p>
-
-<h4><a name="echoStringArray">echoStringArray</a></h4>
-<pre>public org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument echoStringArray
- (org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument param0) throws Exception {
- //Use the factory to create the output document.
- EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
- //Get the String array from the input parameters.
- String[] inParams = param0.getEchoStringArrayParam().getStringArray();
- ArrayOfstringLiteral retParams = ArrayOfstringLiteral.Factory.newInstance();
- //Set the input parameters to the output parameters for echoing.
- for (int i = 0; i < inParams.length; i++) {
- retParams.addString(inParams[i]);
- }
- //return the output document.
- retDoc.setEchoStringArrayReturn(retParams);
- return retDoc;
-}</pre>
-
-<h4><a name="echoStruct">echoStruct</a></h4>
-<pre>public org.apache.axis2.userguide.xsd.EchoStructReturnDocument echoStruct
- (org.apache.axis2.userguide.xsd.EchoStructParamDocument param2) throws Exception {
- //Use the factory to create the output document.
- EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
-
- //Get the SOAPStrcut from the incoming parameters
- SOAPStruct inStruct = param2.getEchoStructParam();
-
- //Struct for the sending back
- SOAPStruct outStruct = SOAPStruct.Factory.newInstance();
-
- //Fill the outgoing struct
- outStruct.setVarFloat(inStruct.getVarFloat());
- outStruct.setVarInt(inStruct.getVarInt());
- outStruct.setVarString(inStruct.getVarString());
- //Set the outgoing document.
- retDoc.setEchoStructReturn(outStruct);
-
- return retDoc;
-}</pre>
-
-<h4><a name="services_xml">services.xml</a></h4>
-
-<p> Axis2 uses "services.xml" to hold the configurations for a particular web
-service deployed in the Axis2 engine. When we generate the skeleton using the
-WSDL2Java tool, it will also generate the required services.xml for this web
-service as well. This can be found in the same directory as the skeleton. The
-generated services.xml is as follows.</p>
-<pre><!-- This services.xml file was auto-generated from WSDL -->
-<!-- by the Apache Axis2 version: #axisVersion# #today# -->
-<serviceGroup>
- <service name="Axis2SampleDocLitService">
- <messageReceivers>
- <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="org.apache.axis2.userguide.Axis2SampleDocLitPortTypeMessageReceiverInOut"/>
- </messageReceivers>
- <parameter locked="false" name="ServiceClass">org.apache.axis2.userguide.Axis2SampleDocLitPortTypeSkeleton
- </parameter>
- <!--All public methods of the service class are exposed by default-->
- </service>
-</serviceGroup></pre>
-
-<p>First line of the "services.xml" gives the name of the Web Service. This
-is used in the URL to the service as the service name. Next comes the
-description and the service class. The next xml tags describe the operations
-that are available in this service with respective message receivers.</p>
-
-<h4><a name="Packaging">Packaging</a></h4>
-
-<p>Next step in the process is to package the classes in a .aar (axis2
-archive) and deploy it in Axis2. When the WSDL2Java tool generate the
-skeleton it will also generate the required data binding classes. These
-schema related classes are located in the
-<strong>schemaorg_apache_xmlbeans</strong> directory inside resources
-directory of the generated code. Copy this to your class path, compile the
-skeleton and the supporting classes. In order to create the .aar file, let's
-create the following directory structure with the required files and then
-simply use jar command to package it.</p>
-
-<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
-border="0"></p>
-
-<p>Go to the top level directory where you can find the class files for the
-above service (i.e. one level up on the directory structure shown above),
-then type the following command in a command line.</p>
-<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitPortType.aar .</pre>
-
-<p>Deploying the service is just a matter of dropping the ".aar" in to
-"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
-your servlet container, hence copy the "echo.aar" into the "<b>services</b>"
-directory. Once these steps are completed, please start the servlet container
-(if you have not already started) and check the link "Services" on the <a
-href="http://localhost:8080/axis2/index.jsp" target="_blank">Home Page of
-Axis2 Web Application</a> (http://localhost:8080/axis2/index.jsp) and see
-whether the Axis2SampleDocLitPortType is deployed properly. If you can see
-the following output then you have successfully deployed
-Axis2SampleDocLitPortType on Axis2.</p>
-
-<p align="center"><img src="images/userguide/ServiceDeployed.jpg"
-name="Graphic4" align="bottom" border="0"></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>
-
-<p align="right"><a href="userguide1.html"><img src="images/arrow_left.gif">
-Previous</a> | <a href="userguide3.html">Next <img
-src="images/arrow_right.gif"></a></p>
-
-<p>Pages: <a href="userguide.html">Content</a>, <a
-href="userguide1.html">1</a>, <b>2</b>, <a href="userguide3.html">3</a>, <a
-href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
-</body>
-</html>
+<!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 User's Guide</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<p><i>Version 1.0</i></p>
+<p><i>User Feedback: <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see <a
+href="http://ws.apache.org/axis2/mail-lists.html">here.</a></p>
+
+<p align="right">Pages: <a href="userguide.html">Content</a>, <a
+href="userguide1.html">1</a>, <b>2</b>, <a href="userguide3.html">3</a>, <a
+href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
+
+<p><b><font size="4">Note (on samples):</font></b> In this page of the user's
+guide we will look at how to write and deploy Web Services using Axis2. All
+the user's guide samples are located in the <b>"samples/userguide/src"</b>
+directory of the binary distribution.</p>
+
+<h2><a name="Web_Services_Using_Axis2">Web Services Using Axis2</a></h2>
+
+<p>Before starting, please check whether you have deployed the "axis2.war" in
+your servlet container and it is working properly. (See <a
+href="installationguide.html" target="_blank">Installation Guide</a>). User
+can select any of the following two ways of writing web services using
+Axis2. </p>
+<ol>
+ <li><a href="#Writing_Web_Services_Using Axis2's_Primary_APIs">Use Axis2's
+ primary interfaces (APIs) and implement the business logic.</a></li>
+ <li><p><a href="#Writing_Web_Services_by_Code_Generating_Skeleton">Start
+ from the WSDL ->Code generate the Skeleton ->Implement the Business
+ Logic.</a></p>
+ </li>
+</ol>
+
+<h3><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">Writing Web
+Services Using Axis2's Primary APIs</a></h3>
+
+<h4><a name="Creating_Web_Service__MyService_">Creating Web Service
+(MyService)</a></h4>
+
+<p>First let's see how we can write a simple Web Service (MyService) using
+Axis2's primary interfaces and deploy it. For this purpose we will create a
+Web Service with two operations as follows.</p>
+<pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and do some processing.
+public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and
+ //responds with another OMElement after processing.</pre>
+
+<p>Complete code for this example Web Service (MyService) can be found in the
+"Axis2Home/samples/userguide/src" directory under "userguide/example1"
+package. As you can see, the two operations are very simple and need no
+explanations on what they do. Now let's see how we can write the deployment
+descriptors for the service and deploy it.</p>
+
+<h4><a name="How_to_write_the_Web_Service_">How to write the Web
+Service?</a></h4>
+Writing a new Web Service with Axis2 involve four steps:
+<ol>
+ <li><p style="margin-bottom: 0in">Write the Implementation Class</p>
+ </li>
+ <li><p style="margin-bottom: 0in">Write a services.xml file to explain the
+ Web Service</p>
+ </li>
+ <li><p style="margin-bottom: 0in">create a *.aar archive (Axis Archive) for
+ the Web Service</p>
+ </li>
+ <li><p>Deploy the Web Service</p>
+ </li>
+</ol>
+
+<h4><a name="Step1_:Write_the_Implementation_Class">Step1 :Write the
+Implementation Class</a></h4>
+
+<p>Provides a implementation class that provide the business logic for the
+Web Service, it should have methods that match the operations in the Web
+Service. Unless you have data binding the signature of the methods can have
+one parameter of type OMElement.</p>
+<pre>public class MyService{
+ public void ping(OMElement element){
+ ......
+ }
+ public OMElement echo(OMElement element){
+ ......
+ }
+}</pre>
+
+<h4><a name="Step2_:Write_the_services_xml_file">Step2 :Write the
+services.xml file</a></h4>
+
+<p>Axis2 uses "services.xml" to keep configurations for a Web Service. Each
+Web Service deployed in Axis2 needs a "services.xml" containing the
+configurations. "services.xml" for MyService will be as follows.</p>
+<pre><service >
+ <description>
+ This is a sample Web Service with two operations, echo and ping.
+ </description>
+ <parameter name="ServiceClass" locked="false">userguide.example1.MyService</parameter>
+ <operation name="echo">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
+ </operation>
+ <operation name="ping">
+ <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/>
+ </operation>
+ </service></pre>
+
+<p><em>The above XML tags can be explained as follows:</em></p>
+
+<p>Name of the service will be the name of the archive file , if and only if
+the services.xml contains only one service element.</p>
+
+<p>Next comes the description and the service class.</p>
+
+<p>The next two xml tags describe the operations that are available in this
+service with respective message receivers. For the "echo" operation we have
+used a <strong>RawXMLINOutMessageReceiver</strong> since it is an IN-OUT
+operation. For IN-ONLY operation "ping", we have used
+<strong>RawXMLINOnlyMessageReceiver</strong> as the message receiver.</p>
+
+<p>You can write a services.xml file to include a group of services instead
+of a single service. This makes management and deployment of a set of related
+services very easy. At runtime you can share information between these
+services within a single interaction using the ServiceGroupContext. If you
+hope to use this functionality, the services.xml file should have following
+format.</p>
+<pre><serviceGroup>
+ <service name="Service1">
+ <!-- details for Service1 -->
+ </service>
+ <service name="Service2">
+ <!-- details for Service2 -->
+ </service>
+ <module ref="ModuleName" />
+ <parameter name="serviceGroupParam1" locked="false">value 1</parameter>
+</serviceGroup></pre>
+
+<p>Note : name of the service is a compulsory attribute</p>
+
+<h4><a name="Step3_:Create_the_Web_Service_Archive">Step3 :Create the Web
+Service Archive</a></h4>
+
+<p>Axis2 use ".aar" (Axis Archive) file as the deployment package for Web
+Services. Therefore, for MyService we will use "MyService.aar" with the
+"services.xml" packaged in the META-INF as shown in the following picture.</p>
+
+<p><img src="images/userguide/ServiceItems.jpg" name="Graphic1"
+align="bottom" width="176" height="91" border="0"></p>
+
+<p>To create "MyService.aar" user can first create a jar file containing all
+the files necessary for the service and then rename the "jar" to "aar" so
+that Axis2 understands it as a service archive. This has already been created
+in the "Axis2Home/samples/userguide" directory. Now let's use it...</p>
+
+<h4><a name="Step4_:Deploy_the_Web_Service">Step4 :Deploy the Web
+Service</a></h4>
+
+<p>Deploying the service is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "MyService.aar" into the
+"<b>services</b>" directory. Once these steps are completed, start the
+servlet container (if you have not already started) and check the link
+"Services" on the <a href="http://localhost:8080/axis2/index.jsp"
+target="_blank">Home Page of Axis2 Web Application</a>
+(http://localhost:8080/axis2/index.jsp) and see whether the MyService is
+deployed properly. If you can see the following output then you have
+successfully deployed MyService on Axis2.</p>
+
+<p align="center"><img src="images/userguide/MyServiceDeployed.jpg"
+name="Graphic2" align="bottom" border="0"></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>
+
+<h3><a name="Writing_Web_Services_by_Code_Generating_Skeleton">Writing Web
+Services by Code Generating Skeleton</a></h3>
+
+<p>This is the second method of writing Web Services using Axis2. Let's see
+how we can generate the skeleton from a given WSDL and implement the business
+logic using Axis2. For this we use Axis2SampleDocLit.wsdl that can be found
+in the <b>wsdl</b> directory under samples.</p>
+
+<h4><a name="WSDL2Java_Tool">WSDL2Java Tool</a></h4>
+
+<p>To generate the skeleton and the 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 is as follows and user can specify these
+values depending on their requirements.</p>
+<pre>Usage WSDL2Code -uri <Location of WSDL> : WSDL file location
+-o <output Location> : output file location
+-a : Generate async style code only. Default is off
+-s : Generate sync style code only. Default is off. takes precedence over -a
+-p <package name> : set custom package name
+-l <language> : valid languages are java and csharp. Default is java
+-t : Generate TestCase to test the generated code
+-ss : Generate server side code (i.e. skeletons). Default is off
+-sd : Generate service descriptor (i.e. services.xml). Default is off. Valid with -ss
+-d <databinding> : valid databinding(s) are adb, xmlbeans and jaxme. Default is adb
+-g Generates all the classes. valid only with the -ss
+-pn <port_name> : name of port in the presence of multiple ports
+-sn <service_name> : name of service in the presence of multiple services
+-u : unpacks the databinding classes
+-r <repository_path> : path of the repository against which code is generated</pre>
+
+<p>We will use the tool with the following parameters and generate the
+skeleton and the other required classes.</p>
+
+<p>Windows users can use the following command in the console:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ..\samples -p org.apache.axis2.userguide</pre>
+
+<p>Linux users should switch the file separator:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -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>src</b> directory inside
+samples, and the schema classes in <strong>schemaorg_apache_xmlbeans</strong>
+directory which is inside resources directory also inside samples
+dir<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>
+
+<h4><a name="Implement_the_Business_Logic">Implement the Business
+Logic</a></h4>
+
+<p>Locate the skeleton class that can be found under src/userguide directory
+with the name "Axis2SampleDocLitPortTypeSkeleton.java". This is the skeleton
+for our web service and we can now easily implement the business logic. The
+WSDL we have used has three operations:<!--<li><p style="margin-bottom: 0in">echoVoid - Operation that does not
+accept any input parameters and also provide no out put parameters. Just
+perform some task </p>
+</li>-->
+</p>
+<ul>
+ <li><p style="margin-bottom: 0in">echoString - Operation that echoes a
+ String value </p>
+ </li>
+ <li><p style="margin-bottom: 0in">echoStringArray - Operation that accept
+ string array as the input and echoes them back</p>
+ </li>
+ <li><p>echoStruct - Operation that accept a Struct as the input and echoes
+ them back.</p>
+ </li>
+</ul>
+<!--<h4>echoVoid </h4>
+
+<p>Locate the following code segment in the
+"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business logic. For
+the explanation purpose we do not need anything to be implemented here.</p>
+<pre>public void echoVoid(){
+//Todo fill this with the necessary business logic
+}</pre> -->
+
+<h4><a name="echoString">echoString</a></h4>
+
+<p>Locate the following code segment in the
+"Axis2SampleDocLitPortTypeSkeleton.java" and fill the business logic as
+shown below.</p>
+<pre> public org.apache.axis2.userguide.xsd.EchoStringReturnDocument echoString
+ (org.apache.axis2.userguide.xsd.EchoStringParamDocument param4) {
+ //To do fill this with the necessary business logic
+ return null;
+ }</pre>
+
+<p>Once filled with the business logic it will be as follows. The code is
+simple and the explanations are given as comments.</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>Similarly following code fragments shows how you can fill the business
+logic for our first web service.</p>
+
+<h4><a name="echoStringArray">echoStringArray</a></h4>
+<pre>public org.apache.axis2.userguide.xsd.EchoStringArrayReturnDocument echoStringArray
+ (org.apache.axis2.userguide.xsd.EchoStringArrayParamDocument param0) throws Exception {
+ //Use the factory to create the output document.
+ EchoStringArrayReturnDocument retDoc = EchoStringArrayReturnDocument.Factory.newInstance();
+ //Get the String array from the input parameters.
+ String[] inParams = param0.getEchoStringArrayParam().getStringArray();
+ ArrayOfstringLiteral retParams = ArrayOfstringLiteral.Factory.newInstance();
+ //Set the input parameters to the output parameters for echoing.
+ for (int i = 0; i < inParams.length; i++) {
+ retParams.addString(inParams[i]);
+ }
+ //return the output document.
+ retDoc.setEchoStringArrayReturn(retParams);
+ return retDoc;
+}</pre>
+
+<h4><a name="echoStruct">echoStruct</a></h4>
+<pre>public org.apache.axis2.userguide.xsd.EchoStructReturnDocument echoStruct
+ (org.apache.axis2.userguide.xsd.EchoStructParamDocument param2) throws Exception {
+ //Use the factory to create the output document.
+ EchoStructReturnDocument retDoc = EchoStructReturnDocument.Factory.newInstance();
+
+ //Get the SOAPStrcut from the incoming parameters
+ SOAPStruct inStruct = param2.getEchoStructParam();
+
+ //Struct for the sending back
+ SOAPStruct outStruct = SOAPStruct.Factory.newInstance();
+
+ //Fill the outgoing struct
+ outStruct.setVarFloat(inStruct.getVarFloat());
+ outStruct.setVarInt(inStruct.getVarInt());
+ outStruct.setVarString(inStruct.getVarString());
+ //Set the outgoing document.
+ retDoc.setEchoStructReturn(outStruct);
+
+ return retDoc;
+}</pre>
+
+<h4><a name="services_xml">services.xml</a></h4>
+
+<p> Axis2 uses "services.xml" to hold the configurations for a particular web
+service deployed in the Axis2 engine. When we generate the skeleton using the
+WSDL2Java tool, it will also generate the required services.xml for this web
+service as well. This can be found in the same directory as the skeleton. The
+generated services.xml is as follows.</p>
+<pre><!-- This services.xml file was auto-generated from WSDL -->
+<!-- by the Apache Axis2 version: #axisVersion# #today# -->
+<serviceGroup>
+ <service name="Axis2SampleDocLitService">
+ <messageReceivers>
+ <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="org.apache.axis2.userguide.Axis2SampleDocLitPortTypeMessageReceiverInOut"/>
+ </messageReceivers>
+ <parameter locked="false" name="ServiceClass">org.apache.axis2.userguide.Axis2SampleDocLitPortTypeSkeleton
+ </parameter>
+ <!--All public methods of the service class are exposed by default-->
+ </service>
+</serviceGroup></pre>
+
+<p>First line of the "services.xml" gives the name of the Web Service. This
+is used in the URL to the service as the service name. Next comes the
+description and the service class. The next xml tags describe the operations
+that are available in this service with respective message receivers.</p>
+
+<h4><a name="Packaging">Packaging</a></h4>
+
+<p>Next step in the process is to package the classes in a .aar (axis2
+archive) and deploy it in Axis2. When the WSDL2Java tool generate the
+skeleton it will also generate the required data binding classes. These
+schema related classes are located in the
+<strong>schemaorg_apache_xmlbeans</strong> directory inside resources
+directory of the generated code. Copy this to your class path, compile the
+skeleton and the supporting classes. In order to create the .aar file, let's
+create the following directory structure with the required files and then
+simply use jar command to package it.</p>
+
+<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
+border="0"></p>
+
+<p>Go to the top level directory where you can find the class files for the
+above service (i.e. one level up on the directory structure shown above),
+then type the following command in a command line.</p>
+<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitPortType.aar .</pre>
+
+<p>Deploying the service is just a matter of dropping the ".aar" in to
+"services" directory that can be found in the "\webapps\axis2\WEB-INF" of
+your servlet container, hence copy the "echo.aar" into the "<b>services</b>"
+directory. Once these steps are completed, please start the servlet container
+(if you have not already started) and check the link "Services" on the <a
+href="http://localhost:8080/axis2/index.jsp" target="_blank">Home Page of
+Axis2 Web Application</a> (http://localhost:8080/axis2/index.jsp) and see
+whether the Axis2SampleDocLitPortType is deployed properly. If you can see
+the following output then you have successfully deployed
+Axis2SampleDocLitPortType on Axis2.</p>
+
+<p align="center"><img src="images/userguide/ServiceDeployed.jpg"
+name="Graphic4" align="bottom" border="0"></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>
+
+<p align="right"><a href="userguide1.html"><img src="images/arrow_left.gif">
+Previous</a> | <a href="userguide3.html">Next <img
+src="images/arrow_right.gif"></a></p>
+
+<p>Pages: <a href="userguide.html">Content</a>, <a
+href="userguide1.html">1</a>, <b>2</b>, <a href="userguide3.html">3</a>, <a
+href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
+</body>
+</html>
Modified: webservices/axis2/trunk/java/xdocs/latest/userguide3.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/userguide3.html?rev=395490&r1=395489&r2=395490&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/latest/userguide3.html (original)
+++ webservices/axis2/trunk/java/xdocs/latest/userguide3.html Wed Apr 19 22:32:05 2006
@@ -1,515 +1,518 @@
-<!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 User's Guide</title>
- <meta name="generator" content="amaya 9.3, see http://www.w3.org/Amaya/">
-</head>
-
-<body lang="en-US" dir="ltr">
-<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
-
-<p><i>Version 1.0</i></p>
-<i>User Feedback: <a
-href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>
-
-<p align="right">Pages: <a href="userguide.html">Content</a>, <a
-href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <b>3</b>, <a
-href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
-
-<p><b><font size="4">Note (on samples):</font></b> In this page of the user's
-guide we will look at how to write Web Service Clients using Axis2. All the
-user's guide samples are located at the <b><font
-color="#000000">"samples/userguide/src"</font></b> directory of the binary
-distribution. So... let's explore the samples.</p>
-
-<h2><a name="Web_Service_Clients_Using_Axis2">Web Service Clients Using
-Axis2</a></h2>
-
-<p>Now let's see how we can write a Web Service Client to use this Web
-Service.</p>
-
-<p>Web services can be used to provide wide range of functionality to the
-users ranging from simple, less time consuming operations such as
-"getStockQuote" to time consuming business services. When we utilize (invoke
-using client applications) these Web Service we cannot use some simple
-generic invocation paradigm that suites all the timing complexities involved
-in the service operations. For example, if we use a single transport channel
-(such as HTTP) to invoke a Web Service with and IN-OUT operation that take
-long time to complete, then most of the time 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 in to play when we need them. Let's try to analyze some common
-service invocation paradigms.</p>
-
-<p>Many web service engines provide the users with a Blocking and
-Non-Blocking client APIs.</p>
-<ul>
- <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
- invocation is called, the client application hangs and only gets control
- back when the operation completes, after which client receives a response
- or a fault. This is the simplest way of invoking Web Services and it also
- suites many business situations.</p>
- </li>
- <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
- hence once a service invocation is called, the client application
- immediately gets the control back and the response is retrieved using the
- callback object provided. This approach provides the flexibility to the
- client application to invoke several Web Services simultaneously without
- blocking the operation already invoked.</p>
- </li>
-</ul>
-
-<p>Both these mechanisms work in the API level. Let's name the asynchronous
-behavior that we can get using the <strong>Non-Blocking API</strong> as
-<b>API Level Asynchrony.</b></p>
-
-<p>Both these mechanisms use single transport connection to send the request
-and to receive the response. They severely lags the capability of using two
-transport connections for the request and the response (either One-Way of
-Two-Way). So both 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 <strong>two
-separate transport connections for request and response</strong>. The
-asynchronous behavior that we gain using this solution can be called
-<b>Transport Level Asynchrony</b>.</p>
-
-<p>By combining API Level Asynchrony & Transport Level Asynchrony 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>Simplest and the 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. No blocking in the API level and also in the transport
- level</p>
- </td>
- </tr>
- </tbody>
-</table>
-
-<p>Axis2 provides the user with all these possibilities to invoke Web
-Services.</p>
-
-<p>Below we describe how to write Web Services Clients using Axis2. This can
-be done in two methods:</p>
-<ol>
- <li><a href="#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Using
- the Axis2's primary APIs</a></li>
- <li><p><a
- href="#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Using
- stubs generated with data binding support</a>, making the life easy for
- developers writing Web Service client applications</p>
- </li>
-</ol>
-
-<h3><a name="Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
-Web Service Clients Using Axis2's Primary APIs</a></h3>
-
-<h4><a name="EchoBlockingClient">EchoBlockingClient</a></h4>
-
-<p>Axis2 provides the user with several invocation patterns for Web Services,
-ranging from pure blocking single channel invocations to a non-blocking dual
-channel invocations. Let's first see how we can write a client to invoke
-"echo" operation of "MyService" using the simplest blocking invocation. The
-client code you need to write is as follows.</p>
-<source><pre> try {
- OMElement payload = ClientUtil.getEchoOMElement();
- <span style="color: #24C113">
- Options options = new Options();
- options.setTo(targetEPR);
- options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
- options.setUseSeparateListener(false);
-
- ServiceClient serviceClient = new ServiceClient();
- serviceClient.setOptions(options);
-
- OMElement result = sender.sendReceive(payload);
- </span>
- StringWriter writer = new StringWriter();
- result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance().createXMLStreamWriter(writer)));
- writer.flush();
-
- System.out.println(writer.toString());
-
- } catch (AxisFault axisFault) {
- axisFault.printStackTrace();
- } catch (XMLStreamException e) {
- e.printStackTrace();
- }
-}</pre>
-</source>
-<p>The green lines shows the set of operations that you need to perform
-inorder to invoke a web service. The rest is used to create the OMElement
-that needs to be sent and display the response OMElement. To test this
-client, use the provided ant build file that can be found in the
-"Axis2Home/samples" directory. Run the "testEchoBlockingClient" target . If
-you can see the response OMElement printed in your command line, then you
-have successfully tested the client. </p>
-
-<h4><a name="PingClient">PingClient</a></h4>
-
-<p>In the Web Service "MyService" we had a IN-ONLY operation with the name
-"ping" (see <a href="userguide2.html#Web_Services_Using_Axis2">Web Services
-Using Axis2</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 bock 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 a IN-ONLY operation we can directly use the
-"fireAndForget()" in ServiceClient to invoke this operation , and that will
-not block the invocation, hence it will return the control immediately back
-to the client. You can test this client by running the target
-"testPingClient" of the ant build file at "Axis2Home/samples".</p>
-
-<p>We have invoked the two operations in our service. Are we done? No! There
-are lot more to explore. Let's see some other ways to invoke the same
-operations...</p>
-
-<h4><a name="EchoNonBlockingClient">EchoNonBlockingClient</a></h4>
-
-<p>In the EchoBlockingClient once the "serviceCleint.sendReceive(payload);"
-is called, the client is blocked till the operation is completed. This
-behavior is not desirable when there are many Web Service invocations to be
-done in a single client application. A solution would be to use a
-Non-Blocking API to invoke web services. Axis2 provides a callback based
-non-blocking API for users.</p>
-
-<p>A sample client for this can be found under
-"Axis2Home/samples/userguide/src/userguide/clients" with the name
-EchoNonBlockingClient. If we consider the changes that user 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. 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
-invocations and provides the user with the flexibility to use Non Blocking
-API for Web Service Clients.</p>
-
-<p>To run the sample client ( EchoNonBlockingClient) you can simply use the
-"testEchoNonBlockingClient" target of the ant file found at the
-"Axis2Home/samples" directory.</p>
-
-<h4><a name="EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></h4>
-
-<p>The solution provided by the Non-Blocking API has one limitation when it
-comes to Web Service invocations which takes long time to complete. The
-limitation is due to the use of single transport connection to invoke the Web
-Service and to retrieve the response. In other words, client API provides a
-non blocking invocation mechanism for the users, but the request and the
-response comes in a single transport (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/Submission/ws-addressing/"
-target="_blank">WS-Addressing</a> provides a neat solution to this using
-<wsa:MessageID> and <wsa:RelatesTo> headers. Axis2 provides
-support for addressing based correlation mechanism and a complying Client
-API to invoke Web Services with two transport connections. (Core of Axis2
-does not depend on WS-Addressing, but contains a set of parameters like in
-addressing that can be populated in any means. WS-Addressing is one of the
-users that may populate them. Even the transports can populate these. Hence
-Axis2 has the flexibility to use different versions of addressing)</p>
-
-<p>Users can select between Blocking or Non-Blocking APIs for the Web Service
-clients with two transport connections. By simply using a boolean flag, the
-same API can be used to invoke web services (IN-OUT operations) using two
-separate transport connections. Let's see how it's done using an example.
-Following code fragment shows how to invoke the same "echo" operation using
-Non-Blocking API with two transport connections<strong>. The ultimate
-asynchrony!!</strong></p>
-<pre> try {
- OMElement payload = ClientUtil.getEchoOMElement();
- Options options = new Options();<br> options.setTo(targetEPR);
-
- //The boolean flag informs the axis2 engine to use two separate transport connection
- //to retrieve the response.
-<br> options.setUseSeparateListener(true);
- options.setAction("urn:echo");
-
- ServiceClient serviceClinet = new ServiceClinet();
-<br> serviceClinet.setOptions(options);</pre>
-<pre>
- //Callback to handle the response
- Callback callback = new Callback() {
- public void onComplete(AsyncResult result) {
- try {
- StringWriter writer = new StringWriter();
- result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance()
- .createXMLStreamWriter(writer)));
- writer.flush();
-
- System.out.println(writer.toString());
-
- } catch (XMLStreamException e) {
- onError(e);
- }
- }
-
- public void onError(Exception e) {
- e.printStackTrace();
- }
- };
-
- //Non-Blocking Invocation
- serviceClinet.sendReceiveNonBlocking(payload, callback);
-
- //Wait till the callback receives the response.
- while (!callback.isComplete()) {
- Thread.sleep(1000);
- }
- serviceClinet.finalizeInvoke();
-
- } catch (AxisFault axisFault) {
- axisFault.printStackTrace();
- } catch (Exception ex) {
- ex.printStackTrace();
- }</pre>
-
-<p><font color="#0000ff"><font color="#000000">The boolean flag (value true)
-in the "<b>options.setUseSeparateListener(...)</b>" method informs the Axis2
-engine to use separate transport connections for request and response.
-Finally "<b>serviceClinet.finalizeInvoke()</b>" informs the Axis2 engine to
-stop the client side listener started to retrieve the
-response.</font></font></p>
-
-<p>Before we run the sample client we have one more step to perform. As
-mentioned earlier Axis2 uses addressing based correlation mechanism, hence we
-need to "engage" addressing module in the server side as well. According to
-the Axis2 architecture, addressing module put its handlers in the
-"<strong>pre-dispatch</strong>" phase (See <a
-href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
-more details about phases) and hence "engaging" means simply adding module
-reference in the "axis2.xml" (NOT the "services.xml"). Now add the following
-line to the "axis2.xml" that you can find in the "/webapps/axis2/WEB-INF"
-directory in the servlet container. </p>
-<pre style="margin-bottom: 0.2in"> <module ref="addressing"/></pre>
-
-<p>Note: <font color="#000000">Once you change the "axis2.xml" you need to
-restart the servlet container.</font></p>
-
-<p>This will enable the addressing in the server side. Now you can test the
-"TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
-target of the ant file found at "Axis2Home/samples" directory. If you see the
-response OMElement printed in the client side, then you have successfully
-tested the Non Blocking API with two transport channels at the client
-side.</p>
-
-<h4><a name="EchoBlockingDualClient">EchoBlockingDualClient</a></h4>
-
-<p>This is again a Two-Way transport request/response client, but this time,
-we use a Blocking API in the client code. Sample code for this can be found
-in the "Axis2Home/samples/userguide/src/userguide/clients/" directory and the
-explanation is similar to the <a
-href="#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a>, except that
-here we do not use a callback object to handle response. This is a very
-useful mechanism when the service invocation is IN-OUT in nature and the
-transports are One-Way (e.g. SMTP). For the sample client we use two HTTP
-connections for request and response. User can test this client using the
-"echoBlockingDualClient" target of the ant build file found in the
-"Axis2Home/samples" directory.</p>
-
-<p>See <a href="http-transport.html" target="_blank">Configuring
-Transports</a> for use different transports.</p>
-
-<h3><a
-name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
-Web Service Clients using Code Generation with Data Binding Support</a></h3>
-
-<p>Axis2 provides the data binding support for Web Service client as well.
-The user can generate the required stubs from a given WSDL with the other
-supporting classes. Let's generate stubs for the WSDL used earlier to
-generate the skeleton for the "Axis2SampleDocLitPortType". Simply run the
-WSDL2Java tool that can be found in the bin directory of the Axis2
-distribution using the following command:</p>
-<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide</pre>
-
-<p>This will generate the required stub "Axis2SampleDocLitPortTypeStub.java"
-that can be used to invoke the Web Service Axis2SampleDocLitPortType. Let's
-see how we can use this stub to write Web Service clients to utilize the Web
-Service Axis2SampleDocLitPortType (the service that we have already
-deployed).</p>
-
-<h4><a name="Client_for_echoVoid_Operation">Client for echoVoid
-Operation</a></h4>
-
-<p>Following code fragment shows the necessary code for utilizing the
-echoVoid operation of the Axis2SampleDocLitPortType that we have already
-deployed. In this operation, a blank SOAP body element is sent to the Web
-Service and the same SOAP envelope is echoed back.</p>
-<pre> try {
- //Create the stub by passing the AXIS_HOME and target EPR.
- //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
- Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
- stub.echoVoid();
-
-} catch (Exception e) {
- e.printStackTrace();
-}</pre>
-
-<h4><a name="Client_for_echoString_Operation">Client for echoString
-Operation</a></h4>
-
-<p>Following code fragment shows the necessary code for utilizing the
-echoString operation of the Axis2SampleDocLitPortType that we have already
-deployed. The code is very simple to understand and the explanations are in
-the form of comments.</p>
-<pre>try {
- //Create the stub by passing the AXIS_HOME and target EPR.
- //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
- Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
- //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>Similarly following code fragments show client side code for
-echoStringArray operation and echoStruct operation respectively.</p>
-
-<h4><a name="Client_for_echoStringArray_Operation">Client for echoStringArray
-Operation</a></h4>
-<pre>try {
- //Create the stub by passing the AXIS_HOME and target EPR.
- //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
- Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
-
- //Create the request document to be sent.
- EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
- ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
-
- paramArray.addString("Axis2");
- paramArray.addString("Echo");
-
- reqDoc.setEchoStringArrayParam(paramArray);
- EchoStringArrayReturnDocument resDoc = stub.echoStringArray(reqDoc);
-
- //Get the response params
- String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
-
- for (int i = 0; i < resParams.length; i++) {
- System.out.println(resParams[i]);
- }
- } catch (Exception e) {
- e.printStackTrace();
- }</pre>
-
-<h4><a name="Client_for_echoStruct_Operation">Client for echoStruct
-Operation</a></h4>
-<pre>try {
- //Create the stub by passing the AXIS_HOME and target EPR.
- //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
- Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
- "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
- //Create the request Document
- EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
-
- //Create the complex type
- SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
-
- reqStruct.setVarFloat(100.50F);
- reqStruct.setVarInt(10);
- reqStruct.setVarString("High");
-
- reqDoc.setEchoStructParam(reqStruct);
-
- //Service invocation
- EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
- SOAPStruct resStruct = resDoc.getEchoStructReturn();
-
- System.out.println("floot Value :" + resStruct.getVarFloat());
- System.out.println("int Value :" + resStruct.getVarInt());
- System.out.println("String Value :" + resStruct.getVarString());
-
-} catch (Exception e) {
- e.printStackTrace();
-}</pre>
-
-<p align="right"><a href="userguide2.html"><img src="images/arrow_left.gif">
-Previous</a> | <a href="userguide4.html">Next <img
-src="images/arrow_right.gif"></a></p>
-
-<p>Pages: <a href="userguide.html">Content</a>, <a
-href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <b>3</b>, <a
-href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
-</body>
-</html>
+<!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 User's Guide</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<p><i>Version 1.0</i></p>
+
+<p><i>User Feedback: <a
+href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></i>. Prefix
+subject with [Axis2]. To subscribe to mailing list see
+<a href="http://ws.apache.org/axis2/mail-lists.html">here.</p>
+
+<p align="right">Pages: <a href="userguide.html">Content</a>, <a
+href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <b>3</b>, <a
+href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
+
+<p><b><font size="4">Note (on samples):</font></b> In this page of the user's
+guide we will look at how to write Web Service Clients using Axis2. All the
+user's guide samples are located at the <b><font
+color="#000000">"samples/userguide/src"</font></b> directory of the binary
+distribution. So... let's explore the samples.</p>
+
+<h2><a name="Web_Service_Clients_Using_Axis2">Web Service Clients Using
+Axis2</a></h2>
+
+<p>Now let's see how we can write a Web Service Client to use this Web
+Service.</p>
+
+<p>Web services can be used to provide wide range of functionality to the
+users ranging from simple, less time consuming operations such as
+"getStockQuote" to time consuming business services. When we utilize (invoke
+using client applications) these Web Service we cannot use some simple
+generic invocation paradigm that suites all the timing complexities involved
+in the service operations. For example, if we use a single transport channel
+(such as HTTP) to invoke a Web Service with and IN-OUT operation that take
+long time to complete, then most of the time 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 in to play when we need them. Let's try to analyze some common
+service invocation paradigms.</p>
+
+<p>Many web service engines provide the users with a Blocking and
+Non-Blocking client APIs.</p>
+<ul>
+ <li><p style="margin-bottom: 0in"><b>Blocking API</b> -Once the service
+ invocation is called, the client application hangs and only gets control
+ back when the operation completes, after which client receives a response
+ or a fault. This is the simplest way of invoking Web Services and it also
+ suites many business situations.</p>
+ </li>
+ <li><p><b>Non-Blocking API </b>- This is a callback or polling based API,
+ hence once a service invocation is called, the client application
+ immediately gets the control back and the response is retrieved using the
+ callback object provided. This approach provides the flexibility to the
+ client application to invoke several Web Services simultaneously without
+ blocking the operation already invoked.</p>
+ </li>
+</ul>
+
+<p>Both these mechanisms work in the API level. Let's name the asynchronous
+behavior that we can get using the <strong>Non-Blocking API</strong> as
+<b>API Level Asynchrony.</b></p>
+
+<p>Both these mechanisms use single transport connection to send the request
+and to receive the response. They severely lags the capability of using two
+transport connections for the request and the response (either One-Way of
+Two-Way). So both 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 <strong>two
+separate transport connections for request and response</strong>. The
+asynchronous behavior that we gain using this solution can be called
+<b>Transport Level Asynchrony</b>.</p>
+
+<p>By combining API Level Asynchrony & Transport Level Asynchrony 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>Simplest and the 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. No blocking in the API level and also in the transport
+ level</p>
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Axis2 provides the user with all these possibilities to invoke Web
+Services.</p>
+
+<p>Below we describe how to write Web Services Clients using Axis2. This can
+be done in two methods:</p>
+<ol>
+ <li><a href="#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Using
+ the Axis2's primary APIs</a></li>
+ <li><p><a
+ href="#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Using
+ stubs generated with data binding support</a>, making the life easy for
+ developers writing Web Service client applications</p>
+ </li>
+</ol>
+
+<h3><a name="Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
+Web Service Clients Using Axis2's Primary APIs</a></h3>
+
+<h4><a name="EchoBlockingClient">EchoBlockingClient</a></h4>
+
+<p>Axis2 provides the user with several invocation patterns for Web Services,
+ranging from pure blocking single channel invocations to a non-blocking dual
+channel invocations. Let's first see how we can write a client to invoke
+"echo" operation of "MyService" using the simplest blocking invocation. The
+client code you need to write is as follows.</p>
+<source><pre> try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+ <span style="color: #24C113">
+ Options options = new Options();
+ options.setTo(targetEPR);
+ options.setListenerTransportProtocol(Constants.TRANSPORT_HTTP);
+ options.setUseSeparateListener(false);
+
+ ServiceClient serviceClient = new ServiceClient();
+ serviceClient.setOptions(options);
+
+ OMElement result = sender.sendReceive(payload);
+ </span>
+ StringWriter writer = new StringWriter();
+ result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance().createXMLStreamWriter(writer)));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (XMLStreamException e) {
+ e.printStackTrace();
+ }
+}</pre>
+</source>
+<p>The green lines shows the set of operations that you need to perform
+inorder to invoke a web service. The rest is used to create the OMElement
+that needs to be sent and display the response OMElement. To test this
+client, use the provided ant build file that can be found in the
+"Axis2Home/samples" directory. Run the "testEchoBlockingClient" target . If
+you can see the response OMElement printed in your command line, then you
+have successfully tested the client. </p>
+
+<h4><a name="PingClient">PingClient</a></h4>
+
+<p>In the Web Service "MyService" we had a IN-ONLY operation with the name
+"ping" (see <a href="userguide2.html#Web_Services_Using_Axis2">Web Services
+Using Axis2</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 bock 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 a IN-ONLY operation we can directly use the
+"fireAndForget()" in ServiceClient to invoke this operation , and that will
+not block the invocation, hence it will return the control immediately back
+to the client. You can test this client by running the target
+"testPingClient" of the ant build file at "Axis2Home/samples".</p>
+
+<p>We have invoked the two operations in our service. Are we done? No! There
+are lot more to explore. Let's see some other ways to invoke the same
+operations...</p>
+
+<h4><a name="EchoNonBlockingClient">EchoNonBlockingClient</a></h4>
+
+<p>In the EchoBlockingClient once the "serviceCleint.sendReceive(payload);"
+is called, the client is blocked till the operation is completed. This
+behavior is not desirable when there are many Web Service invocations to be
+done in a single client application. A solution would be to use a
+Non-Blocking API to invoke web services. Axis2 provides a callback based
+non-blocking API for users.</p>
+
+<p>A sample client for this can be found under
+"Axis2Home/samples/userguide/src/userguide/clients" with the name
+EchoNonBlockingClient. If we consider the changes that user 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. 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
+invocations and provides the user with the flexibility to use Non Blocking
+API for Web Service Clients.</p>
+
+<p>To run the sample client ( EchoNonBlockingClient) you can simply use the
+"testEchoNonBlockingClient" target of the ant file found at the
+"Axis2Home/samples" directory.</p>
+
+<h4><a name="EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></h4>
+
+<p>The solution provided by the Non-Blocking API has one limitation when it
+comes to Web Service invocations which takes long time to complete. The
+limitation is due to the use of single transport connection to invoke the Web
+Service and to retrieve the response. In other words, client API provides a
+non blocking invocation mechanism for the users, but the request and the
+response comes in a single transport (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/Submission/ws-addressing/"
+target="_blank">WS-Addressing</a> provides a neat solution to this using
+<wsa:MessageID> and <wsa:RelatesTo> headers. Axis2 provides
+support for addressing based correlation mechanism and a complying Client
+API to invoke Web Services with two transport connections. (Core of Axis2
+does not depend on WS-Addressing, but contains a set of parameters like in
+addressing that can be populated in any means. WS-Addressing is one of the
+users that may populate them. Even the transports can populate these. Hence
+Axis2 has the flexibility to use different versions of addressing)</p>
+
+<p>Users can select between Blocking or Non-Blocking APIs for the Web Service
+clients with two transport connections. By simply using a boolean flag, the
+same API can be used to invoke web services (IN-OUT operations) using two
+separate transport connections. Let's see how it's done using an example.
+Following code fragment shows how to invoke the same "echo" operation using
+Non-Blocking API with two transport connections<strong>. The ultimate
+asynchrony!!</strong></p>
+<pre> try {
+ OMElement payload = ClientUtil.getEchoOMElement();
+ Options options = new Options();<br> options.setTo(targetEPR);
+
+ //The boolean flag informs the axis2 engine to use two separate transport connection
+ //to retrieve the response.
+<br> options.setUseSeparateListener(true);
+ options.setAction("urn:echo");
+
+ ServiceClient serviceClinet = new ServiceClinet();
+<br> serviceClinet.setOptions(options);</pre>
+<pre>
+ //Callback to handle the response
+ Callback callback = new Callback() {
+ public void onComplete(AsyncResult result) {
+ try {
+ StringWriter writer = new StringWriter();
+ result.serializeWithCache(new OMOutput(XMLOutputFactory.newInstance()
+ .createXMLStreamWriter(writer)));
+ writer.flush();
+
+ System.out.println(writer.toString());
+
+ } catch (XMLStreamException e) {
+ onError(e);
+ }
+ }
+
+ public void onError(Exception e) {
+ e.printStackTrace();
+ }
+ };
+
+ //Non-Blocking Invocation
+ serviceClinet.sendReceiveNonBlocking(payload, callback);
+
+ //Wait till the callback receives the response.
+ while (!callback.isComplete()) {
+ Thread.sleep(1000);
+ }
+ serviceClinet.finalizeInvoke();
+
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ }</pre>
+
+<p><font color="#0000ff"><font color="#000000">The boolean flag (value true)
+in the "<b>options.setUseSeparateListener(...)</b>" method informs the Axis2
+engine to use separate transport connections for request and response.
+Finally "<b>serviceClinet.finalizeInvoke()</b>" informs the Axis2 engine to
+stop the client side listener started to retrieve the
+response.</font></font></p>
+
+<p>Before we run the sample client we have one more step to perform. As
+mentioned earlier Axis2 uses addressing based correlation mechanism, hence we
+need to "engage" addressing module in the server side as well. According to
+the Axis2 architecture, addressing module put its handlers in the
+"<strong>pre-dispatch</strong>" phase (See <a
+href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
+more details about phases) and hence "engaging" means simply adding module
+reference in the "axis2.xml" (NOT the "services.xml"). Now add the following
+line to the "axis2.xml" that you can find in the "/webapps/axis2/WEB-INF"
+directory in the servlet container. </p>
+<pre style="margin-bottom: 0.2in"> <module ref="addressing"/></pre>
+
+<p>Note: <font color="#000000">Once you change the "axis2.xml" you need to
+restart the servlet container.</font></p>
+
+<p>This will enable the addressing in the server side. Now you can test the
+"TestEchoNonBlockingDualClient" using the "testEchoNonBlockingDualClient"
+target of the ant file found at "Axis2Home/samples" directory. If you see the
+response OMElement printed in the client side, then you have successfully
+tested the Non Blocking API with two transport channels at the client
+side.</p>
+
+<h4><a name="EchoBlockingDualClient">EchoBlockingDualClient</a></h4>
+
+<p>This is again a Two-Way transport request/response client, but this time,
+we use a Blocking API in the client code. Sample code for this can be found
+in the "Axis2Home/samples/userguide/src/userguide/clients/" directory and the
+explanation is similar to the <a
+href="#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a>, except that
+here we do not use a callback object to handle response. This is a very
+useful mechanism when the service invocation is IN-OUT in nature and the
+transports are One-Way (e.g. SMTP). For the sample client we use two HTTP
+connections for request and response. User can test this client using the
+"echoBlockingDualClient" target of the ant build file found in the
+"Axis2Home/samples" directory.</p>
+
+<p>See <a href="http-transport.html" target="_blank">Configuring
+Transports</a> for use different transports.</p>
+
+<h3><a
+name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
+Web Service Clients using Code Generation with Data Binding Support</a></h3>
+
+<p>Axis2 provides the data binding support for Web Service client as well.
+The user can generate the required stubs from a given WSDL with the other
+supporting classes. Let's generate stubs for the WSDL used earlier to
+generate the skeleton for the "Axis2SampleDocLitPortType". Simply run the
+WSDL2Java tool that can be found in the bin directory of the Axis2
+distribution using the following command:</p>
+<pre style="margin-bottom: 0.2in">WSDL2Java -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -o ..\samples\src -p org.apache.axis2.userguide</pre>
+
+<p>This will generate the required stub "Axis2SampleDocLitPortTypeStub.java"
+that can be used to invoke the Web Service Axis2SampleDocLitPortType. Let's
+see how we can use this stub to write Web Service clients to utilize the Web
+Service Axis2SampleDocLitPortType (the service that we have already
+deployed).</p>
+
+<h4><a name="Client_for_echoVoid_Operation">Client for echoVoid
+Operation</a></h4>
+
+<p>Following code fragment shows the necessary code for utilizing the
+echoVoid operation of the Axis2SampleDocLitPortType that we have already
+deployed. In this operation, a blank SOAP body element is sent to the Web
+Service and the same SOAP envelope is echoed back.</p>
+<pre> try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ stub.echoVoid();
+
+} catch (Exception e) {
+ e.printStackTrace();
+}</pre>
+
+<h4><a name="Client_for_echoString_Operation">Client for echoString
+Operation</a></h4>
+
+<p>Following code fragment shows the necessary code for utilizing the
+echoString operation of the Axis2SampleDocLitPortType that we have already
+deployed. The code is very simple to understand and the explanations are in
+the form of comments.</p>
+<pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub= new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ //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>Similarly following code fragments show client side code for
+echoStringArray operation and echoStruct operation respectively.</p>
+
+<h4><a name="Client_for_echoStringArray_Operation">Client for echoStringArray
+Operation</a></h4>
+<pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+
+ //Create the request document to be sent.
+ EchoStringArrayParamDocument reqDoc = EchoStringArrayParamDocument.Factory.newInstance();
+ ArrayOfstringLiteral paramArray = ArrayOfstringLiteral.Factory.newInstance();
+
+ paramArray.addString("Axis2");
+ paramArray.addString("Echo");
+
+ reqDoc.setEchoStringArrayParam(paramArray);
+ EchoStringArrayReturnDocument resDoc = stub.echoStringArray(reqDoc);
+
+ //Get the response params
+ String[] resParams = resDoc.getEchoStringArrayReturn().getStringArray();
+
+ for (int i = 0; i < resParams.length; i++) {
+ System.out.println(resParams[i]);
+ }
+ } catch (Exception e) {
+ e.printStackTrace();
+ }</pre>
+
+<h4><a name="Client_for_echoStruct_Operation">Client for echoStruct
+Operation</a></h4>
+<pre>try {
+ //Create the stub by passing the AXIS_HOME and target EPR.
+ //We pass null to the AXIS_HOME and hence the stub will use the current directory as the AXIS_HOME
+ Axis2SampleDocLitPortTypeStub stub = new Axis2SampleDocLitPortTypeStub(null,
+ "http://localhost:8080/axis2/services/Axis2SampleDocLitPortType");
+ //Create the request Document
+ EchoStructParamDocument reqDoc = EchoStructParamDocument.Factory.newInstance();
+
+ //Create the complex type
+ SOAPStruct reqStruct = SOAPStruct.Factory.newInstance();
+
+ reqStruct.setVarFloat(100.50F);
+ reqStruct.setVarInt(10);
+ reqStruct.setVarString("High");
+
+ reqDoc.setEchoStructParam(reqStruct);
+
+ //Service invocation
+ EchoStructReturnDocument resDoc = stub.echoStruct(reqDoc);
+ SOAPStruct resStruct = resDoc.getEchoStructReturn();
+
+ System.out.println("floot Value :" + resStruct.getVarFloat());
+ System.out.println("int Value :" + resStruct.getVarInt());
+ System.out.println("String Value :" + resStruct.getVarString());
+
+} catch (Exception e) {
+ e.printStackTrace();
+}</pre>
+
+<p align="right"><a href="userguide2.html"><img src="images/arrow_left.gif">
+Previous</a> | <a href="userguide4.html">Next <img
+src="images/arrow_right.gif"></a></p>
+
+<p>Pages: <a href="userguide.html">Content</a>, <a
+href="userguide1.html">1</a>, <a href="userguide2.html">2</a>, <b>3</b>, <a
+href="userguide4.html">4</a>, <a href="userguide5.html">5</a></p>
+</body>
+</html>