Web services for environmental applications Practical session setup

Purpose of this document

This document describes how to set up a single desktop machine so that it is ready for a user to work through the "Introduction to Web Services" practical session/tutorial. The tutorial uses the Java programming language exclusively. The application server is Apache Tomcat and the SOAP implementation is Apache Axis. Although these instructions are based on a Windows installation, the same principles and basic steps would apply to an installation on a different platform. It is best if installations are kept separate, i.e. this installation must be performed on each individual machine that is to be used in the practical session.

Note that a separate web server such as Apache is not required. Tomcat is the application server and Axis effectively turns Tomcat into a Web Services server.

Installation of Java

Download the Java 1.4.2 SDK from http://java.sun.com/j2se/1.4.2/download.html. (Later versions of Java should also be fine, but this version is known to work with the tutorial.) Install it. Set the environment variable JAVA_HOME to the installation directory (e.g. C:\j2sdk1.4.2). Add the %JAVA_HOME%\bin directory to the machine's PATH.

Verify that the installation has worked by opening a new command prompt and typing java -version. Information about the installed Java version should be displayed. If not, check that the environment variables (JAVA_HOME and PATH) are set correctly.

Installation of Apache Tomcat

Download version 4.1.31 of Tomcat from http://jakarta.apache.org/site/binindex.cgi#tomcat. (Note that other versions greater than or equal to 4.1.31 should work fine, but may require later versions of the Java SDK. This might cause problems with Axis, but it might not, I haven't tested it. It's safest to stick with 4.1.31 unless you know that later versions are OK). On Windows, it is most convenient to download Tomcat as an EXE file. If installing from the EXE file, accept the default installation option. You may choose an administrator password if you like, but this can be left blank for the purposes of this tutorial. (Note that if permissions prevent installation in the default location, choose another location or perhaps install via a different method, e.g. extracting a ZIP file.)

You should now have an "Apache Tomcat 4.1" group in your start menu. Click on Start Tomcat. Give it a few seconds to start up then open a browser at http://localhost:8080. If you see the Tomcat start page then all is well. You can stop the server at any time by selecting Stop Tomcat from the Windows Start menu. (Note that Tomcat can also be run as a service; the installation procedure will have given you this option.)

Installation of Apache Axis

Axis is an implementation of SOAP, the Simple Object Access Protocol. By installing Axis into Tomcat, Tomcat can be used to host SOAP Web Services. (Tomcat itself is an application server.) Download the Java implementation of Apache Axis version 1.1 from http://ws.apache.org/axis/download.cgi. Only the binaries are needed.

Extract the archive containing the Axis libraries. In the resulting file set you should find a webapps\axis directory. Copy this entire directory to the webapps directory of your Tomcat installation (if you used the default location when you installed Tomcat this will be C:\Program Files\Apache Group\Tomcat 4.1\webapps). Make sure you copy the directory as well, so Tomcat will have a webapps\axis directory too.

Test the installation by restarting Tomcat (you may have to stop it first). Point your web browser at a http://localhost:8080/axis/happyaxis.jsp. You should see the "Axis Happiness Page". This will show whether Axis is correctly installed. You will probably find a message saying "The core axis libraries are present, 1 optional library is missing". This is fine. If any of the core libraries can't be found, follow the instructions on the Axis Happiness Page. (This will probably involve copying some libraries, perhaps jaxrpc.jar and saaj.jar into C:\Program Files\Apache Group\Tomcat 4.1\common\lib.)

Environment setup

To make it easier for tutorial participants to follow the tutorial, it's useful to set a few environment variables. We have already set JAVA_HOME and the PATH so that Java can be run easily from the command line. Set the following environment variables (note that locations may be different, depending on where you installed Tomcat):

CATALINA_HOME = "C:\Program Files\Apache Group\Tomcat 4.1"
AXIS_HOME = %CATALINA_HOME%\webapps\axis
AXIS_LIB = %AXIS_HOME%\WEB-INF\lib
AXISCLASSPATH = %AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;%AXIS_LIB%\commons-logging.jar;
   %AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\wsdl4j.jar;
   %CATALINA_HOME%\common\endorsed\xercesImpl.jar;%CATALINA_HOME%\common\endorsed\xmlParserAPIs.jar

Note that the AXISCLASSPATH is all one long string. The locations of some of the libraries might vary (notice that xercesImpl.jar and xmlParserAPIs.jar are not in the AXIS_LIB directory). You could also choose to copy these libraries elsewhere.

Now add %AXISCLASSPATH% to the CLASSPATH environment variable (or create a new variable called CLASSPATH if it doesn't exist). Make sure the CLASSPATH contains at least AXISCLASSPATH and the current directory, i.e:

CLASSPATH = %CLASSPATH%;%AXISCLASSPATH%;.

Note the ";." at the end of the CLASSPATH!! As a quick (non-exhaustive) test, open a new command prompt and enter "java org.apache.axis.client.AdminClient". You should get a usage message, explaining how to use the AdminClient. If you get any error messages (e.g. ClassNotFoundException), make sure the CLASSPATH is set correctly.