Web Services

In this session you will learn to implement and deploy Web Services. Deployed from a web server (such as Tomcat), Web Services enable you to expose a service to remote clients in a way that is platform independent through the use of XML based standards such as the SOAP (Simple Object Access Protocol) communication protocol, and WSDL (Web Service Description Language) which enables you to describe the interface to the service provided.

In order to do achieve this, we will expose a Web Service based beep generator service, similar to that previously seen, using the Apache Axis implementation of the SOAP protocol and the Tomcat server.

1 Setting up your environment

Installing Tomcat

We will use Jakarta tomcat to deploy your Web Service and expose it to the outside world. It is available at:
 
/opt/UCLCScourseware/java/tomcat/jakarta-tomcat-4.1.27
 
In order to start an instance of Tomcat on your local machine, you will need to set the CATALINA_HOME and CATALINA_BASE environment variables as follows:
 
setenv CATALINA_HOME /opt/UCLCScourseware/java/tomcat/jakarta-tomcat-5.0.28 




setenv CATALINA_BASE ~/tomcat
 

A script is available that will create an instance of the Tomcat server in your own file space directory. The script will install the tomcat server in $HOME/tomcat. Run the script as follows:

/opt/UCLCScourseware/bin/create_tc_base ~/tomcat

[Note : if you do not have enough file space, you might want to replace ~/tomcat/ by /tmp/tomcat/ for the Catalina base environment variable and for the execution of the script].

Installing the axis libraries

Copy the axis directory in:

/cs/research/sse/home1/rigel/ucacwxe/public_html/lectures/Z23-04-05/webServices/classes/webapps

into your newly created $HOME/tomcat/webapps directory.

[Make sure you maintain the same directory structure! Use recursive copy to copy all the directory contents (cp –R).]

You will also need to copy the activation.jar file

/cs/research/sse/home1/rigel/ucacwxe/public_html/lectures/Z23-04-05/webServices/classes/activation.jar

into your $HOME/tomcat/shared/lib directory

Add all the jar files to your CLASSPATH

You will need to add to your CLASSPATH the following files from your

$HOME/tomcat/webapps/axis/WEB-INF/lib directory:

axis-ant.jar

axis.jar

commons-discovery.jar

commons-logging.jar

jaxrpc.jar

log4j-1.2.8.jar

saaj.jar

wsdl4j.jar

Rather than add them in individually, source the setenv.sh script as follows (bash):

%> . /cs/research/sse/home1/rigel/ucacwxe/public_html/lectures/Z23-04-05/webServices/classes/setenv.sh

Start tomcat

Go to the $HOME/tomcat/bin directory and type startup to start the server

To see if it works go to http://localhost:8080/axis/ on your browser (It might not work immediately so be patient)

2 Creating the BeepGenerator object

Axis provides us with a simple “instant deployment” mechanism that allows you to create and deploy a Web Service available with a minimum amount of effort. Web Services are typically stateless so we will use the previously covered BeepGenerator example.

Produce a simple BeepGenerator class that defines and implements an emitBeep method so that it outputs a given number of beeps upon request. This should be a full implementation and not just an interface. You may wish to use the method java.awt.Toolkit.getDefaultToolkit().beep() to generate the system beep sounds as well as printing out beep messages for machines with no sound facilities.

Verify that it compiles and if so, rename the BeepGenerator.java file to BeepGenerator.jws and move the produced file to your $HOME/tomcat/webapps/axis directory.

Point your web browser to http://localhost:8080/axis/BeepGenerator.jws to see if the Web Service has been correctly deployed.

3 The Account WSDL interface and stub generation

When deploying your Web Service, Axis produced all the files required for remote clients to interact with it.

Among these files Axis has produced a WSDL definition for your service, which defines in XML the format of all the operations calls and messages supported by your service. This can be used by third-party developers to write a client capable of interacting with your Web Service. Stubs can be automatically generated from the WSDL file as follows:

Point your web browser to http://localhost:8080/axis/BeepGenerator.jws?wsdl and save the file displayed as BeepGenerator.wsdl in a new directory.

Use the Axis WSDL2Java to generate your stubs:

%> org.apache.axis.wsdl.WSDL2Java –p beeppackage BeepGenerator.wsdl
 

All the stub files required should now be available in the beeppackage directory.

4 Writing your client

Using the generated stubs you can now write a client capable of interacting with your deployed Web Service.

Create a Client.java file with a main method that will use the BeepGeneratorServiceLocator to locate an instance of a BeepGenerator service:

BeepGeneratorServiceLocator bgsl = new BeepGeneratorServiceLocator();

BeepGenerator service = bgsl.getBeepGenerator(new URL(http://localhost:8080/axis/BeepGenerator.jws));

service.emitBeep(1);

When the call has been made from the client, the stubs will generate all the SOAP messages and send these to the service pointed to by the locator.