Quick Overview of SOAP Webservice with Axis2

In this tutorial, we will learn how to build a simple SOAP web service using Axis2.

Example Scenario:

We need to build a web service based on SOAP using Axis2, which should do binary addition and provide us the response.


Project artifacts:

Technologies used –

a. Eclipse IDE for Java EE developer 4.5.0.20150621-1200 (Mars)
b. Preinstalled Maven with Eclipse Mars
c. Tomcat 7.0.64
d. Axis2 1.6.2
e. Java 1.8

Jars used – 

axis2-adb-1.6.2.jar
axis2-kernel-1.6.2.jar
axiom-api-1.2.13.jar
geronimo-javamail_1.4_spec-1.7.1.jar
jaxen-1.1.3.jar
geronimo-stax-api_1.0_spec-1.0.1.jar
apache-mime4j-core-0.7.2.jar
axiom-impl-1.2.13.jar
wstx-asl-3.2.9.jar
geronimo-ws-metadata_2.0_spec-1.1.2.jar
geronimo-jta_1.1_spec-1.1.jar
servlet-api-2.3.jar
commons-httpclient-3.1.jar
commons-codec-1.2.jar
commons-fileupload-1.2.jar
wsdl4j-1.6.2.jar
XmlSchema-1.4.7.jar
neethi-3.0.2.jar
woden-api-1.0M9.jar
woden-impl-dom-1.0M9.jar
woden-impl-commons-1.0M9.jar
commons-logging-1.1.1.jar
jsr311-api-1.0.jar
geronimo-activation_1.1_spec-1.0.2.jar

Before we begin:

The following image depicts the folder structure of maven web project with WSDL in the resource folder.

To learn how to create a WSDL, please read this tutorial. We are going to use the same WSDL for this tutorial.

–    Eclipse project folder structure (at the beginning):

SOAP Webservice Axis2

–     pom.xml

Maven unit of work to declare project dependencies, compile code and build aar (axis2 archive) file for uploading in Axis2 war application. The pom.xml uses two plugins. The first plugin creates java classes for binding purpose from WSDL using the default binding framework of Axis2 i.e. adb. You can also use any of the other supported binding frameworks, which are XmlBeans, JiBX and JAXBRI. The second plugin bundles the created classes into an aar file for uploading to Axis2 war 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.javanbeyond</groupId>
    <artifactId>QuickSOAPOverviewAxis2</artifactId>
    <packaging>aar</packaging>
    <version>0.0.1-SNAPSHOT</version>
    <name>QuickOverviewAxis2 Maven Webapp</name>
    <url>http://maven.apache.org</url>
    <repositories>
        <repository>
            <id>apache-snapshots</id>
            <name>Apache SNAPSHOT Repository</name>
            <url>http://repository.apache.org/snapshots/</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>
    <dependencies>
        <dependency>
            <groupId>org.apache.axis2</groupId>
            <artifactId>axis2</artifactId>
            <version>1.6.2</version>
            <type>pom</type>
        </dependency>
        <dependency>
            <groupId>org.apache.axis2</groupId>
            <artifactId>axis2-adb</artifactId>
            <version>1.6.2</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.axis2</groupId>
                <artifactId>axis2-wsdl2code-maven-plugin</artifactId>
                <version>1.6.2</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>wsdl2code</goal>
                        </goals>
                        <configuration>
                            <packageName>com.javanbeyond.binaryadditionservice</packageName>
                            <!-- WSDL file location -->
                            <wsdlFile>src/main/resources/BinaryAdditionService.wsdl</wsdlFile>
                            <!-- Location where sources will be created. -->
                            <outputDirectory>${basedir}/src/main/java</outputDirectory>
                            <!-- Using default databinding. -->
                            <databindingName>adb</databindingName>
                            <skipWSDL>true</skipWSDL>
                            <flattenFiles>true</flattenFiles>
                            <!-- We want only server side classes for web service implementation -->
                            <generateServerSide>true</generateServerSide>
                            <generateServicesXml>true</generateServicesXml>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.axis2</groupId>
                <artifactId>axis2-aar-maven-plugin</artifactId>
                <version>1.6.2</version>
                <extensions>true</extensions>
                <configuration>
                    <includeDependencies>false</includeDependencies>
                    <aarName>QuickSOAPOverviewAxis2</aarName>
                    <!-- Location where aar should be created -->
                    <outputDirectory>${basedir}/target</outputDirectory>
                    <!-- Location of services.xml which can be put inside aar and which                         was created by axis2-wsdl2code-maven-plugin -->
                    <servicesXmlFile>${basedir}/src/main/java/services.xml</servicesXmlFile>
                    <!-- Location of wsdl which can be put inside aar -->
                    <wsdlFile>${basedir}/src/main/resources/BinaryAdditionService.wsdl</wsdlFile>
                    <!-- The final name of the wsdl inside aar. Default is services.wsdl -->
                    <wsdlFileName>AdditionService.wsdl</wsdlFileName>
                </configuration>
                <executions>
                    <execution>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>aar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Please run maven clean and install and you should see the java classes and few more artifacts created from WSDL.

