C H A P T E R 1
Introduction to Apache Tomcat 7
In this chapter, we introduce the world of Apache Tomcat server.
Throughout this chapter, we
- Describe the Apache Tomcat architecture
- Discuss the requirements for installing and configuring Tomcat
- Describe the steps of installing and configuring Tomcat
- Test your Tomcat installation
At the end of this chapter, you will understand the Tomcat architecture, have an instance of Tomcat server installed and running on your computer, and have a sample web application displayed in your browser.
The Apache Tomcat Server
The Apache Tomcat server is an open source, Java-based web application container that was created to run servlet and JavaServer Pages (JSP) web applications. It was created under the Apache-Jakarta subproject; however, due to its popularity, it is now hosted as a separate Apache project, where it is supported and enhanced by a group of volunteers from the open source Java community.
Apache Tomcat is very stable and has all of the features of a commercial web application container – yet comes under Open Source Apache License. Tomcat also provides additional functionality that makes it a great choice for developing a complete web application solution. Some of the additional features provided by Tomcat—other than being open source and free—include the Tomcat Manager application, specialized realm implementations, and Tomcat valves.
Currently supported versions on Apache Tomcat are 5.5X, 6.0X, and 7.0X. Versions earlier than 5.5 are still available for download, but they are archived and no support is available for them, so users are encouraged to use the latest possible version of Tomcat where available.
Major versions on Apache Tomcat coincide with versions of the Java Servlet specification, or Java Servlet API, released. So, Tomcat 5.5X supports Servlet API 2.3, Tomcat 6.0X supports Servlet API 2.4, and the latest Tomcat 7.0 is a reference implementation of current Servlet API 3.0. In addition to Servlet API versions, Tomcat versions support corresponding JSP API versions.
The JVM compatibility also depends on the version chosen. Table 1-1 provides a cross-reference of Tomcat versions, supported JVM versions, and Servlet API and JSP API releases.
Table 1-1. Tomcat Versions and Supported API and JDK Versions
| Apache Tomcat | Servlet API | JSP API | JDK |
| 7.0 | 3.0 | 2.2 | 1.6 |
| 6.0 | 2.5 | 2.1 | 1.5 |
| 5.5 | 2.4 | 2.0 | 1.4 |
| 4.1 | 2.3 | 1.2 | 1.3 |
| 3.0 | 2.2 | 1.1 | 1.1 |
This book will cover version 7 of the Apache Tomcat Server. However, most of the content can be applied to versions 5.5 and 6—where that is not possible, it will be clearly stated.
The Tomcat Manager Web Application
The Tomcat Manager web application is packaged with the Tomcat server. It is installed in the context path of /manager and provides the basic functionality to manage web applications running in the Tomcat server from any web browser. Some of the provided functionality includes the ability to install, start, stop, remove, and report on web applications. Chapter 4 covers the details of the Tomcat Manager web application.
Specialized Realm Implementations
Tomcat provides container-managed security methods for protecting resources within the container. These “databases” of users that can be authenticated by the container are called realms.
We will cover two types of realms supported by Tomcat in more detail: MemoryRealm, where user information is simply read from a file and stored in memory, and JDBCRealm, which uses relational database to store users. You can read more about realms with examples in Chapter 6.
Tomcat Valves
Tomcat valves are a technology introduced with Tomcat 4, and available in all later versions. Valves allow you to associate an instance of a Java class with a particular Catalina container. The configured valve class is then acting as a preprocessor for all requests coming to the container. Valves are proprietary to Tomcat and cannot, at this time, be used in a different servlet/JSP container.
Servlet API defines similar functionality in form of Filters. We will also discuss the differences between valves and servlet filter implementation in Chapter 8.
Further Information
Throughout this book, we will discuss all of these Tomcat-specific features, and a lot of other features that are common to all web application containers. More information about Tomcat can be found on its homepage at http://tomcat.apache.org, which is shown in Figure 1-1.
Figure 1-1. The Tomcat project homepage
You can also subscribe to the Tomcat mailing lists, which can be found at http://tomcat.apache.org/lists.html.
This page contains all of the mailing lists controlled by the Apache Tomcat project. Once you are on the mailing lists page, you can choose the list that you’re interested in.
In addition to the official documentation and mailing lists from the Apache Tomcat Project web site, you can find useful information on a number of web sites and forums online. We’d like to recommend www.tomcatexpert.com, a relatively new web site promoting adoption of Tomcat in enterprise environments.
The Architecture of Tomcat
A Tomcat instance, or server, is the top-level component in Tomcat’s container hierarchy. Only one Tomcat instance can live in a single Java Virtual Machine (JVM). This approach makes all other Java applications, running on the same physical machine as Tomcat server, safe in case Tomcat and/or its JVM crashes.
Note You can still run multiple instances on same physical box, but as separate Java processes running on separate network ports.
Tomcat instance consists of grouping of the application containers, which exist in the well-defined hierarchy. The key component in that hierarchy is the Catalina servlet engine. Catalina is the actual Java servlet container implementation as specified in Java Servlet API. Tomcat 7 implements Servlet API 3.0, the latest specification from Sun.
Listing 1-1 provides an XML representation of the relationships between the different Tomcat containers.
Listing 1-1. XML Outline of the Tomcat Architecture Components
<Server>
<Service>
<Connector />
<Engine>
<Host>
<Context> </Context>
</Host>
</Engine>
</Service>
</Server>Figure 1-2 shows the relationship of the main components of Tomcat architecture that correspond with the described XML code snippet.
Figure 1-2. Tomcat architecture with main components
This instance can be broken down into a set of containers including a server, a service, a connector, an engine, a host, and a context. By default, each of these containers is configured using the server.xml file, which we describe later in more detail.
The Server
The first container element referenced in this snippet is the <Server> element. It represents the entire Catalina servlet engine and is used as a top-level element for a single Tomcat instance. The <Server> element may contain one or more <Service> containers.
The Service
The next container element is the <Service> element, which holds a collection of one or more <Connector> elements that share a single <Engine> element. N-number of <Service> elements may be nested inside a single <Server> element.
The Connector
The next type of element is the <Connector> element, which defines the class that does the actual handling requests and responses to and from a calling client application.
The Engine
The third container element is the <Engine> element. Each defined <Service> can have only one <Engine> element, and this single <Engine> component handles all requests received by all of the defined <Connector> components defined by a parent service.
The Host
The <Host> element defines the virtual hosts that are contained in each instance of a Catalina <Engine>. Each <Host> can be a parent to one or more web applications, with each being represented by a <Context> component.
The Context
The <Context> element is the most commonly used container in a Tomcat instance. Each <Context> element represents an individual web application that is running within a defined <Host>. There is no limit to the number of contexts that can be defined within a <Host>.
Installing and Configuring Tomcat
In this section, we install Tomcat as a standalone server, which means that Tomcat will service all requests, including static content, JSPs, and servlets. Before continuing with the installation steps, let’s take a look at the prerequisites for Tomcat installation.
Requirements for Installing and Configuring Tomcat
Before we get started performing the tasks outlined by this chapter, you need to download the items listed in Table 1-2.
Table 1-2. Tomcat Requirements
| NAME | LOCATION |
| Tomcat 7 | http://tomcat.apache.org |
| JDK 1.6 Standard Edition | www.java.com/en/download/index.jsp |
To install and configure Tomcat, first download the packages from the previously listed locations. You should choose the appropriate downloads based on your operating system. (We cover the steps involved in installing to both Windows and Linux.)
Installing Tomcat Using Windows Service Installer
The first installation we will be performing is for Windows. The first thing you need to do is install the Java Development Kit (JDK). Since we’re using Tomcat 7, we will need JDK 1.6 or later. To download Java, just type download Java in your favorite web search engine, and follow the top result link.
Note Make sure you follow the instructions included with your OS-appropriate JDK.
Tomcat 7 comes with easy-to-use executable Windows installer, which will do all tasks explained in previous section automatically.
First step to do is to download the Apache Tomcat Windows service installer from the Tomcat download page (http://tomcat.apache.org/download-70.cgi). Tomcat Windows installer interface is very similar to any other Windows installer. Follow the steps, choose the installation location, and the installer will take care of extracting and copying files to correct directory, and configuring Environment variables and service properties. Figure 1-3 shows the running Tomcat installer for Windows.
Figure 1-3. Tomcat Windows Service installer
After the installation is completed, you can check that the environment variable CATALINA_HOME has been set, from the System Properties application.
The Windows installer will install Tomcat 7 as a Windows Service automatically, so the Tomcat can be started automatically on Windows start-up, and run in the background as a Windows Service.
If you are not going to perform a Linux installation, you should skip the section “Installing to Linux” later in this chapter and move on to the section “Testing Your Tomcat Installation.”
Manually Installing on Windows
If you want to control all aspects of Tomcat installation, manage the environment variables required for Tomcat to run and configure your system so you have easy command line access to your Tomcat server, you will need to install Tomcat manually.
For a manual Tomcat installation, you will need to have installed and configured Java Runtime Environment. For this example, we will install the JDK to drive D:, so therefore JAVA_HOME directory is D:jdk1.6.
To check whether Java is configured correctly, run your version of Java from the Windows command prompt. You should get the full version of the installed JDK.
After you have extracted Tomcat, you need to add two environment variables to the Windows system: JAVA_HOME, which is the root directory of your JDK installation, and CATALINA_HOME, which is the root directory of your Tomcat installation. To do this in Windows, perform the following steps:
- Open the Windows Control Panel, select System and Security, and then click on System in the list of available options. You should see an image similar to that shown in Figure 1-4.
- Now select Advanced system settings from the list in the left-hand side menu. You should see a dialog box similar to that shown in Figure 1-5.
Figure 1-5. Windows System Properties dialog box – Advanced tab
- Next, click on the Environment Variables button. You will see a dialog box similar to that shown in Figure 1-6.
- Now, click on the New button on the System Variables section of the Environment Variables dialog box. Add a variable named JAVA_HOME, set its value to the location of your JDK installation, and click OK to complete the step.
- Your final step is to repeat Step 4, but this time using CATALINA_HOME for the variable name and the location of your Tomcat installation as the value. For our installation, we are setting the value to C:optTomcat7. Figure 1-7 shows the settings associated with our installation.
- Make sure you click OK to accept the new variable, and then click OK in the Environment Variables and System Properties dialog boxes to accept all your changes.
That is all there is to it; Tomcat is installed and configure on your Windows system. Before we test the installation, let’s take a look at the automated process of installing Tomcat on Windows, using Tomcat Windows Service Installer.
Installing to Linux
A Linux installation is a much simpler process compared to a Windows installation. The first thing you need to do is install the downloaded JDK.
You can either download the correct Java version from www.java.com, or use built-in application management tool for Linux to download and install Java automatically. On Debian/Ubuntu Linux for example you can install Java by running following command:
sudo apt-get install sun-java6-jdkWe will assume at this point that the JDK is installed to /usr/local/java/jdk1.6.0_02.
To check whether Java is configured correctly, run your version of Java from the command line. You should get the full version of the installed JDK.
After the JDK has been installed, you need to set the JAVA_HOME environment variable. To do this in Linux, find the shell that you are using in Table 1-3 and type the matching command. You need to replace /usr/local/java/jdk1.6.0_02 with the root location of your JDK installation.
Table 1-3. JAVA_HOME Environment Commands
| SHELL | JAVA_HOME |
| Bash | JAVA_HOME=/user/java/jdk1.3.0_02 export JAVA_HOME |
| Tsh | setenv JAVA_HOME /user/java/jdk1.6.0_02 |
You now need to extract the Tomcat server to a directory of your choosing. This directory will become the CATALINA_HOME directory. For this installation, we assume that Tomcat is installed to /opt/tomcat7.
The last step is to set the CATALINA_HOME environment variable. Find the shell that you are using in Table 1-4 and type the matching command. You need to replace /var/tomcat with the directory of your Tomcat installation.
Table 1-4. CATALINA_HOME Environment Commands
| SHELL | CATALINA_HOME |
| Bash | CATALINA_HOME=/var/tomcat export CATALINA_HOME |
| Tsh | setenv TOMCAT _HOME /var/tomcat |
And that is all there is to the Linux installation. You should now be able to move on to the next section, “Testing Your Tomcat Installation.”
Testing Your Tomcat Installation
To test the Tomcat installation, you need to first start the Tomcat server. Table 1-5 contains the startup and shutdown commands for both operating systems.
Table 1-5. Tomcat Startup/Shutdown Commands
| OS | STARTUP | SHUTDOWN |
| Windows | CATALINA_HOMEinstartup.bat |
CATALINA_HOMEinshutdown.bat |
| Linux | CATALINA_HOME/bin/startup.sh |
CATALINA_HOME/bin/shutdown.sh |
Note If you have installed Tomcat on Windows, a folder was placed in your Windows Start menu with shortcuts that allow you to start and stop your Tomcat server from there.
Once Tomcat has started, open your browser to the following URL:
http://localhost:8080/You should see a page similar to that shown in Figure 1-8.
Figure 1-8. The Tomcat default homepage
Tomcat is by default accepting all requests on port 8080. This is set on purpose, to clearly differentiate Java servlet container from the standard HTTP servlets that are accepting incoming requests on port 80 (for example MS IIS or Apache Http Server). If you would like to have all requests serviced on the default HTTP port of 80 instead of port 8080, you need to make the following change to the CATALINA_HOME/conf/server.xml file and restart Tomcat.
Find the following line in the server.xml file:
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector" port="8080"
minProcessors="5" maxProcessors="75" acceptCount="10" debug="0"/>and change the port property to value “80,” as shown in the following code snippet:
<!-- Define a non-SSL HTTP/1.1 Connector on port 80 -->
<Connector className="org.apache.catalina.connector.http.HttpConnector" port="80"
minProcessors="5" maxProcessors="75" acceptCount="10" debug="0"/>Now you have to restart Tomcat. In order to restart Tomcat instance, first stop the server using the shutdown command for your operating system. When the command finishes, start the server again using the startup command. Table 1-5 shows startup and shutdown commands for Windows and Linux, respectively.
After Tomcat is restarted, you will be able to open your browser to the following URL and see results similar to those shown previously in Figure 1-8:
http://localhost Note This URL does not have the port number specified. The URL convention for browsers is that if the port is omitted from the URL, value 80 is assumed. Therefore, URL http://localhost:80/ would have the same effect.
The next step is to verify if the JSP pages are handled correctly from the Tomcat. You do this by executing one of the JSP examples provided with the Tomcat server. To execute an example JSP, start from the page shown in Figure 1-8 and choose JSP Examples. You should see a page similar to that shown in Figure 1-9.
Figure 1-9. The JSP examples page
Now choose the JSP example Date and select the Execute link. If everything was installed properly, you should see a page similar to Figure 1-10 (with a different date, of course).
Figure 1-10. The JSP date page
If you do not see the previous page, make sure that the location of your JAVA_HOME environment variable matches the location of your JDK installation.
Summary
In this chapter, we introduced the Apache Tomcat server and discussed its main components and architecture. We went on to install and configure Tomcat on both Windows and Linux. We also discussed some simple steps to test your new installation and run Tomcat-provided JSP examples.
In the next chapter, “Deploying Web Applications to Tomcat,” we begin our discussions on how to create and deploy real Web applications using the Tomcat server.