A Developer's Diary

Jan 13, 2013

Axis2 Web Service - A Simple tutorial using Maven

Creating a Web Service using Axis2
A plain java class can be declared as a web service provided
1. It has a public method and the class has been defined in the services.xml file
2. The services.xml file should be placed under META-INF directory of the archive file

The services.xml is the Service Configuration file for Apache Axis2 where all the services are defined. The services.xml file below configures two services for our application namely the GreetingService and the Echo Service. The codes for these two services are shown later in the post
<serviceGroup>
<service name="GreetingService">
    <Description>This service welcomes you</Description>
    <messageReceivers>
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
        <messageReceiver  mep="http://www.w3.org/2004/08/wsdl/in-out"  class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
    </messageReceivers>
    <parameter name="ServiceClass" locked="false">com.examples.ws.GreetingService</parameter>
</service>
<service name="EchoService">
    <Description>This service echoes whatever client messages</Description>
    <messageReceivers>
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
        <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out" class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
    </messageReceivers>
    <parameter name="ServiceClass" locked="false">com.examples.ws.EchoService</parameter>
</service>
</serviceGroup>
The META-INF folder with services.xml is placed under src/main/resources directory. The resources folder is defined under resources in pom.xml so that the archive is created with META-INF as defined by us

Hosting Apache Axis2 web service
You can host apache web services as a web archive. The web archive or war file should have the following directory structure
1. The configuration files are stored under conf directory
2. The modules defined as module archive (mar) files are stored under modules directory
3. The services are stored under services directory as axis archive (aar) or jar file
4. The web.xml must define the Apache Axis Servlet necessary for running the web services
The module archive files mentioned above can be obtained from the axis distribution available for download from here. The module archive files are present under %AXIS_HOME%/repository/modules folder

The deployment descriptor file (web.xml) for the web service web application
<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
  <display-name>Archetype Created Web Application</display-name>
  <servlet>
    <display-name>Apache-Axis Servlet</display-name>
    <servlet-name>AxisServlet</servlet-name>
    <servlet-class>org.apache.axis2.transport.http.AxisServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
  </servlet-mapping>
</web-app>

