| <!-- | |
| ~ Licensed to the Apache Software Foundation (ASF) under one | |
| ~ or more contributor license agreements. See the NOTICE file | |
| ~ distributed with this work for additional information | |
| ~ regarding copyright ownership. The ASF licenses this file | |
| ~ to you under the Apache License, Version 2.0 (the | |
| ~ "License"); you may not use this file except in compliance | |
| ~ with the License. You may obtain a copy of the License at | |
| ~ | |
| ~ http://www.apache.org/licenses/LICENSE-2.0 | |
| ~ | |
| ~ Unless required by applicable law or agreed to in writing, | |
| ~ software distributed under the License is distributed on an | |
| ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| ~ KIND, either express or implied. See the License for the | |
| ~ specific language governing permissions and limitations | |
| ~ under the License. | |
| --> | |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" | |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
| <html xmlns="http://www.w3.org/1999/xhtml"> | |
| <head> | |
| <meta name="generator" content= | |
| "HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /> | |
| <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_" id= | |
| "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" id= | |
| "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. <i>OM stands for Object | |
| Model (also known as AXIOM - AXis Object Model) and refers to the | |
| XML infoset model that is initially developed for Apache Axis2. DOM | |
| and JDOM are two such XML models conceptually similar to OM as an | |
| XML model by its external behavior, but considering the deep down | |
| implementation OM is very much different to others. OMElement is | |
| the basic representation of the XML infoset element in OM.For more | |
| details on OMElement see the <a href= | |
| "http://ws.apache.org/commons/axiom/OMTutorial.html">OM | |
| Tutorial</a>.</i></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" id= | |
| "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">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">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">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" id= | |
| "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" id= | |
| "Graphic1" /></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" id= | |
| "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" id="Graphic2" /></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> |