AXIS2 Web Services Tutorial

Filed Under: Java

Welcome to Apache Axis2 Tutorial. Recently I was trying to upgrade my Apache Axis2 skills from 1.3 to latest version 1.5.4 and I was not able to find out any tutorial that is self-explanatory and covering the latest release. So it forms the basis of my post for Axis2 Web Services Tutorial.

Apache Axis2 Tutorial

apache axis2 tutorial

Who Should use this Tutorial?

This tutorial is intended for Java programmers who are interested in developing and deploying Web Services using Apache Axis2.


The scope of this tutorial is to use Axis2 for creating web services and invoking the web service using a Java client program and testing web service using Soap UI tool. Basic understanding of Java, Web Services, XML, Ant, and application server (Tomcat) is required to understand the tutorial with ease.

Software and Tools Used

  1. Java Development Kit (JDK) 1.6.0 (Tomcat 7 requires min JDK 1.6)
  2. Apache Ant 1.7.0 (Axis2 requires minimum version 1.6.5)
  3. Apache Axis2 1.5.4 (Binary Distribution)
  4. Eclipse 3.6.1 IDE for Project Development (You can use other IDE also, for example NetBeans)
  5. Apache Tomcat 7.0.8
  6. SoapUI for testing our web service.
  7. Mac OS X 10.6.4 (I am working on Mac OS but the tutorial should work for other operating systems also, however some change might be needed in executing the commands)

