<!-- | |
~ 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> | |
</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/axiom/userguide/userguide.html">Axiom | |
User Guide</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/">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">Web Administration Guide</a> | |
for more information.</p> | |
</body> | |
</html> |