By Tom Osborne

With the introduction of the Catalina Servlet engine, Tomcat version 4 boasts improved performance that makes it a Servlet/JSP container worthy of your consideration. However, documentation sources to help you get started with Tomcat are few and far between. Few books are available, and the documentation on the Jakarta site can be confusing.

Let’s take a step-by-step journey through a Tomcat installation, and then discuss creating Web applications using some key Tomcat 4/JSP features.

What is Tomcat?
Tomcat is an open source, Java-based Web application container that runs servlet and JSP Web applications. Tomcat is supported and maintained under the Apache-Jakarta subproject by volunteers from the open source Java community. Tomcat Server is the reference implementation for the servlet and JSP specifications, so it’s probably safe to say that Tomcat Server implements the Apache-Jakarta specifications as well or better than most commercial application servers.

Installing Tomcat 4
To start using Tomcat 4, download at least version 1.2 of the Java Development Kit (JDK) and Tomcat 4 install packages; both are available as ZIP files and Windows install packages. Once you install these two packages, you must add two environment variables: JAVA_HOME and TOMCAT_HOME. The JDK will install in JAVA_HOME directory; Tomcat 4 will install in TOMCAT_HOME.

To test the installation, use the menu options to start Tomcat, if installed via the Windows install program. Or, open a Command Prompt, navigate to the TOMCAT_HOME\bin directory, and run the startup.bat/sh file. Then, open a browser and enter the URL http://localhost:8080. The default Tomcat page should appear.

Web application primer
Before we get started, lets’ review the components that comprise a Web application. The Java Servlet specification defines a Web application as a collection of servlets, HTML pages, classes, and other resources that are bundled and run on multiple containers from multiple vendors. Under Tomcat, these resources are placed into a specific directory structure under the TOMCAT_HOME\webapps folder. The directory structure for a sample Web application (myapp) would be:


The myapp directory is considered the Web application root directory. All JSP, HTML, JavaScript files, and other resources are under this directory. The WEB-INF directory contains resources used by the application, but WEB-INF is not in the public document root—no files contained in this directory structure are accessible by a client. The classes directory (under WEB-INF) contains servlets, beans, and utility classes needed for myapp’s operation. In some instances (log4j), properties files are placed in the classes directory. The lib directory (under WEB-INF) contains Java archive files (JARs), such as the JDBC driver or tag library, on which myapp depends. If a class is present in a JAR file and in the classes directory, the class loader loads the one in the classes directory.

Servlets, JSPs, and the ServletContext
A Java Servlet is a platform-independent component that communicates with Web clients using a request/response model managed by a JSP/Servlet container. To write a servlet, either the GenericServlet or HttpServlet class is extended. The GenericServlet has an abstract service method that must be implemented. The HttpServlet extends GenericServlet and requires you to implement one of these methods: doGet, doPost, doPut, doDelete, init, destroy, or getServletInfo. Typically, the doGet and doPost methods are implemented.�

Good reading

We relied heavily on a chapter in James Goodwill’s book, “Apache Jakarta-Tomcat,” as an informational resource� for this section of our article. This is the only Tomcat-specific book available at this time that we can endorse; however, other titles are due very soon from Wrox, Sams, and Wiley.

Servlets have the following life cycle:

  1. When the Servlet is instantiated, the init method is invoked.
  2. The Servlet services zero or more requests.
  3. The Web application is shut down, causing the destroy method to be called and allowing the object to be garbage-collected.

The init method can be used to initialize properties of the Servlet via the ServletConfig parameter. Initialization parameters set in the web.xml file are passed to the init method in the ServletConfig and can be accessed via the getInitParameter method.

Java server pages allow you to generate dynamic HTML pages by embedding Java logic into the requested document. JSPs are a mix of HTML, special tags, and embedded Java code. Each JSP is translated from this mix into a servlet that is used to send HTML back to the client when the JSP is requested. The generated java code and the class file for this Servlet are stored in a specified location that defaults to the TOMCAT_HOME/work directory. This directory can be specified in the Context element for the Web application. In many instances, if a JSP page is not behaving as expected or if a stack trace with line numbers is displayed, the generated code can be viewed to help determine the problem.