System Setup

  1. Download the latest version of Apache Tomcat latest version. As of now, the latest version is 7.0.8 and that is what I am using for this tutorial. It requires minimum Java Version 1.6, so make sure it’s installed in your system. If Java 6 is not installed in your system, you should download and install it first from Java SE Downloads. Download the Tomcat Core zip ( and unzip it to install it on your system. Set the JAVA_HOME environment variable to start and stop the server.
  2. Download Apache Axis2 1.5.4 Binary Distribution zip from Apache Axis2 – Releases. This step is required to create axis2.war that will be deployed to tomcat and to get the axis2 libraries to be used in projects.
  3. Unzip the Axis2 binary distribution zip into any convenient directory. Go to axis2-1.5.4/webapp directory and run the “ant create.war” command to create the axis2.war deployment in the axis2-1.5.4/dist directory. If you don’t have Apache Ant installed, you can download and install it from Apache Ant – Binary Distributions. Please note that I was facing some issue with axis2.war downloaded from War Distribution. Later on, I found out that few jars are missing in the axis2 War Distribution. War Distribution contains only 58 jars whereas Binary Distribution contains 63 jars. (I am feeling lazy to find out, which jars are missing.)
    $ ant create.war
    Buildfile: build.xml
        [mkdir] Created dir: /Users/pankaj/Downloads/axis2-1.5.4/dist/temp
         [copy] Copying 59 files to /Users/pankaj/Downloads/axis2-1.5.4/dist/temp
         [copy] Copying 9 files to /Users/pankaj/Downloads/axis2-1.5.4/dist/temp/WEB-INF
        [mkdir] Created dir: /Users/pankaj/Downloads/axis2-1.5.4/dist/temp/WEB-INF/conf
         [copy] Copying 1 file to /Users/pankaj/Downloads/axis2-1.5.4/dist/temp/WEB-INF/conf
          [war] Building war: /Users/pankaj/Downloads/axis2-1.5.4/dist/axis2.war
       [delete] Deleting directory /Users/pankaj/Downloads/axis2-1.5.4/dist/temp
    Total time: 2 seconds
  4. Deploy the axis2.war in the tomcat application server by copying it in tomcat webapps directory. You may need to restart the server if it’s not supporting hot deployment.
  5. Go to https://localhost:8080/axis2/ and click on Validate link. If the Happy Axis page is coming with GREEN color then it means that axis2 is successfully deployed. Our system setup is ready now and we can proceed for creating Axis2 web services.

axis2 tutorial

Creating Axis2 Web Service

For creating Axis2 Web Service archive, we need following:

  1. A Java Project (Axis2WSImplementation) with a class that will be exposed as a web service. In my example, I am exposing two operations from MyService class. The first operation getData input is String and returns String whereas the second operation getObjectData input is MyBean java object and returns MyBean java object after some data manipulation. Note that MyBean class implements Serializable interface so that it can be transferred over the network.
  2. Ant build.xml file that will be used to create aar, wsdl and client side stub and callback handler classes.
  3. services.xml file that will be part of the axis2 archive. This file will be put in the META-INF folder of the axis2 archive.

The project structure will look like the below image.

apache axis2 project

Don’t get confused with the content inside build folder. They will be created when we will execute the build.xml ant file.

Axis2 Web Service Project Explanation Implementation class that will be exposed as Axis2 web service.


import com.journaldev.bean.MyBean;

public class MyService {

	public String getData(String input) {
		return "Hi" + input;

	public MyBean getObjectData(MyBean myBean) {

		String name = myBean.getName();
		int id = myBean.getId();
		myBean.setId(id + 100);
		myBean.setName("Output: " + name);

		return myBean;
} Java Bean class that is input and output of getObjectData operation in web service.

package com.journaldev.bean;


public class MyBean implements Serializable {

	private static final long serialVersionUID = -1129402159048345204L;

	private String name;

	private int id;

	public String getName() {
		return name;

	public void setName(String name) { = name;

	public int getId() {
		return id;

	public void setId(int id) { = id;


services.xml: Axis2 web service related parameters are part of this xml file. ServiceClass parameter specifies the class that will be exposed as web service. The other important parameters are targetNamespace and schemaNamespace.


<service name="MyService" scope="application" targetNamespace="">
 <messageReceiver mep="" class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
 <messageReceiver mep="" class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
 <schema schemaNamespace=""/>
 <parameter name="ServiceClass"></parameter>

build.xml: Ant build file for performing Axis2 tasks. There are three targets defined whose details are:

  1. generate.wsdl: This target generates the MyService.wsdl file in the build folder. Make sure that targetNamespace and schemaTargetNamespace is same as in service.xml file.
  2. generate.service: This target generates axis2 archive in the build folder. It includes the services.xml file in the archive and archive name is MyService.aar
  3. generate.client: This target generates the client side classes. Make sure you run this after executing generate.wsdl so the MyService.wsdl file is present in the build folder.


<project name="AxisWSImplementation" basedir="." default="generate.service">

 <property environment="env"/>
 <property name="build.dir" value="build"/>

 <path id="axis2.classpath">
 <fileset dir="${basedir}/lib">
 <include name="*.jar"/>

 <target name="compile.service">
 <mkdir dir="${build.dir}"/>
 <mkdir dir="${build.dir}/classes"/>
 <mkdir dir="${build.dir}/resources"/>
 <!--First let's compile the classes-->
 <javac debug="on"

 <target name="generate.wsdl" depends="compile.service">
 <taskdef name="java2wsdl"
 <java2wsdl className=""
 <pathelement path="${axis2.classpath}"/>
 <pathelement location="${build.dir}/classes"/>

 <target name="generate.service" depends="compile.service">
 <copy toDir="${build.dir}/classes" failonerror="false">
 <fileset dir="${basedir}/resources">
 <include name="**/*.xml"/>
 <jar destfile="${build.dir}/MyService.aar">
 <fileset excludes="**/Test.class" dir="${build.dir}/classes"/>

 <target name="generate.client" depends="compile.service">
 <taskdef name="wsdl2java"
 output="${build.dir}/resources" />

 <target name="clean">
 <delete dir="${build.dir}"/>

Generating WSDL, Axis Archive and Stub Files

  • Execute generate.wsdl ant target to generate MyService.wsdl file.
  • Execute generate.service ant target to generate the MyService.aar file.
  • Execute generate.client ant target to generate the Stub classes.

Axis2 Web Service Deployment

Copy the MyService.aar in ~apache-tomcat-7.0.8/webapps/axis2/WEB-INF/services directory. Axis2 supports hot deployment of services, so you don’t need to restart the server. Check your service deployment on ListServices page (https://localhost:8080/axis2/services/listServices). MyService should be listed there with two operations.

axis2 list services page

Axis2 Web Service Testing

After deploying the service, first of all we need to test it. Here I am using SoapUI that is one of the best tools for Web Service Testing. If you don’t have it, you can download it from their website and install it easily.

Steps for Testing using SoapUI

  1. Create a new SoapUI project with Project Name MyServiceTest (you can give any name you want) and Initial WSDL/WADL https://localhost:8080/axis2/services/MyService?wsdl (You can get this URL from Axis2 List Services page after clicking on the MyService link.). Leave other options with default value and click on OK button to create the SoapUI testing project.
  2. Take any of the Soap Bindings and double click on the getData and getObjectData SOAP Requests.
  3. Provide some values for input in the request and submit it to the web service end point URL. You should get output from the service similar to the below image. It confirms that our web service is up and running.

Axis2 Web service testing using SoapUI

Now we will proceed with the last task of invoking the web service using Axis2 stub classes.

Axis2 Web Service invocation using Stub Files

  1. Create a Java Project Axis2Client in Eclipse.
  2. Create lib folder and copy all the Axis2 jars from downloaded binary distribution lib folder. Add these jars to the build path of the project.
  3. Copy earlier generated and in the project src with correct package structure. In my case I copied them in com.journaldev package. If you have to provide these classes to somebody else, I would strongly suggest creating a jar from them and then distributing it with others to avoid any modifications.
  4. Create the Axis2ClientUsingStubsFromAnt client class to invoke the web service operations. The project structure will look similar like below image.

axis2 tutorial project

Axis2ClientUsingStubsFromAnt Code


import java.rmi.RemoteException;

import com.journaldev.MyServiceStub;
import com.journaldev.MyServiceStub.GetData;
import com.journaldev.MyServiceStub.GetDataResponse;
import com.journaldev.MyServiceStub.GetObjectData;
import com.journaldev.MyServiceStub.GetObjectDataResponse;
import com.journaldev.MyServiceStub.MyBean;

 * @author Pankaj - This class will invoke Axis2 web service
 *         operations using Stub classes
public class Axis2ClientUsingStubsFromAnt {

	 * END_POINT is the web service endpoint
	private final static String END_POINT = "https://localhost:8080/axis2/services/MyService";

	public static void main(String[] args) throws RemoteException {

		// Create the Stub Object by passing the Web Service Endpoint URL
		MyServiceStub stub = new MyServiceStub(END_POINT);

		// Creating an input object for the getData operation
		GetData getDataInput = new GetData();

		// Setting the input part in the getData input object

		// invoking the getData operation
		GetDataResponse getDataOutput = stub.getData(getDataInput);

		// get_return method returns the web service output object. Here its
		// String, so we can
		// directly print the returned value
		System.out.println("Output:" + getDataOutput.get_return());

		// Creating input object for the getObjectData operation
		GetObjectData getObjectDataInput = new GetObjectData();
		MyBean myBean = new MyBean();

		// Setting the input part in the getObjectData input object

		// invoking the getObjectData operation
		GetObjectDataResponse getObjectDataOutput = stub

		// Get the MyBean object from the response object
		MyBean myBeanOutput = getObjectDataOutput.get_return();

		// Print the myBeanOutput values to check that web service operations
		// are getting invoked
		System.out.println("ID:" + myBeanOutput.getId() + "NAME:"
				+ myBeanOutput.getName());




Execute the Axis2ClientUsingStubsFromAnt class to invoke the web service. Output of the above program is:

log4j:WARN No appenders could be found for logger (org.apache.axis2.description.AxisService).
log4j:WARN Please initialize the log4j system properly.
ID:101NAME:Output: KUMAR

If you find the tutorial helpful in understanding Axis2 and getting started with it, please share your thoughts in the comment section.

And yeah, don’t forget to share it across with others.

Your two clicks and 5 seconds time can help someone else to learn Axis2 easily. 🙂


  1. Ranjan says:

    Hi Pankaj,
    This is a nice article. Can you please guide how to implement the service payload with attachment (external to the body with mime support ) in axis2.

  2. Senthil Kumar says:

    1. Security policy namespace cannot be null Exception Throwing when we send the message to the Web service listener and we are using Axis2 1.7.9 version.

  3. Praful Anand says:

    Hi Pankaj,

    Please share link for source code of import com.journaldev.MyServiceStub; and import com.journaldev.MyServiceCallbackHandler

    1. Pankaj says:

      Execute generate.client ant target to generate the Stub classes.

      1. Praful Anand says:

        Hi Pankaj,

        Thanks for quick response. But i am not getting regarding this “Execute generate.client ant target”. is this one a command or what is where i have to execute this. Please elaborate in details. what i have to execute where i have to execute.

        1. Pankaj says:

          Run the ant build with this target and it will automatically generate the stub classes.

  4. Zakaria Kaoukab says:

    Thank you sir, your article is still helpful in 2019 😀

  5. joshua says:

    this can be implemente in windows ?

  6. Jiten says:

    you don’t reply to problem, but only to compliments…

    getting issue as below:

    \build.xml:33: java.lang.RuntimeException: java.lang.ClassCastException: org.apache.axis2.receivers.RawXMLINOnlyMessageReceiver cannot be cast to org.apache.axis2.engine.MessageReceiver

    1. Pankaj says:

      I am not sure what is the issue you are facing. This article I wrote more than 5 years back, I haven’t used Axis-2 in last 4 years. So I can’t help you in this issue.

  7. Shilendra says:

    After run https://localhost:8080/axis2/services/

    it displays only:

    Deployed services


    Available operations

    not completed web service in win7

  8. Suri says:

    Hye Pankash,

    Thank you for your great tutorial.
    Do you have any tutorial regarding how to get raw request XML made by client? I create my web services using Axis2 and now I am stuck and dont know how to get and put in log file the request XML made by client

    -Miss Suri

  9. Jayanti Rode says:

    Hi Pankaj,

    Do you have tutorial on SOAP webservices? with examples.

  10. dinesh says:

    Hello all,

    i am getting the below error when i am starting the tomcat server, can someone help on it.

    “[ERROR] The MyService.aar service, which is not valid, caused The services.xml file cannot be found for the service: C:\apache-tomcat-7.0.68\webapps\axis2\WEB-INF\services\MyService.aar”

    Thanks in advance,

  11. Suresh says:

    Hi Pankaj

    as of now i’m using to convert java classes into .wsdl files.. which is working great…but there is requirement.. that i need to convert the java files into wadl files.. is axis supports that.. if so can you give me small example on it using ant… build.xml…

    thank you

    1. Srikanta says:

      I am sure that JAX-WS and axis2 implementation doesn’t support wadl. But if axis2 supports restful then you can do that but not for WebService. Only for restful services. Its’ better you go with JAX-WS specification.

  12. Darshan says:

    Dear Pankaj,

    I have been using your website as a reference, whenever I need any help on java and related technologies. I have found your articles to be in depth and up to date. Keep up the good work and I wish you all the best in your mission.


  13. subrat says:

    Dear sir
    can u send me i want an example on axis2 with maven step to step………………..
    and more post on maven tutorial

  14. Kranti says:

    Hi Pankaj,
    Nice article.
    Is any article available to use Axis2/C in objective C for Mac OS X app for creating client app? First of all, is it possible?

    Thanks in advance,

  15. Manikandan B says:

    When I use the this JAVA2WSDL as plugin in maven it generating WSDL with the following end point url..


    Once the wsdl got generated I need to manully open the wsdl and edit the END point below


    TestService is my web service.

    Please help to me out….

  16. Rob Erto says:

    Dear Pankaj,
    Even after a couple of years later, I can say that your tuto is very clear, well organized. And the use of eclipse helps a lot to dive immediately into the real world. For those who likes command lines here some links from Axis2 web page: Axis2 Quick Start Guide and Apache Axis2 User’s Guide -Building Services and finally Apache Axis2 Advanced User’s Guide. Hope that could help some else.

  17. swapnil says:

    sorry to say but article is not organized properly. We can not just simply rely steps mentioned to execute successfully.

  18. sudarshan says:

    hey pankaj , do we need dynamic web application project to create the web service or normal java project
    please breaf it am new to web service pls

    1. Pankaj says:

      Hi Sudarshan,

      Creating a dynamic web application helps in packaging it as WAR file. You can go with normal java project also, then convert it to Maven WAR project to achieve the same thing.

  19. Sai says:

    I created one axis2 webservice through eclipse IDE, and created axis2 client side code. But while invoking the service from client stub, I am unable to find a method response.get_return(). Please any one can help me out from this issue.

  20. Anjan says:

    I am a newbie to java web services. I prepared a .aar file and deploying it in tomcat5.5.35 with axis2.

    Now while running the web service I found a weird error

    org.apache.axis2.dataretrieval.DataRetrievalException: Failed to load from file, META-INF/ServiceData.xml

    I cannot figure out the reason behind it. My .aar file contains a services.xml listing the services. But why axis is trying to load that ServiceData.xml file. I am using jdk1.6 and tomcat5.5 with axis2.

    The complete error log is given below

    org.apache.axis2.dataretrieval.DataRetrievalException: Failed to load from file, META-INF/ServiceData.xml
    at org.apache.axis2.dataretrieval.DataRetrievalUtil.buildOM(
    at org.apache.axis2.dataretrieval.AxisDataLocatorImpl.loadServiceData(
    at org.apache.axis2.description.AxisService.getDefaultDataLocator(
    at org.apache.axis2.description.AxisService.getDataLocator(
    at org.apache.axis2.description.AxisService.getData(
    at org.apache.axis2.description.AxisService.getWSDL(
    at org.apache.axis2.description.AxisService.printWSDL(
    at org.apache.axis2.transport.http.ListingAgent.processListService(
    at org.apache.axis2.transport.http.AxisServlet.doGet(
    at javax.servlet.http.HttpServlet.service(
    at javax.servlet.http.HttpServlet.service(
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(
    at org.apache.catalina.core.StandardWrapperValve.invoke(
    at org.apache.catalina.core.StandardContextValve.invoke(
    at org.apache.catalina.core.StandardHostValve.invoke(
    at org.apache.catalina.valves.ErrorReportValve.invoke(
    at org.apache.catalina.core.StandardEngineValve.invoke(
    at org.apache.catalina.connector.CoyoteAdapter.service(
    at org.apache.coyote.http11.Http11AprProcessor.process(
    at org.apache.coyote.http11.Http11AprProtocol$Http11ConnectionHandler.process(
    Caused by: File does not exist in the Service Repository! File=META-INF/ServiceData.xml
    at org.apache.axis2.dataretrieval.DataRetrievalUtil.getInputStream(
    at org.apache.axis2.dataretrieval.DataRetrievalUtil.buildOM(
    … 22 more
    16:20:23,031 DEBUG StAXUtils:263 – XMLStreamReader is org.apache.axiom.util.stax.dialect.WoodstoxStreamReaderWrapper
    16:20:23,046 DEBUG StAXUtils:263 – XMLStreamReader is org.apache.axiom.util.stax.dialect.WoodstoxStreamReaderWrapper
    16:20:23,046 DEBUG StAXUtils:680 – About to create XMLOutputFactory implementation with classloader=WebappClassLoader
    delegate: false
    ———-> Parent Classloader:

  21. vishal says:

    hey i am acing problem in creating stub using https protocol.
    help me !!

  22. Kader says:

    Hi pankaj,

    I did my self with your steps.but i am unable to create generate.wsd and generate.service.when i run the ant file in command project shows the build folder,but it didn’t having this two files.kindly help me.

  23. Mandeep Singh says:

    Dear Pankaj, thanks for the wonderful article.

    I am getting an exception when I run the client code. Its an org.apache.axis2.databinding.ADBException: Unexpected subelement.

    I also tried the example using a simple data type (String) instead of a complex one (object), and it worked fine. I am not sure why it doesn’t work in the case of an object (bean).

    One more thing… I used the CodeGen Axis 2 wizard to produce the WSDL and the Java Stubs from the WSDL. Would that be a problem in any way?

    Many thanks for your help.

    Cheers !

  24. Swarndeep Singh Tomar says:

    Nice article!
    I have question regarding defining occurances(minOccurs and maxOccurs) for elements (name, id in your example). I was able to set maxOccurs to unbounded by making it an array but no idea how to limit to some numbers.
    Also, whats the way to set nillable=false for elements.

    I found that @XmlElement(required=true) seems not to work with axis2. Is that correct?


  25. Swarndeep Singh Tomar says:

    Nice article!
    I have question regarding defining occurances(minOccurs and maxOccurs) for elements (name, id in your example). I was able to set maxOccurs to unbounded by making it an array but no idea how to limit to some numbers.
    Also, whats the way to set nillable=false for elements.


  26. Dennis says:

    Nice article Pankaj. This should be added to the Axis2 site.

    1. Pankaj says:

      Thanks for such a nice compliment, I appreciate it but adding it to Axis2 articles list is not in my hand.

  27. Shiva says:

    Hey Pankaj.. Really nice article.. Do you have any material on maven?

    1. Pankaj says:

      I am writing a tutorial on maven, will be up in few days. 🙂

      1. rakesh says:

        Could you please let me know if we have mavenized axis2 sample webservice in place, If yes please share the steps to do that. Thanks in advance

  28. John Holland says:

    Really good tutorial! Do you have any other ones?

    1. Pankaj says:

      Let me know which tutorial you want.

  29. Sushil says:

    Do we need to run the Axis2ClientUsingStubsFromAnt as JAVA APPLICATION?

    1. Pankaj says:

      Yes, run it as java program.

  30. chatting_enabled says:

    Suppose I have a class say MyBanSubClass that extends MyBean and I want to send it to the getObjectData() service function .

    But the issue I am facing is i dont see the MyBanSubClass in the generated WSDL. So is it that whatever is exposed in Service only that is generated or shown as part of WSDL ?

    If yes then how should I make MyBanSubClass visible to the client?

  31. Sam says:

    Now I got the following error:

    C:\work\ixsystems-workspace\Axis2WSImplementation\build.xml:28: taskdef class cannot be found
    using the classloader AntClassLoader[]

    Total time: 0 seconds

    1. Pankaj says:

      It seems to be an issue with your Classpath settings, please check your environment variables and make sure that required classes are present.

  32. Sam says:


    I got the following error:

    sam@sam-PC /cygdrive/c/work/ixsystems-workspace/Axis2WSImplementation/resources
    $ ant generate.wsdl
    Buildfile: C:\work\ixsystems-workspace\Axis2WSImplementation\resources\build.xml

    [javac] C:\work\ixsystems-workspace\Axis2WSImplementation\resources\build.xml:21: warning: ‘includeantruntime’ was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds

    C:\work\ixsystems-workspace\Axis2WSImplementation\resources\build.xml:21: srcdir “C:\work\ixsystems-workspace\Axis2WSImplementation\resources\src” does not exist!

    Total time: 0 seconds

    I think it is my project setup having some problem.
    Can you please pinpoint what is it?


  33. F4 says:

    Great article. Thanks!

Comments are closed.

Generic selectors
Exact matches only
Search in title
Search in content