The services-1.0-SNAPSHOT.jar jar file created earlier with GreetingService and EchoService is placed in the services directory under WEB-INF folder. We are making use of the maven-dependency-plugin to copy the jar file to specific directory under WEB-INF.
The pom.xml below packages all the dependent jar files required for running a Apache Axis2 Web Service application.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.examples.ws</groupId>
  <artifactId>WebService</artifactId>
  <packaging>war</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>WebService Webapplication</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
        <groupId>com.examples.ws</groupId>
        <artifactId>services</artifactId>
        <version>1.0-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>javax.activation</groupId>
        <artifactId>activation</artifactId>
        <version>1.1</version>
    </dependency>
    <dependency>
        <groupId>antlr</groupId>
        <artifactId>antlr</artifactId>
        <version>2.7.7</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-api</artifactId>
        <version>1.2.13</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-impl</artifactId>
        <version>1.2.13</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ws.commons.axiom</groupId>
        <artifactId>axiom-dom</artifactId>
        <version>1.2.13</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-adb</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-adb-codegen</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-ant-plugin</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-clustering</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-codegen</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-corba</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-fastinfoset</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-java2wsdl</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-jaxbri</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-jaxws</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-jibx</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-json</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-kernel</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-metadata</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-mtompolicy</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-saaj</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-soapmonitor-servlet</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-spring</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-transport-http</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-transport-local</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.axis2</groupId>
        <artifactId>axis2-xmlbeans</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>commons-cli</groupId>
        <artifactId>commons-cli</artifactId>
        <version>1.2</version>
    </dependency>
    <dependency>
        <groupId>commons-codec</groupId>
        <artifactId>commons-codec</artifactId>
        <version>1.3</version>
    </dependency>
    <dependency>
        <groupId>commons-fileupload</groupId>
        <artifactId>commons-fileupload</artifactId>
        <version>1.2</version>
    </dependency>
    <dependency>
        <groupId>commons-httpclient</groupId>
        <artifactId>commons-httpclient</artifactId>
        <version>3.1</version>
    </dependency>
    <dependency>
        <groupId>commons-io</groupId>
        <artifactId>commons-io</artifactId>
        <version>1.4</version>
    </dependency>
    <dependency>
        <groupId>commons-logging</groupId>
        <artifactId>commons-logging</artifactId>
        <version>1.1.1</version>
    </dependency>
    <dependency>
        <groupId>org.apache.geronimo.specs</groupId>
        <artifactId>geronimo-stax-api_1.0_spec</artifactId>
        <version>1.0.1</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpcore</artifactId>
        <version>4.0</version>
    </dependency>
    <dependency>
        <groupId>log4j</groupId>
        <artifactId>log4j</artifactId>
        <version>1.2.17</version>
    </dependency>
    <dependency>
        <groupId>javax.mail</groupId>
        <artifactId>mail</artifactId>
        <version>1.4</version>
    </dependency>
    <dependency>
        <groupId>org.apache.neethi</groupId>
        <artifactId>neethi</artifactId>
        <version>3.0.2</version>
    </dependency>
    <dependency>
        <groupId>org.apache.woden</groupId>
        <artifactId>woden-api</artifactId>
        <version>1.0M9</version>
    </dependency>
    <dependency>
        <groupId>org.apache.woden</groupId>
        <artifactId>woden-impl-commons</artifactId>
        <version>1.0M9</version>
    </dependency>
    <dependency>
        <groupId>org.apache.woden</groupId>
        <artifactId>woden-impl-dom</artifactId>
        <version>1.0M9</version>
    </dependency>
    <dependency>
        <groupId>wsdl4j</groupId>
        <artifactId>wsdl4j</artifactId>
        <version>1.6.2</version>
    </dependency>
    <dependency>
        <groupId>org.codehaus.woodstox</groupId>
        <artifactId>wstx-asl</artifactId>
        <version>3.2.9</version>
    </dependency>
    <dependency>
        <groupId>org.apache.xmlbeans</groupId>
        <artifactId>xmlbeans</artifactId>
        <version>2.3.0</version>
    </dependency>
    <dependency>
        <groupId>org.apache.ws.commons.schema</groupId>
        <artifactId>XmlSchema</artifactId>
        <version>1.4.7</version>
    </dependency>

    <!-- Junit Dependency -->
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <finalName>ws</finalName>
        <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>tomcat-maven-plugin</artifactId>
                <configuration>
                    <url>http://localhost:8080/manager/text</url>
                    <username>admin</username>
                    <password>admin</password>
                </configuration>
            </plugin>
        </plugins>
        </pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>2.6</version>
                <executions>
                    <execution>
                    <id>copy-services</id>
                    <phase>package</phase>
                    <goals>
                        <goal>copy</goal>
                    </goals>
                    <configuration>
                      <artifactItems>
                        <artifactItem>
                          <groupId>com.examples.ws</groupId>
                          <artifactId>services</artifactId>
                          <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/services</outputDirectory>
                        </artifactItem>
                      </artifactItems>
                    </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
  </build>
</project>

Deploy the web archive in tomcat servlet container and try to access the web service description language file from the web browser
Output of running GreetingService (http://localhost:8080/services/GreetingService) in the browser

The GreetingService code
package com.examples.ws;

public class GreetingService
{
    public String greetGuest()
    {
        return "Welcome Guest";
    }
}

The EchoService code
package com.examples.ws;

public class EchoService
{
    public String doEcho(String message)
    {
        return message;
    }
}

Your web service is deployed successfully and can be consumed by the clients. :)

No comments :

Post a Comment

Subscribe to: Post Comments ( Atom )