| <html> |
| <head> |
| <meta http-equiv="content-type" content=""> |
| <title>Writing Web Services Using Axis2's Primary APIs</title> |
| <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" |
| media="all"> |
| </head> |
| |
| <body> |
| <a name="Writing_Web_Services_Using Axis2's_Primary_APIs"></a> |
| |
| <h1>Writing Web Services Using Apache Axis2's Primary APIs</h1> |
| |
| <p>Apache Axis2 dispatches a component called |
| <strong>MessageReceiver</strong> when Receiving a Message to the server. |
| Apache Axis2 provides different implementations of this class and it can be |
| configured by adding a messageReceiver tag to services.xml. Apache Axis2 |
| provides an implementation for a class of Message receivers called RawXml |
| Message receivers. They work at the XML level and can only handle OMElements |
| as parameters. This section explains how to write a service using them.</p> |
| |
| <p>In our example, the Web service will have two operations.</p> |
| <pre>public void ping(OMElement element){} //IN-ONLY operation, just accepts the OMElement and does some processing. |
| public OMElement echo(OMElement element){}//IN-OUT operation, accepts an OMElement and |
| // sends back the same again </pre> |
| <a name="How_to_write_the_Web_Service_"></a> |
| |
| <h4>How to Write a Web Service?</h4> |
| Writing a new Web service with Apache Axis2 involves four steps: |
| <ol> |
| <li>Write the Implementation Class.</li> |
| <li>Write a services.xml file to explain the Web service.</li> |
| <li>Create a *.aar archive (Axis Archive) for the Web service.</li> |
| <li>Deploy the Web service.</li> |
| </ol> |
| <a name="Step1_:Write_the_Implementation_Class"></a> |
| |
| <h4>Step1: Write the Implementation Class</h4> |
| |
| <p>An implementation class has the business logic for the Web service and |
| implements the operations provided by the Web service. Unless you have data |
| binding, the signature of the methods can have only one parameter of the type |
| OMElement.</p> |
| |
| <p>For more details on OMElement see the <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 |
| ...... |
| } |
| public OMElement echo(OMElement element){ |
| ...... |
| } |
| }</pre> |
| <a name="Step2_:Write_the_services_xml_file"></a> |
| |
| <h4>Step2: Write the services.xml file</h4> |
| |
| <p>"services.xml" has the configuration for a Web service. Each Web service, |
| deployed in Apache Axis2 , must have its configuration in "services.xml". The |
| configuration for MyService is 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"/> |
| <actionMapping>urn:echo</actionMapping> |
| </operation> |
| <operation name="ping"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/> |
| <actionMapping>urn:ping</actionMapping> |
| </operation> |
| </service></pre> |
| |
| <p>The above XML tags can be explained as follows:</p> |
| |
| <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>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>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"/> |
| <actionMapping>urn:echo</actionMapping> |
| </operation> |
| <operation name="ping"> |
| <messageReceiver class="org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver"/> |
| <actionMapping>urn:ping</actionMapping> |
| </operation></pre> |
| |
| <p>4. Every operation must map to a corresponding MessageReceiver class. |
| After a message is processed by the handlers, the 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 the IN-ONLY operation "ping", we have used |
| <strong>RawXMLINOnlyMessageReceiver</strong> as the message receiver.</p> |
| |
| <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>7. You can write a services.xml file to include a group of services |
| instead of a single service. This makes the 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"> |
| <!-- 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 : The name of the service is a compulsory attribute.</p> |
| <a name="Step3_:Create_the_Web_Service_Archive"></a> |
| |
| <h4>Step3: Create the Web Service Archive</h4> |
| |
| <p>Apache Axis2 uses the ".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 in the directory structure shown |
| below. Please note that the name of the archive file will be the same as that |
| of the service 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 the archive file, you can create a .jar file containing all the |
| necessary files and then rename it to a .aar file. This archive file can be |
| found in the "Axis2_HOME/samples/userguide" directory. This file has to be |
| deployed now.</p> |
| <a name="Step4_:Deploy_the_Web_Service"></a> |
| |
| <h4>Step4: Deploy the Web Service</h4> |
| |
| <p>The service can be deployed by dropping the ".aar" file into the |
| "services" directory in "/webapps/axis2/WEB-INF" of your servlet container. |
| Start the servlet container (if you have not already started), click 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 MyService is deployed properly. If you can see the following output, |
| then you have successfully deployed MyService on Apache Axis2. |
| Congratulations !!</p> |
| |
| <p align="center"><img src="images/userguide/MyServiceDeployed.jpg" |
| name="Graphic2" align="bottom" border="0"></p> |
| |
| <p>Note: Apache Axis2 provides an easy way to deploy Web services using the |
| "Upload Service" tool on the Axis2 Web Application's Administration module. |
| Please refer to the <a href="webadminguide.html" target="_blank">Web |
| Administration Guide</a> for more information.</p> |
| </body> |
| </html> |
