Java Server Pages

Installing the Tomcat Server

You can download the Tomcat Server either in binary format or as source code that you compile yourself. If you’re primarily interested in learning about JSP, I recommend that you use the binary download to run the examples in this book and develop your own applications. If you’re a Java programmer and interested in seeing how Tomcat is implemented, feel free to download the source and take a look at the internals.

The binary distribution is available at:

http://jakarta.apache.org/downloads/binindex.html

On this page you find three types of builds:

• Release builds

• Milestone builds

• Nightly builds

Release builds are stable releases that have been tested extensively and verified to comply with the servlet and JSP specifications. Milestone builds are created as intermediary steps towards a release build. They often contain new features that are not yet fully tested, but are generally known to work. A nightly build, however, may be very unstable. It’s actually a snapshot of the latest source code and may have been tested only by the person who made the latest change. You should use a nightly build only if you’re involved in the development of Tomcat.

You should download the latest release build. All examples in this book were developed and tested using the 3.2 (Beta 3) version, but any release later than 3.2 should work fine as well. When you click on the link for the latest release build and select the bin directory, you see a list of archive files in different formats, similar to Figure 4.1.

Figure 4-1. Release build packages

Pick a compression format that’s appropriate for your platform. For Windows, select jakarta-tomcat.zip and save it to your hard drive, for instance in a directory named C:\Jakarta. You can unpack the package either with a ZIP utility program such as WinZip, or by using the jar command that’s included in the Java distribution. Using the Command Prompt window where you set the JAVA_HOME and PATH environment variables earlier, change directory to the directory where you downloaded the ZIP file and unpack it:

C:\>cd Jakarta
C:\Jakarta> jar xvf jakarta-tomcat.zip

For Unix platforms, download the jakarta-tomcat.tar.gz file, for instance to /usr/local, and use these commands to unpack it (assuming you have GNU tar installed):

[hans@gefion /]cd /usr/local
[hans@gefion /usr/local] tar xzvf jakarta-tomcat.tar.gz

If you don’t have GNU tar installed on your system, you can use this command:

[hans@gefion /usr/local]gunzip -c jakarta-tomcat.tar.gz | tar xvf -

This creates a directory structure with a top directory named jakarta-tomcat with a number of subdirectories. Like most software packages, the doc subdirectory contains a file named Readme ; do exactly that. Software distributions change and if, for instance, the instructions in this chapter no longer apply when you download the software, the Readme file should contain information about how to get started.

You also need to set the TOMCAT_HOME environment variable. For Windows, use:

C:\Jakarta>set TOMCAT_HOME=C:\Jakarta\jakarta-tomcat

For Unix, use:

[hans@gefion /usr/local]export TOMCAT_HOME=/usr/local/jakarta-tomcat

The jakarta-tomcat directory contains a number of subdirectories:

bin

Scripts for starting the Tomcat server.

conf

Tomcat configuration files.

doc

Documents describing how to install and start Tomcat. Other documentation is available as web pages once the server is started.

lib

Binary (platform-dependent) modules for connecting Tomcat to other web servers such as Apache.

src

The source code for all servlet and JSP specification classes and interfaces.

webapps

Default location for web applications served by Tomcat.

No matter what your platform, the bin directory contains both Windows batch files and Unix scripts for starting and stopping the server.

Windows Platforms

The Windows files are named startup.bat, shutdown.bat, and tomcat.bat. The tomcat.bat file is the main script for controlling the server; it’s called by the two other scripts startup.bat and shutdown.bat. To start the server in a separate window, change directory to the bin directory and run the startup.ba t file:

C:\Jakarta>cd jakarta-tomcat\bin
C:\Jakarta\jakarta-tomcat\bin> startup

A new Command Prompt window pops up and you see startup messages like this:

2000-09-01 09:27:10 - ContextManager: Adding context Ctx( /examples )
2000-09-01 09:27:10 - ContextManager: Adding context Ctx( /admin )
Starting tomcat. Check logs/tomcat.log for error messages
2000-09-01 09:27:10 - ContextManager: Adding context Ctx( )
2000-09-01 09:27:10 - ContextManager: Adding context Ctx( /test )
2000-09-01 09:27:13 - PoolTcpConnector: Starting HttpConnectionHandler 
 on 8080
2000-09-01 09:27:13 - PoolTcpConnector: Starting Ajp12ConnectionHandler
 on 8007

Just leave this window open; this is where the server process is running.

If you’re running on a Windows 95 or 98 platform, you may see an error message about “Out of environment space” when you try to start the server. That’s because the default amount of space allocated for environment variables is not enough. To change this default, run this command in the Command Prompt window before you run the startup.ba t file again:

C:\Jakarta\jakarta-tomcat\bin>COMMAND.COM /E:4096 /P

This command sets the environment space to 4096 bytes (4 KB). That should be enough for the server. However, If you still get the same message, use a higher value.

For some installations, this command may not work. If it doesn’t work, try this instead:

1. Close the Command Prompt window and open a new one.

2. Click on the MS-DOS icon at the top-left of the window.

3. Select the Properties option.

4. Click on the Memory tab.

5. Change the Initial Environment value from Auto to 4096.

6. Click on OK and try to start the server again.

At this point, the server may not start due to other problems. If so, the extra Command Prompt window may pop up and then disappear before you have a chance to read the error messages. If this happens, you can let the server run in the Command Prompt window with this command instead:

C:\Jakarta\jakarta-tomcat\bin>tomcat run

On Windows NT, first make sure that the Command Prompt window has a large enough screen buffer so that you can scroll back in case the error messages don’t fit on one screen. Open the Properties window for the Command Prompt window (right mouse button in the upper-left corner), select Layout, and set the screen buffer size height to a large value (for instance 999). Unfortunately, the Command Prompt screen buffer cannot be enlarged for Windows 95/98, so scrolling back is not an option. If you run into problems on these platforms, double-check that you have installed the Java SDK correctly and that you have set the JAVA_HOME and PATH environment variables as described earlier.

Unix Platforms

For Unix, the corresponding scripts are named startup.sh, shutdown.sh, and tomcat.sh. Start the server with this command:

[hans@gefion /usr/local/jakarta-tomcat/bin]./startup.sh

If you want Tomcat to start each time you boot the system, you can add the following commands to your /etc/rc.d/rc.local (or equivalent) startup script:

export JAVA_HOME=/usr/local/jdk1.2.2
export TOMCAT_HOME=/usr/local/jakarta-tomcat
$TOMCAT_HOME/bin/startup.sh &

Two more subdirectories under the Tomcat home directory are then created the first time you start the server:

logs

Server log files. If something doesn’t work as expected, look at the files in this directory for clues as to what’s wrong.

work

A directory for temporary files that are created by the JSP container and other files. This directory is where the servlets generated from JSP pages are stored.