ws-axis-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cha...@apache.org
Subject svn commit: r449932 [1/2] - in /webservices/axis2/trunk/java/xdocs/1_1: userguide1.html userguide2.html userguide3.html userguide4.html
Date Tue, 26 Sep 2006 07:07:36 GMT
Author: chatra
Date: Tue Sep 26 00:07:35 2006
New Revision: 449932

URL: http://svn.apache.org/viewvc?view=rev&rev=449932
Log:
made minor corrections

Modified:
    webservices/axis2/trunk/java/xdocs/1_1/userguide1.html
    webservices/axis2/trunk/java/xdocs/1_1/userguide2.html
    webservices/axis2/trunk/java/xdocs/1_1/userguide3.html
    webservices/axis2/trunk/java/xdocs/1_1/userguide4.html

Modified: webservices/axis2/trunk/java/xdocs/1_1/userguide1.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/userguide1.html?view=diff&rev=449932&r1=449931&r2=449932
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/userguide1.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/userguide1.html Tue Sep 26 00:07:35 2006
@@ -71,7 +71,7 @@
     deploy the service and make it available for use.</p>
   </li>
   <li><p style="margin-bottom: 0in"><strong>Asynchronous Web
-    Services</strong> - Axis2 now supports asynchronous Web services &amp;
+    services</strong> - Axis2 now supports asynchronous Web services &amp;
     asynchronous Web services invocation using non-blocking clients and
     transports .</p>
   </li>
@@ -100,7 +100,7 @@
     is completely transport-independent.</p>
   </li>
   <li><p style="margin-bottom: 0in"><strong>WSDL support</strong>
- Axis2
-    supports the Web Service Description Language, version <a
+    supports the Web service Description Language, version <a
     href="http://www.w3.org/TR/wsdl">1.1</a> and <a
     href="http://www.w3.org/TR/wsdl20/">2.0</a>, which allows you to easily
     build stubs to access remote services, and also to automatically export

