Monday, April 14, 2008

Hello World with Web Services

“Time for minor skirmishes is over!!! Now we do battle!!!”

Don’t get alarmed by reading the above. I’m still blogging about Web services and related technologies (not about ancient war craft). I just wanted to say that having discussed a lot of theoretical stuff in the previous blog entries (or rather going around and around the bush) now I’m fully armed and ready to start developing and deploying Web services of my own. There are loads of tested and proven methods, tools and IDEs to help Web services developers. So to start with I’m going to stick to a very simple and straight forward method which involves Apache Axis2 (well actually I will be using WSO2 WSAS, which is powered by Axis2), Eclipse IDE and Axis2 Eclipse plugins. It is pretty much a very painless and known-to-work kind of method and ideal for budding Web services developers (and even for pros of the industry). Let this blog entry be a tutorial to those out there who have just stepped into the world of Web services and willing to experiment with the technology (and may the best developer win :-)).

Here’s what you need…

Set them up...

Installing these software is fairly easy and straight forward. Remember to setup the JAVA_HOME environment variable after installing the Java development kit.

(A public WSO2 WSAS instance is available at from which you can test your Web services and get a feel for it.)

Once you have all the software tools you need properly installed and tested we can get on with developing out first Web service.

And here’s the recipe…

Run Eclipse IDE and create a new Java project. (File --> New --> Java Project)

Give the project any name you like.

Create the following class in the project. (Names of the class and the package do not matter. Just give any name of your choice.)

To add a new class to your project simply right-click on the node corresponding to your project on the Package explorer pane and click on ‘New’ and then select ‘Class’ from the submenu.

package testws;

public class MyFirstWS
public String greet(String name)
return "Hi, " + name + ", welcome to Web services World!!!";

As you can see it is a very simple Java class with just one method. It accepts a String parameter called ‘name’ and returns a String value. 

Now save all the files and build the project. (Project --> Build Project)

Then run the Axis2 Service Archiver Wizard. (File --> New --> Other --> Axis2 Wizards --> Axis2 Service Archiver)

Browse and specify the class file location of your project. Generally this is the ‘bin’ folder in your top level project folder. Also check the ‘Include .class files only’ check box (“this is not really necessary, but then again why take any risks right?”) and click ‘Next’.

Next window allows you to specify a WSDL for the Web service. Since we don’t have a WSDL for our service simply check the ‘Skip WSDL’ check box and click ‘Next’.

You can add any additional Java libraries required to run the service from the next Window. Since we don’t need any additional libraries for our service simply click ‘Next’ to proceed. (However if you want to add any additional libraries just enter the full path of the library and click ‘Add’. You may add any number of libraries in this fashion.)

Next window deals with the service.xml file which is important when it comes to deploying the Web service. In this case we will get our service.xml file auto generated. So check the ‘Generate the service xml automatically’ and click ‘Next’ to continue.

Now you can specify the Java class that you want to expose as a Web service. Type the fully qualified name of the class (in my case it is testws.MyFirstWS) and click ‘Load’. The methods of the class should appear in the area below. Select the methods you want to be in your service. Also at the top most text box you can specify a name for your Web service. This name will be displayed to the external parties so best to pick a nice and cool name.

Finally specify a name for the service archive file that will be generated and also a location to save it. Click ‘Finish’ to exit the wizard. If everything went right Eclipse will display a message box saying ‘Service archive generated successfully!’

Now browse to the location you specified in the last step of the wizard. A file with the name you specified and an .aar extension will be there. This is the service archive file of your Web service and you are going to need this file to deploy the Web service. Service archive files are in a way similar to compressed .zip files. They are collections of other files. Mainly it consists of the class files and the service xml.

Now it’s time to put the service on-line. If you are using WSO2 WSAS simply start the server, log on to https://localhost:9443 using your web browser and sign in to the WSAS management console. The default username and password are ‘admin’ and ‘admin’. Click on ‘Services’ and Click on ‘Upload service artifact’ which is the top most link in the page. Browse to the location of your .aar file and click ‘Upload’. WSAS will display a message saying the service archive has been uploaded. (WSO2 WSAS supports hot deployment. So there is no need to restart the server.)

If by chance you are using Tomcat or Axis2 standalone server to deploy Web services copy the .aar file manually to the ‘webapps’ directory of your Tomcat or Axis2 installation. Then restart the server.

So that’s basically it. You have created and deployed a Web service. You can access service by logging into the WSAS management console and clicking on the ‘Services’. Your service will be listed their along with other Web services. Now you can do a lot of things with it. WSO2 WSAS gives you a whole bunch of features to play around with deployed Web services. You can view the WSDL of your service, generate clients for it and even try it out on-line using the WSAS 'Try It' feature.

You can directly invoke the service and test it if you want. Open a browser window and log on to http://localhost:9443/services//greet?name=

If you get a result similar to the following you have done right. It means your Web service is up and running and also it is working without any faults. So pat on your back and be proud of yourself.

Wow!!! Wasn't that easy? Well that's mainly because we used a very powerful IDE to develop the service and a feature rich application server to deploy it. If we had to do everything manually this would have been a pain in the butt. I think we really should appreciate these software tools and the people who have put in a lot of effort to create them.

Please note that I have done the above example in Linux. But the exact procedure can be safely carried out in the other environments like Windows and Mac-OS.

No comments: