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/10/05 10:29:59 UTC
svn commit: r453140 -
/webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html
Author: chatra
Date: Thu Oct 5 01:29:58 2006
New Revision: 453140
URL: http://svn.apache.org/viewvc?view=rev&rev=453140
Log:
more updates
Modified:
webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html
Modified: webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html?view=diff&rev=453140&r1=453139&r2=453140
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/userguide-new.html Thu Oct 5 01:29:58 2006
@@ -17,53 +17,46 @@
<h2>Content</h2>
<ul>
- <li><p><a href="userguide1.html#Axis2_User's_Guide">Introduction</a></p>
+ <li><p><a href="#Introduction">Introduction</a></p>
</li>
- <li><p><a href="userguide2.html#Axis2_User's_Guide">Web Services Using
- Axis2</a></p>
+ <li><p><a href="#Web_Services_Using_Axis2">Web Services Using Axis2</a></p>
<ul>
- <li><a href="userguide2.html#Getting_started">Getting Started</a></li>
- <li><a
- href="userguide2.html#Writing_Web_Services_Using Axis2's_Primary_APIs">Writing
+ <li><a href="#Getting_started">Getting Started</a></li>
+ <li><a href="#Writing_Web_Services_Using Axis2's_Primary_APIs">Writing
Web Services using Axis2 APIs</a>
<ul>
- <li><a href="userguide2.html#How_to_write_the_Web_Service_">How to
- write the Web Service?</a>
+ <li><a href="#How_to_write_the_Web_Service_">How to write the Web
+ Service?</a>
<ul>
- <li><a
- href="userguide2.html#Step1_:Write_the_Implementation_Class">Step1
+ <li><a href="#Step1_:Write_the_Implementation_Class">Step1
:Write the Implementation Class</a></li>
- <li><a
- href="userguide2.html#Step2_:Write_the_services_xml_file">Step2
- :Write the services.xml file</a></li>
- <li><a
- href="userguide2.html#Step3_:Create_the_Web_Service_Archive">Step3
+ <li><a href="#Step2_:Write_the_services_xml_file">Step2 :Write
+ the services.xml file</a></li>
+ <li><a href="#Step3_:Create_the_Web_Service_Archive">Step3
:Create the Web Service Archive</a></li>
- <li><a
- href="userguide2.html#Step4_:Deploy_the_Web_Service">Step4
- :Deploy the Web Service</a></li>
+ <li><a href="#Step4_:Deploy_the_Web_Service">Step4 :Deploy the
+ Web Service</a></li>
</ul>
</li>
</ul>
</li>
<li><p><a
- href="userguide2.html#Writing_Web_Services_by_Code_Generating_Skeleton">Writing
- Web Services by Code Generating Skeleton</a></p>
+ href="#Writing_Web_Services_by_Code_Generating_Skeleton">Writing Web
+ Services by Code Generating Skeleton</a></p>
<ul>
- <li><a href="userguide2.html#How_to_write_the_Web_Service_2">How to
- write the Web Service?</a>
+ <li><a href="#How_to_write_the_Web_Service_2">How to write the Web
+ Service?</a>
<ul>
- <li><a href="userguide2.html#Step1_:Generate_skeleton">Step 1:
- Generate Skeleton Code</a></li>
- <li><a
- href="userguide2.html#Step2_Implement_Business_Logic">Step2
- :Implement Business Logic</a></li>
- <li><a href="userguide2.html#Step3_:Verify_services_xml">Step3
- :Verify services.xml file</a></li>
- <li><a href="userguide2.html#Step4_Create_archive">Step4
- :Create the Web Service Archive file</a></li>
- <li><a href="userguide2.html#Step5_Deploy_web_service">Step5
- :Deploy the Web Service</a></li>
+ <li><a href="#Step1_:Generate_skeleton">Step 1: Generate
+ Skeleton Code</a></li>
+ <li><a href="#Step2_Implement_Business_Logic">Step2 :Implement
+ Business Logic</a></li>
+ <li><a href="#Step3_:Verify_services_xml">Step3 :Verify
+ services.xml file</a></li>
+ <li><a href="#Step4_Create_archive">Step4 :Create the Web
+ Service Archive file</a></li>
+ <li><a href="#Step5_Deploy_web_service">Step5 :Deploy the Web
+ Service</a></li>
</ul>
</li>
</ul>
@@ -72,78 +65,64 @@
</li>
</ul>
<ul>
- <li><p><a href="userguide3.html#Axis2_User's_Guide">Web Service Clients
- Using Axis2</a></p>
+ <li><p><a href="#Axis2_User's_Guide">Web Service Clients Using Axis2</a></p>
<ul>
<li><a
- href="userguide3.html#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
+ href="#Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">Writing
Web Service Clients using Axis2's Primary APIs</a>
<ul>
+ <li><a href="#EchoBlockingClient">EchoBlockingClient</a></li>
+ <li><a href="#PingClient">PingClient</a></li>
+ <li><a href="#EchoNonBlockingClient">EchoNonBlockingClient</a></li>
<li><a
- href="userguide3.html#EchoBlockingClient">EchoBlockingClient</a></li>
- <li><a href="userguide3.html#PingClient">PingClient</a></li>
- <li><a
- href="userguide3.html#EchoNonBlockingClient">EchoNonBlockingClient</a></li>
+ href="#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></li>
<li><a
- href="userguide3.html#EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></li>
- <li><a
- href="userguide3.html#EchoBlockingDualClient">EchoBlockingDualClient</a></li>
+ href="#EchoBlockingDualClient">EchoBlockingDualClient</a></li>
</ul>
</li>
<li><p><a
- href="userguide3.html#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
+ href="#Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">Writing
Web Service Clients using Code Generation with Data Binding
Support</a></p>
<ul>
- <!--<li><a href="userguide3.html#Client_for_echoVoid_Operation">Client
+ <!--<li><a href="#Client_for_echoVoid_Operation">Client
for echoVoid Operation</a></li>-->
- <li><a
- href="userguide3.html#Client_for_echoString_Operation">Client for
+ <li><a href="#Client_for_echoString_Operation">Client for
echoString Operation</a></li>
- <li><a
- href="userguide3.html#Client_for_echoStringArray_Operation">Client
- for echoStringArray Operation</a></li>
- <li><a
- href="userguide3.html#Client_for_echoStruct_Operation">Client for
+ <li><a href="#Client_for_echoStringArray_Operation">Client for
+ echoStringArray Operation</a></li>
+ <li><a href="#Client_for_echoStruct_Operation">Client for
echoStruct Operation</a></li>
</ul>
</li>
</ul>
</li>
- <li><p><a href="userguide4.html#Axis2_User's_Guide">Modules</a></p>
+ <li><p><a href="#Axis2_User's_Guide">Modules</a></p>
<ul>
- <li><a href="userguide4.html#MyService_with_a_Logging_Module">MyService
- with a Logging Module</a>
+ <li><a href="#MyService_with_a_Logging_Module">MyService with a Logging
+ Module</a>
<ul>
- <li><a href="userguide4.html#Step1_:_LoggingModule_Class">Step1 :
- LoggingModule Class</a></li>
- <li><a href="userguide4.html#Step2_:_LogHandler">Step2 :
- LogHandler</a></li>
- <li><a href="userguide4.html#Step3_:_module_xml">Step3 :
- module.xml</a></li>
- <li><a
- href="userguide4.html#Step_4:_Modify_the_"axis2_xml"">Step
- 4: Modify the "axis2.xml"</a></li>
- <li><a
- href="userguide4.html#Step5_:_Modify_the_"services_xml"">Step5
- : Modify the "services.xml"</a></li>
- <li><a href="userguide4.html#Step6_:_Packaging">Step6 :
- Packaging</a></li>
- <li><a
- href="userguide4.html#Step7_:_Deploy_the_Module_in_Axis2">Step7 :
- Deploy the Module in Axis2</a></li>
+ <li><a href="#Step1_:_LoggingModule_Class">Step1 : LoggingModule
+ Class</a></li>
+ <li><a href="#Step2_:_LogHandler">Step2 : LogHandler</a></li>
+ <li><a href="#Step3_:_module_xml">Step3 : module.xml</a></li>
+ <li><a href="#Step_4:_Modify_the_"axis2_xml"">Step 4:
+ Modify the "axis2.xml"</a></li>
+ <li><a href="#Step5_:_Modify_the_"services_xml"">Step5 :
+ Modify the "services.xml"</a></li>
+ <li><a href="#Step6_:_Packaging">Step6 : Packaging</a></li>
+ <li><a href="#Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy
+ the Module in Axis2</a></li>
</ul>
</li>
</ul>
</li>
- <li><p><a href="userguide5.html#Axis2_User's_Guide">Other Samples</a></p>
+ <li><p><a href="#Axis2_User's_Guide">Other Samples</a></p>
<ul>
- <li><a href="userguide5.html#Google_Spell_Checker_Sample">Google Spell
- Checker Sample</a></li>
- <li><a href="userguide5.html#Google_Search_Sample">Google Search
+ <li><a href="#Google_Spell_Checker_Sample">Google Spell Checker
Sample</a></li>
- <li><a href="userguide5.html#Amazon_Queuing_Service">Amazon Queuing
- Service</a></li>
+ <li><a href="#Google_Search_Sample">Google Search Sample</a></li>
+ <li><a href="#Amazon_Queuing_Service">Amazon Queuing Service</a></li>
</ul>
</li>
<li><p>Advanced Topics</p>
@@ -188,7 +167,7 @@
<p>In this section, we will learn how to write and deploy Web services using
Axis2. All the samples mentioned in this giude are located in the
<b>"samples\userguide\src"</b> directory of <a
-href="../download/1_1/download.html/#std-bin">Axis2 binary
+href="../download/1_1/download.html/#std-bin">Axis2 standard binary
distribution</a>.</p>
<h3><a name="Getting_started">Getting Started</a></h3>
@@ -211,7 +190,8 @@
<p>The complete code of the example Web service - MyService which will be
used in this exercise is found in the "Axis2_HOME/samples/userguide/src"
-directory under "userguide/example1" package.</p>
+directory of Axis2 binary distribution, under "userguide/example1"
+package.</p>
<h3><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">1. Writing Web
Services Using Axis2's Primary APIs</a></h3>
@@ -243,6 +223,10 @@
implements the operations provided by the Web service. Unless you have data
binding, the signature of the methods can have only one parameter of type
OMElement.</p>
+
+<p><span style="color: #FF0000">OMElement is .... </span>For more details see
+<a href="http://ws.apache.org/commons/axiom/OMTutorial.html">OM
+Tutorial</a>.</p>
<pre>public class MyService{
public void ping(OMElement element){
// Business Logic
@@ -276,17 +260,17 @@
<p><em>The above XML tags can be explained as follows:</em></p>
-<p>The description of the service class is provided in the description
+<p>1. The description of the service class is provided in the description
tag.</p>
<pre><service >
<description>
This is a sample Web service with two operations, echo and ping.
</description></pre>
-<p>The name of the service class is provided as a parameter.</p>
+<p>2. The name of the service class is provided as a parameter.</p>
<pre><parameter name="serviceClass" locked="false">userguide.example1.MyService</parameter></pre>
-<p>The "operation" xml tag describes the operations that are available in
+<p>3. The "operation" xml tag describes the operations that are available in
this service with respective message receivers.</p>
<pre> <operation name="echo">
<messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
@@ -297,22 +281,23 @@
<actionMapping>urn:ping</actionMapping>
</operation></pre>
-<p>Every operation must map to a corresponding MessageReceiver class. After a
-message is processed by the handlers, Axis2 engine hands it over to a
-MessageReceiver. <br>
-For the "echo" operation, we have used a
+<p>4. Every operation must map to a corresponding MessageReceiver class.
+After a message is processed by the handlers, Axis2 engine hands it over to a
+MessageReceiver.</p>
+
+<p>5. 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>The actionMapping is required only if you want to enable WS-Addressing.
+<p>6. The actionMapping is required only if you want to enable WS-Addressing.
This will be used later in this user guide.</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 the
+<p>7. 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 the
following format.</p>
<pre><serviceGroup>
<service name="Service1">
@@ -327,7 +312,7 @@
<p>Note : name of the service is a compulsory attribute.</p>
-<h4><a name="Step3_:Create_the_Web_Service_Archive">Step3 :Create the Web
+<h4><a name="Step3_:Create_the_Web_Service_Archive">Step3 : Create the Web
Service Archive</a></h4>
<p>Axis2 uses ".aar" (Axis Archive) file as the deployment package for Web
@@ -341,16 +326,16 @@
<p>To create the archive file, you can create a jar file containing all the
necessary files and then rename it to .aar file.This archive file can be
-found in the "Axis2Home/samples/userguide" directory. This file now has to be
-deployed.</p>
+found in the "Axis2_HOME/samples/userguide" directory. This file now has to
+be deployed.</p>
-<h4><a name="Step4_:Deploy_the_Web_Service">Step4 :Deploy the Web
+<h4><a name="Step4_:Deploy_the_Web_Service">Step4 : Deploy the Web
Service</a></h4>
<p>The service can be deployed by dropping dropping the ".aar" file in to
-"services" directory in "\webapps\axis2\WEB-INF" of your servlet
-container.Start the servlet container (if you have not already started) and
-check the link "Services" on the <a href="http://localhost:8080/axis2/"
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
+Start the servlet container (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 MyService is deployed
properly. If you can see the following output then you have successfully
@@ -370,8 +355,8 @@
<p>This is the second method of writing Web services using Axis2. In this
method, we generate the skeleton from a given WSDL and implement the business
logic in the classes generated. For this example, we will use
-Axis2SampleDocLit.wsdl. This can be found in the <b>wsdl</b> directory under
-samples.</p>
+Axis2SampleDocLit.wsdl. This can be found in the <b>"samples\wsdl</b>"
+directory of the binary distribution.</p>
<h4><a name="How_to_write_the_Web_Service_2">How to write a Web
Service?</a></h4>
@@ -390,7 +375,7 @@
</li>
</ol>
-<h4><a name="Step1_:Generate_skeleton">Step1 :Generate Skeleton Code</a></h4>
+<h4><a name="Step1_:Generate_skeleton">Step1 : Generate Skeleton Code</a></h4>
<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
@@ -414,28 +399,27 @@
-r <repository_path> : path of the repository against which code is generated</pre>
<p>The parameters for wsdl2java tool in our example are as follows:</p>
+<strong>Windows</strong> <!--<p>Windows users can use the following command in the console:</p> -->
-<h5>Windows</h5>
-<!--<p>Windows users can use the following command in the console:</p> -->
<pre style="margin-bottom: 0.2in">WSDL2Java.bat -uri ..\samples\wsdl\Axis2SampleDocLit.wsdl -ss -sd -d xmlbeans -o ..\samples -p org.apache.axis2.userguide</pre>
+<strong>Linux</strong> <!--<p>Linux users should switch the file separator:</p> -->
-<h5>Linux</h5>
-<!--<p>Linux users should switch the file separator:</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>src</b> directory inside
-samples, and the schema classes in <strong>schemaorg_apache_xmlbeans</strong>
-directory which is inside resources directory and 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>
+<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>
<h4><a name="Step2_Implement_Business_Logic">Step 2: Implement Business
Logic</a></h4>
<p>Implement the business logic in the skeleton class. The skeleton class
"Axis2SampleDocLitServiceSkeleton.java" can be found in
-src/org/apache/axis2/userguide directory. Our sample WSDL has three
-operations: <!--<li><p style="margin-bottom: 0in">echoVoid - Operation that does not
+<strong>"samples/src/org/apache/axis2/userguide</strong>" directory. Our
+sample WSDL-Axis2SampleDocLit.wsdl in <strong>"samples/wsdl"</strong>
+directory 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>-->
@@ -523,11 +507,11 @@
return retDoc;
}</pre>
-<h4><a name="Step3_:Verify_services_xml">Step3 :Verify generated
+<h4><a name="Step3_:Verify_services_xml">Step3 : Verify Generated
services.xml</a></h4>
-<p> As mentioned earlier, "services.xml" file holds all the configuration
-informatinn for for a webservice. When the skeleton is generated using the
+<p>As mentioned earlier, "services.xml" file holds all the configuration
+information for a Web service. When the skeleton is generated using the
WSDL2Java tool, the services.xml file is also generated. This file can be
found in the same directory as the skeleton. The generated services.xml is as
follows.</p>
@@ -553,22 +537,24 @@
</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 following xml tags describe the
-operations that are available in this service with respective message
-receivers.</p>
+<p>1. 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.</p>
-<h4><a name="Step4_Create_archive">Step 4: Create Archive file</a></h4>
+<p>2. Next comes the description and the service class.</p>
+
+<p>3. The following xml tags describe the operations that are available in
+this service with respective message receivers.</p>
+
+<h4><a name="Step4_Create_archive">Step 4: Create Archive File</a></h4>
<p>The next step is to package the classes in an .aar (axis2 archive) and
deploy it in Axis2. When the WSDL2Java tool generates 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. To create the .aar
-file, create the following directory structure with the required files and
-then jar it up.2:45 PM 9/28/2006</p>
+are located in the
+<strong>"samples\resources\schemaorg_apache_xmlbeans</strong>" directory of
+the generated code. Copy this to your class path, compile the skeleton and
+the supporting classes. To create the .aar file, create the following
+directory structure with the required files and then jar it up.</p>
<p><img src="images/userguide/DirectoryStructure.jpg" align="bottom"
border="0"></p>
@@ -576,12 +562,12 @@
<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 run the following on the command line</p>
-<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitService.aar .</pre>
+<pre style="margin-bottom: 0.2in">jar -cf Axis2SampleDocLitService.aar</pre>
<h4><a name="Step5_Deploy_web_service">Step 5: Deploy Web Service</a></h4>
<p>The service can be deployed by dropping dropping the ".aar" file in to
-"services" directory in "\webapps\axis2\WEB-INF" of your servlet
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet
container.Start the servlet container (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>
@@ -598,16 +584,13 @@
href="webadminguide.html" target="_blank">Web Administration Guide</a> for
more information on this)</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
-samples mentioned in this guide are located at the <b><font
-color="#000000">"samples\userguide\src"</font></b> directory of the binary
-distribution. So let's get started!</p>
-
<h2><a name="Web_Service_Clients_Using_Axis2">Web Service Clients Using
Axis2</a></h2>
-<p>Let's see how we can write a Web service Client to use a Web service.</p>
+<p>Let's see how we can write a Web service Client using Axis2 in order to
+use a Web service. All samples mentioned in this guide are located at the
+<b><font color="#000000">"samples\userguide\src"</font></b> directory of the
+binary distribution. So let's get started!</p>
<p>Web services can be used to provide a wide-range of functionality to user
from simple, less time consuming operations such as "getStockQuote" to time
@@ -643,22 +626,22 @@
</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>
+behavior that we can get using the Non-Blocking API as <b>API Level
+Asynchrony.</b></p>
<p>Both these mechanisms use single transport connections to send the request
and to receive the response. They severely lag the capability of using two
transport connections for the request and the response (either One-Way or
Two-Way). So both these mechanisms fail to address the problem of long
running transactions (the transport connection may time-out before the
-operation completes). A possible solution would be to use <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>
+operation completes). A possible solution would be to use two separate
+transport connections for request and response. The asynchronous behavior
+that we gain using this solution can be called <b>Transport Level
+Asynchrony</b>.</p>
+
+<p>By <strong>combining API Level Asynchrony & Transport Level
+Asynchrony</strong> we can obtain four different invocation patterns for Web
+services as shown in the following table.</p>
<a name="table1"></a>
<table width="100%" border="1" cellpadding="0" cellspacing="0">
@@ -720,13 +703,13 @@
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 life easy for
+ stubs generated with data binding support</a>, making life easier 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>
+<h3><a name="Writing_Web_Service_Clients_using_Axis2's_Primary_APIs">1.
+Writing Web Service Clients Using Axis2's Primary APIs</a></h3>
<h4><a name="EchoBlockingClient">EchoBlockingClient</a></h4>
@@ -737,7 +720,14 @@
client code you need to write is as follows.</p>
<source><pre> try {
OMElement payload = ClientUtil.getEchoOMElement();
- <span style="color: #24C113">
+ <!--<span style="color: #24C113">-->
+
+
+
+
+
+
+ <span style="color: rgb(36, 193, 19);">
Options options = new Options();
options.setTo(targetEPR); // this sets the location of MyService service
@@ -753,13 +743,17 @@
}
}</pre>
</source>
-<p>The green lines show the set of operations that you need to perform in
-order 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/userguide" 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>
+<p>1. The lines highlighted in green lines show the set of operations that
+you need to perform in order to invoke a Web service.</p>
+
+<p>2. The rest is used to create the OMElement that needs to be sent and
+display the response OMElement.</p>
+
+<p>To test this client, use the provided ant build file that can be found in
+the "<strong>Axis2_HOME/samples/userguide</strong>" directory. Run the
+"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>
@@ -789,7 +783,7 @@
"fireAndForget()" in ServiceClient to invoke this operation. This will not
block the invocation and will return the control immediately back to the
client. You can test this client by running the target "testPingClient" of
-the ant build file at "Axis2Home/samples/userguide".</p>
+the ant build file at "<strong>Axis2Home/samples/userguide</strong>".</p>
<p>We have now invoked the two operations in our service. Are we done? No!
There's a lot more to explore. Let's see some other ways to invoke the same
@@ -805,10 +799,10 @@
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 users may have to do
-with respect to the "EchoBlockingClient" that we have already seen, it will
-be as follows:</p>
+"<strong>Axis2_HOME/samples/userguide/src/userguide/clients</strong>" with
+the name EchoNonBlockingClient. If we consider the changes that users may
+have to do with respect to the "EchoBlockingClient" that we have already
+seen, it will be as follows:</p>
<pre style="margin-bottom: 0.2in">serviceClient.sendReceiveNonblocking(payload, callback);</pre>
<p>The invocation accepts a callback object as a parameter. Axis2 client API
@@ -826,7 +820,7 @@
<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>
+"<strong>Axis2_HOME/samples</strong>" directory.</p>
<h4><a name="EchoNonBlockingDualClient">EchoNonBlockingDualClient</a></h4>
@@ -879,8 +873,21 @@
e.printStackTrace();
}
};
- //Non-Blocking Invocation sender = new ServiceClient(); sender.engageModule(new QName(Constants.MODULE_ADDRESSING)); sender.setOptions(options); sender.sendReceiveNonBlocking(payload, callback); //Wait till the callback receives the response. while (!callback.isComplete()) { Thread.sleep(1000); } //Need to close the Client Side Listener. } catch (AxisFault axisFault) { axisFault.printStackTrace(); } catch (Exception ex) { ex.printStackTrace();
- } finally {
+ //Non-Blocking Invocation
+ sender = new ServiceClient();
+ sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
+ sender.setOptions(options);
+ sender.sendReceiveNonBlocking(payload, callback);
+ //Wait till the callback receives the response.
+ while (!callback.isComplete()) {
+ Thread.sleep(1000);
+ }
+ //Need to close the Client Side Listener.
+ } catch (AxisFault axisFault) {
+ axisFault.printStackTrace();
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ } finally {
try {
sender.finalizeInvoke();
} catch (AxisFault axisFault) {
@@ -901,29 +908,40 @@
<h5>Engaging Addressing in the Server Side</h5>
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
+href="Axis2ArchitectureGuide.html#incomingsoap">Architecture Guide</a> for
+more details on 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/conf" directory in the servlet container.
+"<strong>/webapps/axis2/WEB-INF/conf</strong>" directory in the servlet
+container.
<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>
<h5>Engaging Addressing in the Client Side</h5>
-There are two ways of doing this. <br>
-One is to get the addressing-<version>.mar from modules folder of the
-std-bin distribution. And then making that available in your classpath. <br>
-The second method is to create a ConfigurationContext giving a repository
-location. Axis2 has the concept of a repository to keep the services and
-modules. You can use the extracted standard binary distribution itself as the
-repository as it contains the proper structure of an Axis2 repository (having
-the services and modules folders inside it). ConfigurationContext has the
-runtime context information of the Axis2 system. <br>
-If you have extracted the standard binary distribution to, say,
+There are two ways of doing this:<br>
+
+<ol>
+ <li>One is to get the addressing-<version>.mar from modules folder of
+ the standard binary distribution. And then making that available in your
+ classpath.</li>
+ <li>The second method is to create a ConfigurationContext giving a
+ repository location. Axis2 has the concept of a repository to keep the
+ services and modules.</li>
+</ol>
+
+<p>You can use the extracted <a
+href="../download/1_1/download.html/#std-bin">standard binary
+distribution</a> itself as the repository as it contains the proper structure
+of an Axis2 repository (having the services and modules folders inside it).
+ConfigurationContext has the runtime context information of the Axis2 system.
+<br>
+</p>
+
+<p>If you have extracted the standard binary distribution to, say,
$user_home/axis2/dist, then put the following line just before sender = new
-ServiceClient();
+ServiceClient();</p>
<pre>ConfigurationContext configContext = ConfigurationContextFactory.createConfigurationContextFromFileSystem(< Axis2RepositoryLocation >, null);</pre>
Then replace "sender = new ServiceClient();" line with "sender = new
ServiceClient(configContext, null);"
@@ -931,30 +949,32 @@
<p>This will enable addressing in both client and server sides. Now you can
test the "TestEchoNonBlockingDualClient" using the
"testEchoNonBlockingDualClient" target of the ant file found at
-"Axis2Home/samples/userguide" 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>
+"<strong>Axis2_HOME/samples/userguide</strong>" 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
+in the "<strong>Axis2_HOME/samples/userguide/src/userguide/clients/</strong>"
+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 the 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. Users can test this client using the
"echoBlockingDualClient" target of the ant build file found in the
-"Axis2Home/samples/userguide" directory.</p>
+"<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
<p>See <a href="http-transport.html" target="_blank">Configuring
Transports</a> for using 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>
+name="Writing_Web_Service_Clients_using_Code_Generation_with_Data_Binding_Support">2.
+Writing Web Service Clients using Code Generation with Data Binding
+Support</a></h3>
<p>Axis2 provides the data binding support for Web service clients as well.
The user can generate the required stubs from a given WSDL with other
@@ -1077,18 +1097,15 @@
e.printStackTrace();
}</pre>
-<p><b><font size="4">Note (on samples):</font></b> All samples mentioned in
-the user's guide are located at <b>"samples\userguide\src"</b> directory of
-the binary distribution.</p>
-
<h2><a name="Modules"></a>Modules</h2>
<p>Axis2 provides extended support for modules (See <a
href="Axis2ArchitectureGuide.html" target="_blank">Architecture Guide</a> for
more details about modules in Axis2). Let's create a custom module and deploy
-it to MyService which we created earlier. Following steps show the actions
-that need to be performed to deploy a custom module for a given Web
-service:</p>
+it to MyService which we created earlier.</p>
+
+<p>Following steps show the actions that need to be performed to deploy a
+custom module for a given Web service:</p>
<ol>
<li><p style="margin-bottom: 0in">Create the Module Implementation</p>
</li>
@@ -1111,11 +1128,12 @@
<h3><a name="MyService_with_a_Logging_Module">MyService with a Logging
Module</a></h3>
-<p>Let's write a simple logging module for our sample. This module contains
-one handler that just logs the message that is passed through it. Axis2 uses
-".mar" (Module Archive) to deploy modules in Axis2. Following diagram shows
-the file structure inside which needs to be there in the ".mar" archive.
-Let's create all these and see how it works.</p>
+<p>Let's write a simple logging module for our sample located at
+<b>"samples\userguide\src"</b> directory of the binary distribution. This
+module contains one handler that just logs the message that is passed through
+it. Axis2 uses ".mar" (Module Archive) to deploy modules in Axis2. Following
+diagram shows the file structure inside which needs to be there in the ".mar"
+archive. Let's create all these and see how it works.</p>
<p><img src="images/userguide/ModuleView.jpg" name="Graphic5" align="bottom"
border="0"></p>
@@ -1140,17 +1158,19 @@
<p>A module in Axis2 can contain, one or more handlers that perform various
SOAP header processing at different phases. (See<a
-href="Axis2ArchitectureGuide.html" target="_blank"> Architecture Guide</a>
-for more information about phases). To write a handler one should implement
-<a
+href="Axis2ArchitectureGuide.html#incomingsoap" target="_blank"> Architecture
+Guide</a> for more information on phases). To write a handler one should
+implement <a
href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/engine/Handler.java?rev=357187&view=log">org.apache.axis2.engine.Handler</a>.
But for convenience, <a
href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/handlers/AbstractHandler.java?rev=396788&view=log">org.apache.axis2.handlers.AbstractHandler</a>
-provides an abstract implementation of the Handler interface. For the logging
-module we will write a handler with the following methods. "public void
-invoke(MessageContext ctx);" is the method that is called by Axis2 engine
-when the control is passed to the handler. "public void revoke(MessageContext
-ctx);" is called when the handlers are revoked by the Axis2 engine.</p>
+provides an abstract implementation of the Handler interface.</p>
+
+<p>For the logging module we will write a handler with the following methods.
+"public void invoke(MessageContext ctx);" is the method that is called by
+Axis2 engine when the control is passed to the handler. "public void
+revoke(MessageContext ctx);" is called when the handlers are revoked by the
+Axis2 engine.</p>
<pre>public class LogHandler extends AbstractHandler implements Handler {
private Log log = LogFactory.getLog(getClass());
private QName name;
@@ -1228,9 +1248,9 @@
<order phase="loggingPhase" />
</handler></pre>
-<p>To learn more about Phase rules, see <a
+<p>To learn more about Phase rules, check out the article <a
href="http://www.developer.com/java/web/article.php/3529321"
-target="_blank">here</a></p>
+target="_blank">Axis2 Execution Framework</a></p>
<h4><a name="Step_4:_Modify_the_"axis2_xml"">Step 4: Modify the
"axis2.xml"</a></h4>
@@ -1278,12 +1298,12 @@
<!-- System pre defined phases -->
<!-- After Postdispatch phase module author or service author can add any phase he wants -->
<phase name="OperationInPhase"/>
- <phase name="<font color="#33cc00">loggingPhase</font>"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
</phaseOrder>
<phaseOrder type="outflow">
<!-- user can add his own phases to this area -->
<phase name="OperationOutPhase"/>
- <phase name="<font color="#33cc00">loggingPhase</font>"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
<!--system predefined phases-->
<!--these phases will run irrespective of the service-->
<phase name="PolicyDetermination"/>
@@ -1292,18 +1312,18 @@
<phaseOrder type="INfaultflow">
<!-- user can add his own phases to this area -->
<phase name="OperationInFaultPhase"/>
- <phase name="<font color="#33cc00">loggingPhase</font>"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
</phaseOrder>
<phaseOrder type="Outfaultflow">
<!-- user can add his own phases to this area -->
<phase name="OperationOutFaultPhase"/>
- <phase name="<font color="#33cc00">loggingPhase</font>"/>
+ <phase name="<span style="color: rgb(36, 193, 19);">loggingPhase</span>"/>
<phase name="PolicyDetermination"/>
<phase name="MessageOut"/>
</phaseOrder>
</pre>
-<p>Shown in green, the custom phase "loggingPhase" is placed in all the
+<p>The text in green, the custom phase "loggingPhase" is placed in all the
flows, hence that phase will be called in all the message flows in the
engine. Since our module is associated with this phase, the LogHandler inside
the module will now be executed in this phase.</p>
@@ -1313,20 +1333,23 @@
<p>Up to this point we have created the required classes and configuration
descriptions for the logging module and by changing the "axis2.xml" we have
-created the required phases for the logging module. Next step is to
-"<b>engage</b>" (use) this module in one of our services. For this, let's use
-the same Web service that we have used throughout the user's guide-
-MyService. However, since we need to modify the "services.xml" of MyService
-in order to engage this module, we use a separate Web service, but with the
-similar operations. The code for this service can be found in the
-"Axis2Home/samples/userguide/src/userguide/example2" directory. The simple
-changes that we have done to "services.xml' are shown in green in the
-following lines of xml.</p>
-<pre><service name="<font color="#33cc00">MyServiceWithModule</font>">
+created the required phases for the logging module.</p>
+
+<p>Next step is to "<b>engage</b>" (use) this module in one of our services.
+For this, let's use the same Web service that we have used throughout the
+user's guide- MyService. However, since we need to modify the "services.xml"
+of MyService in order to engage this module, we use a separate Web service,
+but with the similar operations.</p>
+
+<p>The code for this service can be found in the
+"<strong>Axis2_HOME/samples/userguide/src/userguide/example2</strong>"
+directory. The simple changes that we have done to "services.xml' are shown
+in green in the following lines of xml.</p>
+<pre><service name="<span style="color: rgb(36, 193, 19);">MyServiceWithModule</span>">
<description>
This is a sample Web service with a logging module engaged.
</description>
- <font color="#33cc00"><module ref="logging"/></font>
+ <span style="color: rgb(36, 193, 19);"><module ref="logging"/></span>
<parameter name="ServiceClass" locked="xsd:false">userguide.example2.MyService</parameter>
<operation name="echo">
<messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
@@ -1349,7 +1372,7 @@
<p>Before deploying the module we need to create the ".mar" file for this
module. This can be done, using the "jar" command and then renaming the
created jar file. Or you can find the "logging.mar" that is already created
-for you in the "Axis2Home/samples/userguide" directory.</p>
+for you in the "<strong>Axis2_HOME/samples/userguide</strong>" directory.</p>
<h4><a name="Step7_:_Deploy_the_Module_in_Axis2">Step7 : Deploy the Module in
Axis2</a></h4>
@@ -1362,16 +1385,21 @@
<p>Although the required changes to the "services.xml" is very little, we
have created a separate service archive (MyServiceWithModule.aar) for users
-to deploy and see. Deploy this service using the <a
-href="userguide2.html#Step4_:Deploy_the_Web_Service">same steps that you used
-to deploy "MyService"</a> and copy the "logging.mar" file to the "modules"
-directory. Then run using the "TestWebServiceWithModuleClient.bat" or
+to deploy and see.</p>
+
+<p>Deploy this service using the same steps that you used to <a
+href="#Step4_:Deploy_the_Web_Service">deploy "MyService"</a> and copy the
+"logging.mar" file to the "modules" directory.</p>
+
+<p>Then run using the "TestWebServiceWithModuleClient.bat" or
"TestWebServiceWithModuleClient.sh" in the
-"Axis2Home/samples/userguide/src/userguide/clients/bin" directory.</p>
+"<strong>Axis2Home/samples/userguide/src/userguide/clients/bin</strong>"
+directory.</p>
<p>Note: To see logs, the user needs to modify the "log4j.properties" to log
-INFO. The property file is located in "webapps\axis2\WEB-INF\classes" of your
-servlet container. Change the line "log4j.rootCategory= ERROR, LOGFILE" to
+INFO. The property file is located in
+"<strong>webapps/axis2/WEB-INF/classes</strong>" of your servlet container.
+Change the line "log4j.rootCategory= ERROR, LOGFILE" to
"log4j.rootCategory=INFO, ERROR, LOGFILE".</p>
<p><font size="4"><b>Note (on samples):</b></font> All samples mentioned in
@@ -1381,8 +1409,8 @@
<h2><a name="Other_Samples">Other Samples</a></h2>
<p>To show the power of usage of Axis2, three standard samples are shipped
-with the binary distribution. These are meant to interact with outside Web
-services and prove the capabilities of the Axis2 system.</p>
+with the standard binary distribution. These are meant to interact with
+outside Web services and prove the capabilities of the Axis2 system.</p>
<p>The included samples are</p>
<ul>
@@ -1394,40 +1422,62 @@
</ul>
<p>A simple introduction to each of the above samples are given below. Each
-sample contains it's own help document that speaks about the usage and the
-advanced operations of that particular sample.</p>
+sample contains it's own <strong>help document</strong> that speaks about
+the usage and the advanced operations of that particular sample.</p>
-<p>The most obvious place to look for the samples are the binary
-distribution. All these samples are included in the samples directory in the
-binary distribution. The shell scripts and the batch files are in fact
-written to use the binary distribution's root directory as the home in order
-to find the libraries.</p>
-
-<p>The alternate method is to build the samples from source. Moving to the
-modules/samples and running maven will create the samples in the
-target/samples directory. However if the samples need to be started using the
-shell scripts (or the batch files) then the AXIS_HOME environment need to be
-set.( the "guessed" AXIS_HOME would not be correct in this case)</p>
+<p>The most obvious place to look for the samples are the <a
+href="Axis2 standard binary distribution#std-bin">standard binary
+distribution</a>. All these samples are included in the
+<strong>samples</strong> directory in the binary distribution. The shell
+scripts and the batch files are in fact written to use the binary
+distribution's root directory as the home in order to find the libraries.</p>
+
+<p>The alternate method is to build the samples from <a
+href="Axis2 standard binary distribution#src">standard source
+distribution</a>. Moving to the "<strong>Axis2_HOME/modules/samples</strong>"
+of the source distribution and running maven will create the samples in the
+"<strong>Axis2_HOME/target/samples</strong>" directory. However, if the
+samples need to be started using the shell scripts (or the batch files) then
+the Axis2_HOME environment need to be set.( the "guessed" Axis2_HOME would
+not be correct in this case)</p>
<h3><a name="Google_Spell_Checker_Sample">Google Spell Checker Sample</a></h3>
<p>This includes a spell checker program that uses the Google spell checking
service. It demonstrates the blocking and non-blocking modes of calling the
-service. This sample can be found at the samples\googleSpellcheck directory
-and can be easily started using either the batch file or the shell script.</p>
+service. This sample can be found at the
+"<strong>Axis2_HOME/samples/googleSpellcheck</strong>" directory in the Axis2
+standard binary distribution and can be easily started using either the batch
+file or the shell script.</p>
<h3><a name="Google_Search_Sample">Google Search Sample</a></h3>
<p>This includes a search program that uses the familiar Google search over
the SOAP API. It utilizes the non-blocking mode of the client API. This
-sample can be found at the samples\googleSearch directory and can be easily
-started using either the batch file or the shell script.</p>
+sample can be found at "<strong>Axis2_HOME/samples/googleSearch</strong>"
+directory of the standard binary distribution and can be easily started using
+either the batch file or the shell script.</p>
<h3><a name="Amazon_Queuing_Service">Amazon Queuing Service</a></h3>
<p>Amazon queuing service sample shows how to use the Amazon queuing service.
It has two user interfaces, one to enqueue and the other to dequeue. This
-sample is included in the samples\amazonQS directory with the required
-batch/shell scripts to run the sample.</p>
+sample is included in "<strong>Axis2_HOME/samples/amazonQS</strong>"
+directory of the standard binary distribution with the required batch/shell
+scripts to run the sample.</p>
+
+<h2>Advanced Topics</h2>
+ <ul>
+ <li><a href="rest-ws.html" target="_blank">RESTful Web Services</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>
+ <li><a href="mtom-guide.html" target="_blank">MTOM with Axis2</a></li>
+ <li><a href="../modules/wss4j/1_0/security-module.html"
+ target="_blank">Securing SOAP Messages with Apache Rampart</a></li>
+ </ul>
</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org