Modified: webservices/axis2/trunk/java/xdocs/1_1/userguide2.html
URL: http://svn.apache.org/viewvc/webservices/axis2/trunk/java/xdocs/1_1/userguide2.html?view=diff&rev=449932&r1=449931&r2=449932
==============================================================================
--- webservices/axis2/trunk/java/xdocs/1_1/userguide2.html (original)
+++ webservices/axis2/trunk/java/xdocs/1_1/userguide2.html Tue Sep 26 00:07:35 2006
@@ -1,427 +1,425 @@
-<!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>
-</head>
-
-<body lang="en-US" dir="ltr">
-<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
-
-<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
-samples mentioned in this guide 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 -&gt;Code generate the Skeleton -&gt;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  
-                                          // sends back the same again </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 an implementation class that provides 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
-only 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>&lt;service &gt;
-    &lt;description&gt;
-        This is a sample Web Service with two operations, echo and ping.
-    &lt;/description&gt;
-    &lt;parameter name="ServiceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;
-    &lt;operation name="echo"&gt;
-        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
-        &lt;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
-    &lt;/operation&gt;
-     &lt;operation name="ping"&gt;
-        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
-        &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
-    &lt;/operation&gt;
- &lt;/service&gt;</pre>
-
-<p><em>The above XML tags can be explained as follows:</em></p>
-
-<p>First comes the description and the service class.</p>
-<pre>&lt;parameter name="ServiceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;</pre>
-
-<p>We provide the name of the service implementation class a parameter in the
-services.xml file.</p>
-
-<p>The next two xml tags describe the operations that are available in this
-service with respective message receivers.</p>
-<pre>   &lt;operation name="echo"&gt;
-            &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
-            &lt;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
-   &lt;/operation&gt;
-   &lt;operation name="ping"&gt;
-       &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
-       &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
-   &lt;/operation&gt;</pre>
-
-<p>Every operation must have a corresponding MessageReceiver class. When
-Axis2 engine receives a message, after the message is being processed by the
-handlers, it will be handed over to a MessageReceiver. <br>
-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.
-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 following
-format.</p>
-<pre>&lt;serviceGroup&gt;
-  &lt;service name="Service1"&gt;
-    &lt;!-- details for Service1 --&gt;
-  &lt;/service&gt;
-  &lt;service name="Service2"&gt;
-    &lt;!-- details for Service2 --&gt;
-  &lt;/service&gt;
-  &lt;module ref="ModuleName" /&gt;
-  &lt;parameter name="serviceGroupParam1" locked="false"&gt;value 1&lt;/parameter&gt;
-&lt;/serviceGroup&gt;</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 uses ".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.
-(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><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/" 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 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 &lt;Location of WSDL&gt; : WSDL file location
--o &lt;output Location&gt; : 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 &lt;package name&gt; : set custom package name
--l &lt;language&gt; : 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 &lt;databinding&gt; : valid databinding(s) are adb, xmlbeans and jaxme. Default
is adb
--g Generates all the classes. valid only with the -ss
--pn &lt;port_name&gt; : name of port in the presence of multiple ports
--sn &lt;service_name&gt; : name of service in the presence of multiple services
--u : unpacks the databinding classes
--r &lt;repository_path&gt; : 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.bat -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.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 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/org/apache/axis2/userguide directory with the name
-"Axis2SampleDocLitServiceSkeleton.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
-"Axis2SampleDocLitServiceSkeleton.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
-"Axis2SampleDocLitServiceSkeleton.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 ){
-      //Todo fill this with the necessary business logic
-      throw new  java.lang.UnsupportedOperationException();
-   }
- </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 &lt; 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>&lt;!-- This file was auto-generated from WSDL --&gt;
-&lt;!-- by the Apache Axis2 version: #axisVersion# #today# --&gt;
-&lt;serviceGroup&gt;
-  &lt;service name="Axis2SampleDocLitService"&gt;
-   &lt;messageReceivers&gt;
-      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" 
-      class="org.apache.axis2.userguide.Axis2SampleDocLitServiceMessageReceiverInOut"/&gt;
-   &lt;/messageReceivers&gt;
-   &lt;parameter locked="false" name="ServiceClass"&gt;
-   org.apache.axis2.userguide.Axis2SampleDocLitServiceSkeleton&lt;/parameter&gt;
-   &lt;operation name="echoStringArray" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
-      &lt;actionMapping&gt;echoStringArray&lt;/actionMapping&gt;
-   &lt;/operation&gt;
-   &lt;operation name="echoStruct" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
-      &lt;actionMapping&gt;echoStruct&lt;/actionMapping&gt;
-   &lt;/operation&gt;
-   &lt;operation name="echoString" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
-      &lt;actionMapping&gt;echoString&lt;/actionMapping&gt;
-   &lt;/operation&gt;
-  &lt;/service&gt;
-&lt;/serviceGroup&gt;</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 Axis2SampleDocLitService.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 "Axis2SampleDocLitService.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/"
-target="_blank">Home Page of Axis2 Web Application</a>
-(http://localhost:8080/axis2/) and see whether the
-Axis2SampleDocLitService is deployed properly. If you can see the following
-output then you have successfully deployed Axis2SampleDocLitService 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>
+</head>
+
+<body lang="en-US" dir="ltr">
+<h4><a name="Axis2_User's_Guide">Axis2 User's Guide</a></h4>
+
+<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
+samples mentioned in this guide 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 -&gt;Code generate the Skeleton -&gt;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  
+                                          // sends back the same again </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 an implementation class that provides 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
+only 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>&lt;service &gt;
+    &lt;description&gt;
+        This is a sample Web service with two operations, echo and ping.
+    &lt;/description&gt;
+    &lt;parameter name="ServiceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;
+    &lt;operation name="echo"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+        &lt;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
+    &lt;/operation&gt;
+     &lt;operation name="ping"&gt;
+        &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
+        &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
+    &lt;/operation&gt;
+ &lt;/service&gt;</pre>
+
+<p><em>The above XML tags can be explained as follows:</em></p>
+
+<p>First comes the description and the service class.</p>
+<pre>&lt;parameter name="serviceClass" locked="false"&gt;userguide.example1.MyService&lt;/parameter&gt;</pre>
+
+<p>We provide the name of the service implementation class a parameter in the
+services.xml file.</p>
+
+<p>The next two xml tags describe the operations that are available in this
+service with respective message receivers.</p>
+<pre>   &lt;operation name="echo"&gt;
+            &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/&gt;
+            &lt;actionMapping&gt;urn:echo&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="ping"&gt;
+       &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
+       &lt;actionMapping&gt;urn:ping&lt;/actionMapping&gt;
+   &lt;/operation&gt;</pre>
+
+<p>Every operation must have a corresponding MessageReceiver class. When
+Axis2 engine receives a message, after the message is being processed by the
+handlers, it will be handed over to a MessageReceiver. <br>
+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.
+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 following
+format.</p>
+<pre>&lt;serviceGroup&gt;
+  &lt;service name="Service1"&gt;
+    &lt;!-- details for Service1 --&gt;
+  &lt;/service&gt;
+  &lt;service name="Service2"&gt;
+    &lt;!-- details for Service2 --&gt;
+  &lt;/service&gt;
+  &lt;module ref="ModuleName" /&gt;
+  &lt;parameter name="serviceGroupParam1" locked="false"&gt;value 1&lt;/parameter&gt;
+&lt;/serviceGroup&gt;</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 uses ".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.
+(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><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/" 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 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 &lt;Location of WSDL&gt; : WSDL file location
+-o &lt;output Location&gt; : 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 &lt;package name&gt; : set custom package name
+-l &lt;language&gt; : 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 &lt;databinding&gt; : valid databinding(s) are adb, xmlbeans and jaxme. Default
is adb
+-g Generates all the classes. valid only with the -ss
+-pn &lt;port_name&gt; : name of port in the presence of multiple ports
+-sn &lt;service_name&gt; : name of service in the presence of multiple services
+-u : unpacks the databinding classes
+-r &lt;repository_path&gt; : 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.bat -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.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 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/org/apache/axis2/userguide directory with the name
+"Axis2SampleDocLitServiceSkeleton.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
+"Axis2SampleDocLitServiceSkeleton.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
+"Axis2SampleDocLitServiceSkeleton.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 ){
+      //Todo fill this with the necessary business logic
+      throw new  java.lang.UnsupportedOperationException();
+   }
+ </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 &lt; 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>&lt;!-- This file was auto-generated from WSDL --&gt;
+&lt;!-- by the Apache Axis2 version: #axisVersion# #today# --&gt;
+&lt;serviceGroup&gt;
+  &lt;service name="Axis2SampleDocLitService"&gt;
+   &lt;messageReceivers&gt;
+      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" 
+      class="org.apache.axis2.userguide.Axis2SampleDocLitServiceMessageReceiverInOut"/&gt;
+   &lt;/messageReceivers&gt;
+   &lt;parameter locked="false" name="ServiceClass"&gt;
+   org.apache.axis2.userguide.Axis2SampleDocLitServiceSkeleton&lt;/parameter&gt;
+   &lt;operation name="echoStringArray" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoStringArray&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="echoStruct" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoStruct&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+   &lt;operation name="echoString" mep="http://www.w3.org/2004/08/wsdl/in-out"&gt;
+      &lt;actionMapping&gt;echoString&lt;/actionMapping&gt;
+   &lt;/operation&gt;
+  &lt;/service&gt;
+&lt;/serviceGroup&gt;</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 Axis2SampleDocLitService.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 "Axis2SampleDocLitService.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/" target="_blank">Home
+Page of Axis2 Web Application</a> (http://localhost:8080/axis2/) and see
+whether the Axis2SampleDocLitService is deployed properly. If you can see the
+following output then you have successfully deployed Axis2SampleDocLitService
+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>



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


Mime
View raw message