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.
- SevletRunner - JavaSoft
- JServ - Apache
- JRUN - LiveSoftware
- JavaWebServer - Sun
- Servlet Express - IBM
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
- Getting the Servlet CLASSPATH right
- Registering your Servlets
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.
- The CLASSPATH environment (Or System classpath under NT) variable is used generally. If you put a Servlet in your default CLASSPATH your Servlet engine will not be able to reload it dynamically. Your Servlet will get loaded by the default ClassLoader, which does not do dynamic reloading. Therefore, if you change your Servlet you will have to restart your Web Server in order to see your changes! In short, do not put your Servlets in your general CLASSPATH.
- Most Servlet Engines have a HOME/classes and a HOME/servlets directory which they add to your CLASSPATH. DO NOT add the HOME/servlets directory to your general CLASSPATH! If you do, again your Web Server will have to be restarted before chagnes to servlets can take effect.
- Your USER_CLASSPATH (or User's CLASSPATH) can be set from within your Servlet Engine's configuration files. This sets the general classpath under which your Servlet Engine runs, and is really the same as setting a CLASSPATH environment variable. Some Servlet Engines (Java Web Server for example) will actually use your CLASSPATH environment variable; others (Apache-Jserv) require that you set a user classpath in the Servlet Engine configuration file.
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.
- Create a subclass of javax.servlet.http.HttpServlet
- Override the doGet() and/or doPost() methods
- Optionally override the init() and destroy() methods
You are passed two objects in doGet() and doPost():
- HttpServletRequest -- contains information about the request
- HttpServletResponse -- fill this in with response data
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: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.
- Have you got filenames wrong?
- Have you got the CLASSPATH wrong?
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.
- Servlet not found
- No class defined
- Some .properties file cannot be found or isn't being used
- NoClassDefFound or ClassNotFoundException gets thrown
- Document Contains No Data -- some Servlet Engines just cancel the request and send nothing back to the browser, which reports this. Check the error logs for other messages.
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!
api | design | faq | goals | links | license | othertech | quickstart | script | status