xdocs/0_94/userguide2.html - axis-axis2-java-core - Git at Google

 <!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 0.94</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 -&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
                                           //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>&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;/operation&gt;
      &lt;operation name="ping"&gt;
         &lt;messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/&gt;
     &lt;/operation&gt;
  &lt;/service&gt;</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>&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 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. 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 &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 services.xml 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.Axis2SampleDocLitPortTypeMessageReceiverInOut"/&gt;
      &lt;/messageReceivers&gt;
      &lt;parameter locked="false" name="ServiceClass"&gt;
       org.apache.axis2.userguide.Axis2SampleDocLitPortTypeSkeleton
      &lt;/parameter&gt;
      &lt;!--All public methods of the service class are exposed by default--&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 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 0.94</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. 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>