– The created files from WSDL

  1. services.xml : The configuration file for the service which is used by Axis2 runtime to get service class information, operation mapping, message receivers etc of the service. This is not the only configuration file available in Axis2. For a detail list of  configuration files and its usage, please refer Axis2 Configuration Guide.

  2. BinaryAdditionServiceSkeleton.java :  The implementation class of the service which contains business logic.

  3. BinaryAdditionServiceMessageReceiverInOut.java : This class acts as a bridge between Axis2 engine and service skeleton instance. After a message is processed by the handlers, the Axis2 engine hands it over to a MessageReceiver. As far as Axis2 message processing is considered, Axis2 core engine considers the message to be processed complete when a message receiver is invoked. In this example, the message receiver is declared outside the operation, which will be applied to all operations of the service. Message receivers can also be declared inside operation, specific to each operation of the service.

  4. BinaryAddRequest : The java equivalent of the request XML which ADB uses for data binding.

  5. BinaryAddResponse : The java equivalent of response XML which ADB uses for data binding.

  6. ExtensionMapper.java : Class to support xsi:type.

Let’s Proceed…

  1. Final project directory structure:

    AxisWebserviceaar file

 

Please note the creation of aar (axis2 archive) file. This is the file we are going to deploy inside Axis2 war.

2. The skeleton class

file:BinaryAdditionServiceSkeleton.java. BinaryAdditionServiceSkeleton is the class which receives the request from client. We have implemented our addition logic in this class.

 

/**
 * BinaryAdditionServiceSkeleton.java
 *
 * This file was auto-generated from WSDL
 * by the Apache Axis2 version: 1.6.2  Built on : Apr 17, 2012 (05:33:49 IST)
 */
package com.javanbeyond.binaryadditionservice;

import com.javanbeyond.www.binaryadditionservice.BinaryAddResponse;

/**
 * BinaryAdditionServiceSkeleton java skeleton for the axisService
 */
public class BinaryAdditionServiceSkeleton {

    /**
     * Auto generated method signature
     
     @param binaryAddRequest
     @return binaryAddResponse
     */

    public com.javanbeyond.www.binaryadditionservice.BinaryAddResponse binaryAdd(
            com.javanbeyond.www.binaryadditionservice.BinaryAddRequest binaryAddRequest) {
        BinaryAddResponse response = new BinaryAddResponse();
        response.setOut(Integer
                .toBinaryString(Integer.parseInt(binaryAddRequest.getA()2)
                        + Integer.parseInt(binaryAddRequest.getB()2)));
        return response;
    }

}

3. The service configuration file

file: services.xml. The description of services are specified using services.xml. Each service archive file needs to have a services.xml in order to be a valid service. If the service needs to be further fine-tuned, it can be done using services.xml.

<!-- This file was auto-generated from 
    WSDL --><!-- by the Apache Axis2 version: 1.6.2 
    Built on : Apr 17, 2012 (05:33:49 IST) --><serviceGroup>
    <service name="BinaryAdditionService">
        <messageReceivers>
            <messageReceiver mep="http://www.w3.org/ns/wsdl/in-out" class="com.javanbeyond.binaryadditionservice.BinaryAdditionServiceMessageReceiverInOut"></messageReceiver>
        </messageReceivers>
        <parameter name="ServiceClass">com.javanbeyond.binaryadditionservice.BinaryAdditionServiceSkeleton</parameter>
        <parameter name="useOriginalwsdl">true</parameter>
        <parameter name="modifyUserWSDLPortAddress">true</parameter>
        <operation name="binaryAdd" mep="http://www.w3.org/ns/wsdl/in-out" namespace="http://www.javanbeyond.com/BinaryAdditionService/">
            <actionMapping>http://www.javanbeyond.com/BinaryAdditionService/binaryAdd</actionMapping>
            <outputActionMapping>http://www.javanbeyond.com/BinaryAdditionService/BinaryAdditionService/binaryAddResponse</outputActionMapping>
        </operation>
    </service>
</serviceGroup>

4. Rerun maven clean install and the created aar file should have our logic now.

5. aar file deployment steps:

  1. Download the axis2 war and deploy it in Tomcat.
  2. Open your favorite browser and type “http://localhost:8080/axis2”.

Axis2WelcomeScreen

3. Click on “Administration” and provide username as “admin” and password “axis2”. Please refer to axis2 website for more details.

Axis2 war admin

4. Click on “Upload Service”.

Upload aar Axis2

5. Select the aar file created  and upload it.

6. Click on “Available Services”. Refresh the page . You should see the service name along with service endpoint URL. Client would use this url to access the service.

Uploaded aar file

Note : If the service is not visible, please restart Tomcat and then try.

Example Execution:

1. Open SOAPUI and create a SOAP project with the url “http://localhost:8080/axis2/services/BinaryAdditionService?wsdl”

Axis2SOAP UI Project

2. Hit the service with two binary values and you will get their binary sum in response.

Axis2 SOAPUI Request and Response

 

Leave a Reply

Back to Top
%d bloggers like this: