Servlet Guide

WebMacro is a Servlet Framework--this guide provides a brief overview of Servlet Engines and other things you'll need to set up a Servlet environment and use it. Whether or not you use WebMacro, this guide should help you get started with servlets.

The documentation that comes with Servlet Engines is not usually very good, so this guide will give you an overview of the key things you have to get right in order to get your Servlet Engine working, and write servlets.

Servlet Engines

In order to run Servlets you need a Servlet Engine. This is either a stand alone Servlet Runner, or an add on to your web server.

Each Servlet Engine has its own peculiarities and advantages. There are good Servlet Engines available both as commercial and free products.

Here's some of the more common Servlet Engines:

ServletRunner is a stand-alone Servlet Engine which implements the JSDK environment, and not much more. You can use it as your Servlet Engine, though it is primarily intended for testing purposes.

JServ and JRUN are plug-ins to your Web server. JServ is oriented toward the Apache server; JRun will work under a variety of servers. JServ is free under an Apache style license; JRun is a commercial product though there is a free lite version available.

Sun's JavaWebServer (JWS) is a complete web server writtein in Java. Naturally it also includes a Servlet Engine based on Sun's JSDK.

IBM's ServletExpress is closely related to their WebSphere line of server products.

Which Servlet Engine you select is largely a matter of preference, determined by what you're most familiar with and what features are most desirable.

WebMacro works fine with all of the above Servlet engines--and most likely others as well.

JSDK: Java Servlet Development Kit

In order to program Servlets you need a copy of the Java Servlet Development Kit. Under Java 1.1 you need to download this separately from Sun's servlet page (below); under Java 1.2 some parts of the JSDK are part of the core language.

Still, in either case you will need a Servlet Engine to get a complete implementation of the Servlet Environment--including some core parts of the JSDK.

Your Servlet Engine will come with an implementation of the JSDK. Alternately, you can download a reference implementation of the JSDK from JavaSoft's website:

At this site you'll also fund some Servlet tutorials, the Servlet specification, links to Servlet resources, and more.

Servlet Configuration

Configuring your Servlet Engine breaks down into three main issues: Here we go:

Installing your Servlet Engine

You'll have to refer to the documentation that comes with your Servlet Engine for a complete explanation. Here I'll just mention that you need to pay attention to the issues raised under Servlet Troubleshooting below.

Getting the Servlet CLASSPATH right

Since Servlet CLASSPATHS are such a problem, I'll go into it in some depth.

There are several places you can set a CLASSPATH from in most Servlet Engines:

You should refer to your Servlet Engine's documentation for a complete explanation on how it sets and uses CLASSPATH information--but keep in mind the issues raised above.

Servlet Programming

In order to program servlets, first you need to install the JSDK and get the javax.servlet.* and javax.servlet.http packages into your CLASSPATH.

The next few steps are straightforward:

Your Servlet's doGet() method will be called when the Servlet Engine receives a GET request that maps to your Servlet. Similarly, it will call your doPost() method when a POST request arrives.

You are passed two objects in doGet() and doPost():

At this point you may want to read my article on correct Servlet design: Fundamentals of Servlet Design, which describes the design underlying the Webmacro Servlet Framework.

You may want to have a look at WebMacro and see whether it would help you in what you're doing. It's a generic framework for designing servlets which includes an HTML template engine--saving your servlet from having to generate HTML directly.

It also includes a variety of library tools designed to make many common servlet programming tasks simpler.

Best of all, it's free.

Installing your Servlet

Once you've written your servlet, place it in your HOME/Servlets directory.

This is the directory in which your Servlet Engine will look to load servlets. Many Servlet Engines will reload your servlet each time its last-modified date changes--otherwise you will have to restart your Servlet Engine.

If your Servlet does not work, check your Servlet Engine's log file to find out why, and look through the information in the next section.

Servlet Troubleshooting

Whenever you have a problem with Servlet configuration, getting a servlet to run, or working with a Servlet Engine, there are always two usual suspects:
  1. Have you got filenames wrong?
  2. Have you got the CLASSPATH wrong?
Filename issues are particularly tricky with servlets, since it is not always obvious what a filename is relative to. A good rule of thumb is to use an absolute filename whenever possible; if that is not possible search through your Servlet Engine's documentation to determine exactly what filenames are relative to.

A second, more subtle issue with filenames has to do with Java properties issues. Many Servlet engines, Servlet tools, and Servlet Frameworks use .properties files to store configuration information. Beware that in a Java.properties file the \ character is the escape character. This is an issue for NT/Win95 users: You cannot write "C:\Servlets" in such a file. Instead reverse the slash and write "C:/Servlets" (Unix style).

As for the CLASSPATH, just double and triple check that all of the classes your Servlet uses appear someone on the CLASSPATH. This seems simple, but check again--more than half the problems people report on the WebMacro mailing list have to do with incorrect CLASSPATH settings.

Here are some symptoms that you got the CLASSPATH wrong:

Some of the above may be caused by other errors, but all can occur if your Servlet CLASSPATH is incorrect.

WebMacro Servlet Framework

Now that you know a little bit about servlets, I hope you're excited! Please take a look around the site and examine the WebMacro Servlet Framework, which was mentioned above.

I believe that the design principles underlying WebMacro really are the right way to do things. Even if you don't use WebMacro, you probably should follow this general design.

You check WebMacro out by examining the links below, or else just download WebMacro and try it out!


Introduction | Download

api | design | faq | goals | links | license | othertech | quickstart | script | status