You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by he...@apache.org on 2006/10/09 12:43:08 UTC
svn commit: r454334 [3/3] - in
/webservices/axis2/branches/java/1_1/xdocs/1_1: dii.html modules.html
reference.html src/ src/Axis2SampleDocLitServiceCode.html userguide.html
xmlbased-server.html
Added: webservices/axis2/branches/java/1_1/xdocs/1_1/xmlbased-server.html
URL: http://svn.apache.org/viewvc/webservices/axis2/branches/java/1_1/xdocs/1_1/xmlbased-server.html?view=auto&rev=454334
==============================================================================
--- webservices/axis2/branches/java/1_1/xdocs/1_1/xmlbased-server.html (added)
+++ webservices/axis2/branches/java/1_1/xdocs/1_1/xmlbased-server.html Mon Oct 9 03:43:07 2006
@@ -0,0 +1,157 @@
+<h1><a name="Writing_Web_Services_Using Axis2's_Primary_APIs">Writing Web Services Using Axis2's Primary APIs</a></h1>
+
+<p>Axis2 dispatch a componenets call <strong>MessageReciver</strong> while reciving a Message in the server. Axis2 provides different implementations of this class and it can be configured by adding a messageReceiver tag to service.xml. Axis2 provide implementation for class of Message recivers called RawXml Message recivers. They work on XML level and could 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>
+
+<h4><a name="How_to_write_the_Web_Service_">How to write a Web
+Service?</a></h4>
+Writing a new Web service with Axis2 involves 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 style="margin-bottom: 0in">Deploy the Web service</p>
+ </li>
+</ol>
+
+<h4><a name="Step1_:Write_the_Implementation_Class">Step1 :Write the
+Implementation Class</a></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 type
+OMElement.</p>
+
+<p><span style="color: #FF0000">OMElement is .... </span>For more details see
+<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>
+
+<h4><a name="Step2_:Write_the_services_xml_file">Step2 :Write the
+services.xml file</a></h4>
+
+<p>"services.xml" has the configuration for a web Service. Each web service,
+deployed in 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><em>The above XML tags can be explained as follows:</em></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, 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 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 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 : 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 in directory structure shown below.
+Please note that the name of the archive file will be 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 .aar file.This archive file can be
+found in the "Axis2_HOME/samples/userguide" directory. This file now has to
+be deployed.</p>
+
+<h4><a name="Step4_:Deploy_the_Web_Service">Step4 : Deploy the Web
+Service</a></h4>
+
+<p>The service can be deployed by dropping the ".aar" file in to
+"services" directory in "/webapps/axis2/WEB-INF" of your servlet container.
+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. Congratulations !!</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. Please refer
+to the <a href="webadminguide.html" target="_blank">Web Administration
+Guide</a> for more information.</p>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org