SOAP Web Services made easy with Axis2

Apache Axis2 provides utilities for generating and deploying web service client and servers. I'm not going to get into the details of its architecture or its improvements compared to earlier versions of Axis. You can visit Axis2 home page for a detailed description.

This tutorial takes you through the necessary steps required to expose your existing classes as a web service using Axis2 for Java.

Requirements: First download Axis2 from the Apache website and install it according to the "installation.txt" found inside the package.

Set AXIS2_HOME to your environment variables and also "%AXIS2_HOME%/bin" (include the bin directory) to your PATH

Scenario: You have a simple bean that provides a service to a client application (i.e. The client gives the name of a football team in the Brazilian cup league and the server responds with the team's current position in the league) This is done by invoking the "getCurrentPosition(String team)" of the class "BCLService.java"

Exposing your class as a web service: Actually, what you expose are the methods of the class and not the class itself. You can expose the "getCurrentPosition(String team)" method to the client by simply making it available in a configuration file.

1. Configuration: Create a simple XML file "service.xml" which will inform Axis2 about its services. The following is a sample "service.xml" for our "BCLService" class:

<service>
  <parameter name="ServiceClass" locked="false">
    com.xyz.BCLService
  </parameter>
  <operation name="getCurrentPostion">
    <messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver" />
  </operation>
</service>


Note: The value of the xml element <parameter> must be the full qualified name your java class.
All public methods of your declared class will be exposed by default. If you wish not to expose a method, then use the <excludeOperation> element.
The "locked" attribute of element <parameter> is set to false so that any child node parameter can override it.
The "name" attribute of element <operation> must be the name of the method you wish to expose in the web service (you can add as many as you want, however, Axis2 does not support overloaded methods! Operation names must be unique!)

2. Packaging: Axis2 expects its services to be packaged according to a specific format:
2.1 Create a "tmp" dir (just for packaging purpose)
2.2 Compile your "BCLService.java" class (javac BCLService.java) and move it to the "tmp" directory
2.3 Create a "META-INF" directory inside the "tmp" directory and place the "service.xml" config file inside it.
2.4 Finally, in order to package everything into an axis archive (aar), run the following command from the "tmp" dir level:

Jar cvf BCLService.aar .

Jar The jar command generates an archive file in the same directory
cvf The cvf option indicates that you want to create a JAR file in verbose mode and that the output should go to a file rather than to stdout. For more information on creating jar files, visit SUN's Tutorial "Packaging Programs in JAR"
BCLService.aar Is actually a jar, just renamed to "aar" (axis archive) to distinguish from other jars – note that this is optional
. Package everything in the current directory

3. Hosting the Service: Below are the 2 most popular ways of hosting the service:

* Using the Simple HTTP Server that comes in Axis2 distribution
* Use Axis2 to generate a WAR file and deploy it in a servlet container of your choice. (i.e. Tomcat)

The following steps will take you through the 2nd option (create WAR from AAR):

3.1 Place your newly created "BCLService.aar" in the following directory:
%AXIS2_HOME%/repository/services
3.2 Execute target "create.war" from the ant build file at:
%AXIS2_HOME%/webapps/build.xml
i.e. run command: ant create.war
3.3 Find the generated "axis2.war" inside:
%AXIS2_HOME%/dist
3.4 If you’re using Tomcat as your servlet container, drop the WAR file in the "webapps" dir of Tomcat, then start the server.

4. Running the web service application: To verify the deployment go to: http://<HOST>:<PORT>/axis2/
Follow the "services" link and check that the "getCurrentPosition(String name)" operation is available from the list of operations.

It will also list the endpoint reference URL (EPR) but you will not be able to access it from the browser since Axis2 doesn’t expect input from the browser.

Click on the "BCLService" service link to view its WSDL file. Clients can now simply look up your WSDL to find out what operations your service exposes in order to call them.

Note that Axis2 generated the WSDL file for you, however, you are also free to create one or your own, just drop your own WSDL file (i.e. BCLService.wsdl) in the META-INF directory of the Axis Archive (AAR).

Check out my post on BCLService - Accessing the web service with a generated client for steps on how you can interact with the web service.

-----------------------------------
Axis2 vs CXF

Both are web service frameworks under the Apache umbrella of but what is it that differentiate them from one another?

Axis2

1. Axis2 evolved from the well know Axis 1.
2. The Axis concept is more of a stand alone web service (separate webapp), independent of other applications with its own architecture.
3. Suitable for larger web services, most configuration done via XML files.
4. Packages its own archive: AAR
5. When you build a service in Axis2, it's default behaviour is that you can access it using SOAP or REST request. Axis2 will look at the request "content-type" header and figure out whether to process the request as SOAP or REST.

CXF

1. CXF is the result of a merge between Celtix and XFire.
2. You can easily embed CXF into your application, it has good Spring integration, no extra XML configuration files.
3. Packaged in a WAR archive.
4. You can use JAX-RS annotations to build RESTfull services just like Jersey but needs extra config file "cxf.xml".