Introduction to Tomcat 5.0 --- the Open-Source servlet container of choice

Tomcat is the de-facto web server of choice. Written entirely in Java, you have access to the entire code (if you want to make changes). Read to get an introduction to Tomcat, where to download, how to install it on your machine and know about the xml files of importance.

Introduction

Tomcat is an official Reference Implementation of the JSP 2.0 and Servlet 2.4 specifications. The homepage of Tomcat is http://jakarta.apache.org/tomcat/index.html. You can download binaries or source for all three major operating systems, namely, Windows, Unix and Macintosh. (To get a hold of the basics of web server, servlet container, the concept of 'specifications', you can refer my February article at http://www.orafaq.com/articles. The title is 'HTTP Basics, Web Server, Servlet Container and the Java Servlet API').

Downloading and Installing

While the step of downloading is familiar, what to download is more tricky. Jakarta maintains a site solely for downloading all its products. It is important to understand different kinds of builds. As an application developer, I would download the 'Milestone' build. There are other builds meant for developers who are working on adding features to their software. The URL for downloading Tomcat 5.0.25 is http://apache.gnusoft.net/jakarta/tomcat-5/v5.0.25/bin/. There are various flavors of Tomcat. What we need, as an application developer, is the file called jakarta-tomcat-5.0.25.zip.

You have to set your TOMCAT_HOME. This is going to be a 'system' variable. In Windows 2000 and XP, you can go to Control Panel, System, Advanced tab and then click on 'Environment Variables', and then click on the 'New' button. Add 'TOMCAT_HOME' as the name of the variable, and the bin directory of Tomcat installation as the value. In order for you to run Tomcat, you will need an environment variable, and that is our 'JAVA_HOME'. This will be set to the Java SDK (Software Development Kit) bin directory. 'bin' directory is usually the folder which has the binary files. You can download JDK 1.4 from http://java.sun.com/j2se and follow links. You can start Tomcat by double-clicking the startup.bat in the 'bin' folder, or run startup.sh on a LINUX/UNIX environment.

XML files of interest

server.xml

This has entries for port in which the server is going to run, database realms and other cluster related information. A sample file looks like:

<Server port="8005" shutdown="SHUTDOWN" debug="0">
<Listener
   className="org.apache.catalina.mbeans.ServerLifecycleListener"
   debug="0"/>
<Listener
   className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"
   debug="0"/>

<GlobalNamingResources>

   <Environment name="simpleValue" type="java.lang.Integer" value="30"/>

   <Resource name="UserDatabase" auth="Container"

      type="org.apache.catalina.UserDatabase"

      description="User database that can be updated and saved">

   </Resource>

   <ResourceParams name="UserDatabase">

      <parameter>

         <name>factory</name>

         <value>org.apache.catalina.users.MemoryUserDatabaseFactory</value>

      </parameter>

      <parameter>

         <name>pathname</name>

         <value>conf/tomcat-users.xml</value>

      </parameter>

</ResourceParams>

</GlobalNamingResources>

 <!-- Define the Tomcat Stand-Alone Service -->

<Service name="Catalina">

   <Connector port="8080" maxThreads="150" minSpareThreads="25"

              maxSpareThreads="75"

              enableLookups="false" redirectPort="8443" acceptCount="100"

              debug="0" connectionTimeout="20000"

              disableUploadTimeout="true" />

   <Realm className="org.apache.catalina.realm.JDBCRealm" debug="99"

          driverName="oracle.jdbc.driver.OracleDriver"

          connectionURL="jdbc:oracle:thin:@ntserver:1521:ORCL"

          connectionName="scott" connectionPassword="tiger"

          userTable="users" userNameCol="user_name" userCredCol="user_pass"

          userRoleTable="user_roles" roleNameCol="role_name" />

   <Host name="localhost" debug="0" appBase="webapps"

         unpackWARs="true" autoDeploy="true"

         xmlValidation="false" xmlNamespaceAware="false">

...

...

</Server>

web.xml

