Document last updated 12 April 2001. We are very interested in feedback that would make these materials better. Feel free to write the author, Jonathan Revusky.

(Este documento en español) (Ce document en français)

Hello, Niggle

Following a long tradition in computing, this directory contains a minimal "Hello, World" servlet written on top of the Niggle framework. The objective here is not to do anything particularly interesting. The idea is that, once you manage to build and run the minimal servlet here, you will be set up to move on to more involved examples. At the very least, you will have a servlet runner installed and working and you will have defined a web application context in which to put your examples. You will be out of the starting gate.

These instructions assume that you have the JDK 1.2 (or higher) installed on your machine and that you have installed Tomcat or a servlet container that uses the same configuration scheme. Though these instructions refer to Tomcat, it should not be difficult to get this example working with another servlet engine.

Step 1: Compiling the code.

The trick to compiling the code is to make sure that the compiler can resolve all of the dependencies. To compile this minimal servlet, we need niggle.jar and servlet.jar on the CLASSPATH. In the following, you will have to replace $NIGGLE_HOME by the directory where you unzipped Niggle. On a unix machine, the command would be:


      javac -classpath $NIGGLE_HOME/lib/niggle.jar:$NIGGLE_HOME/lib/servlet.jar *.java

      and on Windows:

      javac -classpath $NIGGLE_HOME\lib\niggle.jar;$NIGGLE_HOME\lib\servlet.jar *.java

At this point, you should have generated the .class files HelloNiggleServletInteraction.class and HelloNiggleServlet.class.

Step 2: Installing the classes and supporting files

In the following, I'll refer to the root directory of your server distribution as $TOMCAT_HOME. If you do not have a servlet runner installed, you can go to http://jakarta.apache.org and the simplest thing to do is to download the latest stable binary release of Tomcat. Once you download the zip file, you simply unzip the archive into the directory which you want to be the parent directory of the tomcat home directory.

Now, relative to the $TOMCAT_HOME location, there is a webapps directory. This is the location where the tomcat server looks for information related to web applications. Each subdirectory of $TOMCAT_HOME/webapps is taken to be the parent directory of a webapp context. We will start by creating our own webapp context by creating a subdirectory called niggletut.

Now, under the niggletut directory, create a WEB-INF directory. On unix systems, case will be important here. That's "WEB-INF" all caps. And under WEB-INF, create 2 further subdirectories: classes and lib.

So, you should have created a directory structure under $TOMCAT_HOME that looks like this:


            $TOMCAT_HOME
                       |
                       webapps
                             |
                             niggletut
                                     |
                                     WEB-INF
                                           |
                                           classes
                                           |
                                           lib

What you need to do now is the following:

Step 3: Testing the servlet

Now comes the moment of truth. Here's what you need to do:

If you are using tomcat, the second step above is achieved by running the startup script in the $TOMCAT_HOME/bin directory. This is either startup.bat or startup.sh, depending on your religious persuasion. (If you already had tomcat running, you had to run shutdown first.)

Since, by default, tomcat runs on port 8080 and maps <web-app-name>/servlet/<servlet-name> to the servlets in a given context, the following URL should do the trick:

http://localhost:8080/niggletut/servlet/HelloNiggleServlet

At this stage, you should see the Hello, Niggle message. If you went through the above steps religiously using the Tomcat 3.2 server on top of Java 2, it is hard to see what could have gone wrong. On the other hand, if you are trying to get the example working with a different servlet container, I see two main possibilities for things going wrong. The first is that the above URL is not quite right and that the servlet is mapped to a different URL. For instance, your server may run by default on port 8000, not 8080 or it might be "servlets" in the URL instead of "servlet". Things like that. The other possibility is that you need to tweak a line somewhere in your server's configuration for it to be aware of the niggletut webapp context you just added. Either of the above problems will make it necessary for you to call upon your own superior hacking skills. You might even get desperate enough to read the documentation.

Once you have managed to build and run this example, please go through the accompanying notes which dissect the various pieces of the minimal app and explain their function.