There are certain implicit variables available to a JSP:

  • request – reference to the HttpServletRequest
  • response – reference to the HttpServletResponse
  • pageContext – provides access to the namespaces within the JSP
  • session – reference to the HttpSession
  • application – reference to the ServletContext
  • config – reference to the ServletConfig
  • page – reference to the current instance of the JSP being accessed; analogous to using this in the generated Servlet for this JSP
  • exception – reference to the uncaught exception thrown by a JSP; only available on JSPs with the isErrorPage set to true

The standard JSP tags are:

  • <jsp:useBean> – allows� you to put or look up a bean in the page, request, session, or application scope. (This tag is very useful for maintaining state)
  • <jsp:setProperty> – allows you to set the property of a bean that is already defined and in scope.
  • <jsp:getProperty> �– takes the value of a bean’s property, converts it to a string, and places it in the output stream.
  • <jsp:param> – provides parameters and values to the include, forward, and plugin standard actions.
  • <jsp:include> – includes a page at request time instead of translation time with the @include directive.
  • <jsp:forward> – forwards the request to another resource in the existing Web application.
  • <jsp:plugin> – enables the JSP author to generate HTML using client-browser independent constructs that result in the download and subsequent execution of the specified applet or component (results of the evaluated tag are typically replaced by an <object> or <embed> tag).

The ServletContext can be thought of as a global storage area for a Web application. Each Web application has a ServletContext. Objects stored in the ServletContext persist for the life of the Web application, unless removed.

Building a sample Web application
Now let’s move on to building a sample Web application that consists of a servlet, a bean, and several JSP pages. The Web application will be called myapp and the files will reside in the TOMCAT_HOME\webapps\myapp directory.

The .\ directory contains all JSP files, as you can see in Listing A. The index.jsp page uses the <jsp:forward> tag to effectively make the form.jsp the home page for myapp. The form.jsp page makes use of the <jsp:include> tag to add navigation and two separate forms to complete the form page. Note how the third <jsp:include> tag uses the <jsp:param> tag to pass a parameter to the jsp_form.jsp page. The servlet_form.jsp page is an example of using a servlet for form handling while the jsp_form.jsp page submits to another JSP page. The company_name.jsp page uses the parameters submitted from the jsp_form.jsp page to build the colored company logo. The bean_values.jsp page uses the <jsp:useBean> tag to store/retrieve/modify bean properties in the session and application scope. The variables.jsp page shows examples of using some of the implicit variables available in a JSP.

The .\WEB-INF\classes\myapp directory contains the class files for the Servlet and bean used by the application, as you can see in Listing B. The MyBean class has one property called stringValue. The bean_values.jsp page is used to store an instance of this bean in the session and application scope. The CompanyNameServlet is used as the destination of the form submission on the servlet_form.jsp page. This servlet generates HTML output based on parameters in the request. Note that we’ve overridden the init method to set the companyName property provided in the web.xml file. It’s common practice to have the doGet() or doPost() implementation in one method call the other implementation.

The .\WEB-INF this directory contains the web.xmlfile, as you can see in Listing C, that defines the servlet and a context parameter. Note the init-param specifying the company name. This parameter is extracted from the ServletConfig in the init method of the CompanyNameServlet. The context parameter is accessed in the variables.jsp page.

To run the myapp application, place the files in the TOMCAT_HOME\webapps\myapp directory and start Tomcat. Once Tomcat is running, type the URL http://localhost:8080/myapp into a browser. This should bring up the index.jsp page with the form.jsp contents.

Just scratching the surface
This brief introduction to Tomcat should help get the ball rolling, but there’s a lot more to JSP and configuring Tomcat than we’ve discussed in this article. Tomcat has a server.xml file located in the TOMCAT_HOME\conf directory that allows for further customization, offers a manager application and request-preprocessors called Valves, and is able to implement filters. Tomcat integrates with log4j and the Apache Web server, providing more robust solutions for your Web application. Overall, Tomcat is an outstanding alternative, particularly since it’s free.