This is a standard file for any web application. It is called the 'deployment descriptor'. It has entries for all servlets, their initial parameters (if any), servlet mappings, MIME-mappings, etc. Each web application will have one and only one web.xml file. A typical deployment descriptor would look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    			"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
	<servlet>
        <servlet-name>Fine</servlet-name>
        <servlet-class>
          		abc.def.FineServlet
        </servlet-class>
        <init-param>
            <param-name>fineLevel</param-name>
            <param-value>10</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

<servlet-mapping>

        <servlet-name>Fine</servlet-name>

        <url-pattern>/</url-pattern>

    </servlet-mapping>

<session-config>

        <session-timeout>30</session-timeout>

    </session-config>

<mime-mapping>

        <extension>body</extension>

        <mime-type>text/html</mime-type>

    </mime-mapping>

<mime-mapping>

        <extension>bin</extension>

        <mime-type>application/octet-stream</mime-type>

    </mime-mapping>

<mime-mapping>

        <extension>doc</extension>

        <mime-type>application/msword</mime-type>

    </mime-mapping>

</web-app>

Explanation of the above deployment descriptor:

The above file is an XML document. An XML document is a document written against some specifications. Those specifications can be a 'DTD' (Document Type Definition) or a 'schema'. In this case, the file is validated against a DTD. The DTD is located at http://java.sun.com/dtd/web-app_2_3.dtd as seen in the second line of the file. The first line is a mandatory line that has to be written, in order for a XML document to be a proper document. It specifies the version of XML used, and also the character set. In this case, the character set is "ISO-8859-1". The root element is 'web-app'. There can be one and only one root element.

The child elements are servlet, servlet-mapping, mime-mapping, etc. You can see the DTD at the address mentioned above. The DTD is standard for any web application. The 'servlet-element' declares a servlet whose name is 'Fine'. The actual package and the name of the Servlet class is also declared. When the web container starts it instantiates a servlet of this kind and associates it with the name. The initial parameters are set to the ServletConfig class, and thus can be retrieved at runtime. This is a neat way of setting values to variables declaratively. You do not have to find a class and change code. Servlet mapping elements are used by the web container to determine which servlet to serve, depending on the URL sent from the browser. If the URL ends with a '/', in this case, servlet 'Fine' is offered for service. When the client requests a document other than the usual HTML (maybe a Microsoft Word document, might be an audio, video file, etc.), then the container checks for the mime-mapping element. The extension of such files and corresponding mime-type is documented in the descriptor.

The <load-on-startup> is used for pre-loading servlets. Servlets are usually thought to be instantiated when the first request comes in. However, we can have the servlet instantiated and left in the container right when the server starts. This element tells us the order in which it should be instantiated. In this case, there is only one servlet, hence the value is 1. Had there been two, we could have given the second servlet a value of '2' for the same element. This means Fine servlet will be instantiated and then the next one.

tomcat-users.xml

Simple file to configure usernames, passwords for different roles. A sample file would look like:

<tomcat-users>
    <user name="adam" password="toyota" roles="admin" />
    <user name="dev"  password="web" roles="developer"  />
    <user name="dev"   password="web" roles="admin, developer" />
</tomcat-users>

Role-based security revolves around declarations in xml files. You specify a 'role' and then you can assign users to those roles. An easy role to imagine would be an 'admin' role for someone who is going to have administrative rights. Another role would be a user. This is the sole purpose of this file.

Logging

Tomcat automatically puts all its log information in a file called 'catalina.out' in <Tomcat_Install_Dir>\jakarta-tomcat-5.0.25\logs.

Summary

This article tries to introduce the inquisitive to Tomcat servlet engine. For those really new is strongly encouraged to read my February article, and also strongly urged to post questions, comments on this site, for open discussion. There are many related technologies that you need to understand. For example, understanding the basics of a XML document, and what a XML Parser does. Covering XML parsers and XML DTD's were outside the scope of this article.

Prepared by Saikat Goswami, Boston, Massachussets, sai_nyc@hotmail.com