Sunday, 21 February 2010

BCLService - Accessing the web service with a generated client

On my previous post, I explained how you can expose your existing java API as a SOAP web sevice using Apache Axis2. I went through the steps of creating a web service called "BCLService"...Now here's the sequel, we are going to look into how we can interact with the service using a generated client.

This is a step by step guide to interacting with the BCLService using a client based on generated code. This guide uses Axis 2 as an implementation of the SOAP protocol. Axis is a framework for constructing SOAP clients and servers.

1. Requirements:
JDK 1.5 (or latest)
Axis 2 1.4 (or latest)

You can download the latest release of Axis2 from the Apache download site

Apache provides a tool in the Axis2 distribution (WSDL2Java) to generate client side stubs that interacts with the service (You can find WSD2Java in "org.apache.axis.wsdl.WSDL2Java").

2. Generating client stubs using the Apache WSDL2Java tool: Client programs need only to know the EPR and the operation name (both listed on the WSDL) in order to interact with your web service.

In order to generate the stubs, run the following command:

$ sh -uri http://:/axis2/services/?wsdl -o /path/to/your/client/code/
$ WSDL2Java.bat -uri http://:/axis2/services/?wsdl -o /path/to/your/client/code/
-uri Specifies the location of the WSDL file. In other terms, the Endpoint Reference (EPR) of the service with the “?wsdl” argument appended in the end.
-o Specifies the output path for the tool, in other words, the location where you want WSD2Java to generate the client code, Note that you need not to specify the source folder (/src) in the parameter as the source folder will already be added by WSDL2Java

The above command generates 2 java classes. Now, all you need to do is to create a simple class (i.e. which uses the stub to call the service.

3. Calling the Web Service: The following is a sample client class code used to interact with the web service.
Make sure to add all the Axis JARs that the stubs refer to (JARs can be found under AXIS_HOME/axis2-1.4/lib).

public class Client {
  public static void main(String[] args)
                           throws RemoteException {
    MyServiceStub stub = new MyServiceStub();

    /* Invoking the GetCurrentPosition service */

    //Create the request
    MyServiceStub.GetCurrentPosition request =
                 new MyServiceStub.GetCurrentPosition ();

    /* if the method doesn’t take parameters, then just
     skip the request object and instantiate the reponse
     object directly by calling the method on the stub */

    GetCurrentPosition Response response =

    System.out.println("Web Service returned : " +

Now you can compile and run the client code. Its is important to note that the classpath must have all the jars in the "lib" directory of the axis2 distribution when compiling and running the client.

Saturday, 13 February 2010

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 ""

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:

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

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 "" class (javac 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:
3.2 Execute target "create.war" from the ant build file at:
i.e. run command: ant create.war
3.3 Find the generated "axis2.war" inside:
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?


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.


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".