The Tomcat Web app Quick Reference Guide
Getting started with Tomcat and web applications? Here's some helpful information about developing, deploying, and debugging your applications with Tomcat.
A Brief Introduction to Java Web Applications
Java web applications are actually a grouping of one or more Java web technologies, which work together to process requests. Following the guidelines laid out in the Java EE specification, these grouped components operate within a runtime environment, which is made up of a number of different Java containers. These containers are specialized implementations of the Java container model, in which a given Java class is responsible for managing interactions with a group of sub-classes.
This model offers a number of benefits, including security (by isolating classes from one another, portability (by decoupling the actual brokering of transactions from the application itself), logical structure (by using hierarchical permissions control and inherited configuration), and modularity (by using standard APIs to allow any type of container to communicate with any other container). However, from a purely functional standpoint, the most important benefit of container management is that each container provides its own persistence control, allowing dynamically-generated user state to be logically preserved across all of an application's components.
Because they are assembled from various discrete technologies, the complexity of a Java web application can vary from extremely simple, using only one or two components, to very complex, incorporating multiple data sources, transformations, server calls, and interoperating functions.
A simple web application might consist of a single JSP page, which contains a single Java call - for example, a request for the current date. A more complicated example might include static HTML pages, JSP pages, servlets for processing user input, JNDI resources such as databases and user realms, multiple data sources that require complex security and data transformation operations to communicate with, and more.
The other advantage of managing web applications with containers is that all configuration differences, additional components, and so on, are managed with the same standards. This allows a single web application to be deployed on any implementation of the Java EE Application Server specification without minimal changes to its internal code. This is made possible, in part, by standard directory structure.
Standard Directory Structure
Java web applications conform to a standard directory structure, specified in the Java EE specification, which designates exactly where specific Java objects should be placed within a program. This method is used for three reasons.
First of all, standard directory structure is designed to integrate non-web Java directory idioms with the needs of a web container. In Java, a correlation between class names and directory structure helps the classloader locate and load the libraries it needs. In the Java servlet specification, this idea is preserved and extended to make the deployment and loading of applications and classes on the server a more logical process.
Before compression, which we will discuss below, all web applications share the following basic directory elements:
This is the root directory of the web application. In addition to the WEB-INF directory, which we discuss below, this directory includes any resource that should be visible to the web container (in other other words, items that are directly accessible via a URL).
This includes items such as static HTML pages and images, JSP pages, client-side class files, and client-side JAR files. These files can be loosely collected within the Document Root or organized into subfolders.
This directory, which is contained within the Document Root, is invisible from the web container. It contains all resources needed to run the application, from Java classes, to JAR files and libraries, to other supporting files that the developer does not want a web user to access. This folder also contains the application's deployment descriptor, an important XML file discussed below.
This directory, contained within WEB-INF, is a repository of all the Java classes and packages required by the application (other than those contained in Tomcat's common or shared class repositories). These will be loaded when Tomcat starts the application, and are only visible to this application. Class files can be organized into packages within this directory, as long as they are organized with the standard Java naming structure.
This directory contains JAR files required by the web application. Classes contained in these files will be decompressed and loaded at application start up.
This file, known as the "deployment descriptor" is an important XML configuration file, which is read by Tomcat when the application is first deployed. This file contains a list of all servlets and resources required by the application, in a hierarchical format that can be used to define security constraints, map servlets to specific URLs, and more.
In Tomcat, a Context represents a single web application. Tomcat uses the Context configuration element to contain information about components required by a given application, such as databases, realms, or custom loaders. Additionally, the Context element can be configured with a wide variety of attributes that control things such as logging, reload permissions, caching, and more.
In older versions of Tomcat, Contexts had to be configured in Tomcat's central server.xml configuration file. However, since Tomcat 5.x, Tomcat has supported the configuration of Contexts at deploy time via a "context fragment" contained in the META-INF directory. When the application is deployed from a WAR file, this file will be copied into the appropriate directory and renamed according to the application's context path.
For more information about the Context element, check out this article: Understanding the Tomcat Context.
Developing Web Applications With Tomcat and Eclipse
Although it is possible to write Java web applications from scratch using a text editor, Java's modular, hierarchical structure and focus on web-based deployments involving multiple interoperating libraries and dependencies make it a language particularly suited to the use of an Integrated Development Environment, or IDE.
These programs offer graphical organization of code, ease complicated editing tasks via menus and hierarchical menus, check code for errors, and more. The most popular open-source Java IDE is Eclipse, which includes a set of plugins called the Web Tools Platform, or WTP that provide full integration with the Tomcat runtime during development.
Setting up Tomcat integration in Eclipse can be tricky. To help you get started, we've created an illustrated, step-by-step guide to Tomcat Eclipse integration.
Building and Deploying Web Applications on Tomcat
The process of packaging a Java web application and publishing it to an application server consists of two steps: build and deployment.
The purpose of the build process is to package the Java source of a project in a format that can be used on an application server. Usually, this process is automated using a tool such as Ant or Maven.
During the build process, the project's Java source code is compiled into class files (which may be packaged into JARs), a directory structure based on the standard structure described above is created, and any dependencies listed in the project are copied into the appropriate bins for Tomcat to find and load them.
Finally, the project is left in one of two formats. If the application is under development, it may be left in an exploded format, so that its individual classes can be replaced and reloaded as changes are made, either manually or using an IDE.
If the application is ready for production, or if the developer is only making minor changes and finds it more efficient to simply redeploy the application after each build, the application will be packaged as a Web Application aRchive, or WAR file.
This file is then "deployed" to Tomcat, using either a static or dynamic method.
Static deployment refers to the deployment of an application to a server while it is not running.
First, the packaged or exploded application is copied to the Tomcat "appBase", a directory which is configured on a per-Host basis. The default appBase location is "$CATALINA_BASE/webapps", or "$CATALINA_HOME/webapps", if no base directory has been defined.
Next, if the application does not contain a Context fragment, one must be added within the appropriate Host element in Tomcat's server.xml configuration file. Finally, the "deployOnStartup" attribute of the relevant Host element must be set to "true" in server.xml.
If all of these steps are completed correctly, Tomcat will deploy the application on start-up, creating a context path as specified in the deployment descriptor and Context fragment.
Dynamic deployment refers to the deployment of an application to a running server. Tomcat supports a number of different dynamic deployment methods.
Deployment Using the Tomcat Manager
Tomcat Manager, the management and administration tool included with all distributions of Tomcat, includes a number of deployment capabilities, accessible using either its URI commands or its web console. Manager can deploy applications to a running server from remote and local directories, from Tomcat's appBase, or from a Context fragment that includes a docBase path, and can handle both exploded and compressed applications.
Enabling and configuring the Manager application is somewhat complicated, for security reasons. To help you get it up and running quickly, we provide an easy guide to configuring the Tomcat Manager.
In addition to the "deployOnStartup" attribute, the Host element also supports an attribute named "autoDeploy". When this attribute is set to "true", Tomcat will enable dynamic deployment features for this Host. Instead of waiting until start-up to check the appBase for new WARs and exploded applications, the Host uses a background process to check for new applications in the directory at a specified interval. Thus, a new application can be deployed to a running server simply by dragging it into the appBase.
This feature allows a number of other dynamic deployment scenarios as well, including re-deployment, using the concept of Watched Resources. For more in-depth information, visit our comprehensive article on Tomcat Deploy procedures.
Deployment with Ant and Maven
Ant and Maven are the two most popular build automation systems available for the Java platform. Ant's focus is automation, while Maven offers additional build management functionality, using modular plug-ins and structured phases to perform tasks such as validation, packaging, and deployment. Both Ant and Maven can be configured to automatically deploy applications.
The easiest way to deploy with Ant is to use the Tomcat Client Deployer, an Apache-provided bundle of Ant tasks that runs a build cycle which compiles, compresses, and deploys an application. You can find more information on the Tomcat Client Deployer here, including detailed use instructions.
Maven, on the other hand, utilizes a Tomcat plug-in, developed as part of the Mojo project, to offer deployment capabilities. You can read more about how to use Maven to speed up your deployment in our helpful Tomcat Maven integration guide.
It is important to note that both Maven and Ant offer their deployment capabilities by manipulating the Tomcat Manager. This means that the Manager must be enabled before either tool can be used for deployment. If you are not familiar with how to do this, don't worry - we've written a step-by-step guide to the process. Just click here!
Debugging Your Web Application
When it comes time to debug your application, Tomcat has you covered. As an implementation of the Servlet specification, Tomcat includes support for the Java Platform Debugging Architecture, or JPDA.
JPDA is a multi-component architecture for debugging Java applications, which consists of three APIs - the Java Debug Interface (JDI), which provides remote debugging support, the Java Debug Wire Protocol (JDWP), which standardizes data formats for debugging requests, and the JVM Tools Interface (JVM TI), which provides various JVM services that can be manipulated by debugging tools. These tools are included in most popular Java IDEs. NetBeans, Eclipse, and IntelliJ all include JPDA-based debugging tools, while JSwat offers stand-alone debugging capability.
Jason Brittain, author of The Definitive Guide to Apache Tomcat (O'Reilly) and MuleSoft's resident Tomcat expert, recently wrote a helpful blog post about debugging your Tomcat-hosted web applications using Eclipse. Click here to check it out!