Using Tomcat reload features to speed up development

In compliance with a recommendation in Section 4 of the Java Servlet specification, Apache Tomcat implements methods of systematically reloading Java classes to allow an application's components to be updated without restarting the entire server.  

This feature is very important for development, as server start-up and restart times have proven to be a serious drain to developer productivity as the minutes add up.  In fact, the slow server restart time of Java EE stack application servers was one of the driving forces behind Tomcat's widespread adoption, both for personal and enterprise-level projects.

However, even Tomcat can't start up as fast as it can reload an application while running.  By reloading only the changed classes of an isolated application, developers can get new features up and running within seconds instead of minutes.

Tcat's central management console gives you deep visibility into your web application performance. Reliably stop, start, deploy and redeploy applications, get custom alerts by email or phone, and more. Download Tcat today!

In this article, we'll cover proper configuration and use examples for all of the different mechanisms Tomcat provides for reloading applications and Java classes, including: 

We'll also cover some reasons why you should not use automatic reloading in a production environment, and some alternative solutions.

How reloading works

Before we begin, let's quickly define some of the terms used in this article, to avoid confusion.  

In this article, you'll see references to both "reloading" and "redeploying" web applications.  Although both have to do with propagating changes to an application to the server for use, these terms are not quite interchangeable.

On an Apache Tomcat server, to "reload" an application means to call a method of the StandardContext class called StandardContext.reload() on a given Context.  This method creates a new classloader and new servlets, drops all references to the old servlets, and then calls the Servlet.init() method on the servlet, which brings the servlet to an initialized state, triggering a reload of all classes and libraries by the new classloader.  

By contrast, "redeployment" means that the application is first deleted entirely from its deployed directory, and then re-deployed onto the server from your appBase directory.  

A word on server restart

The most basic, free-of-error way to reload your web application is to restart your Tomcat server.  Although this method is slow, and can be a real hassle if you are running multiple applications on your server, there are a number of situations where a full server restart is the most appropriate method of reloading your application.  

These special cases include cases where your application has components that must be configured in Catalina's server.xml file, such as GlobalNamingResources, or if you have used a symbolic link to your docBase to configure application settings. 

Restarting the Tomcat server is also a way to stop and restart your applications, which allows elements such as web.xml files to be reloaded (although there are ways of reloading these files without stopping the server).

Reloading via the Tomcat manager

The Tomcat Manager, a web application included with all standard distributions of Tomcat, has the ability reload web applications (as well as start, stop, deploy, and undeploy them), even if the application context is not configured as "reloadable".  This is especially useful for reloading an application in a production environment, where Tomcat's automatic reload features should be disabled, or for low-performance environments where automatic reload could cause memory issues.  

Once it has been properly configured, the Tomcat Manager can be accessed either through a web console at http:/{host}:{port}/manager/html, or through a variety of URI-based commands designed to expose its functionality for scripting.  

To reload an application from the web console, navigate to the "List Applications" tab.  From this page, you can choose an application from a list of all applications deployed on the server to reload.  To reload an application via a URI command, use the following format:


These commands work even if you have not declared your application context as "reloadable".  Note that to date (Tomcat 6.0.26), the Manager application cannot reload applications that are deployed as WAR files, only applications that were deployed as exploded directories.  

To reload a WAR-deployed application reflecting changes using Manager, you can undeploy the application and then re-deploy it.  The Tomcat Manager can also not be used to reload changes to the web.xml file.  To propagate these changes without restarting your entire server using Manager, simply stop and then start the application.  Alternatively, you can configure these files as WatchedResources, as shown below.

For obvious security reasons, the Tomcat Manager is disabled by default. Enabling it requires not one but several changes to Tomcat's configuration.  

For a complete guide to configuring and using the Tomcat Manager's reload functionality, as well as all its other features, visit our Getting The Most Out Of The Tomcat Manager article.

Hot reload via context settings

In detail-oriented stages of development, such as optimization, it is often necessary to make many small changes, some of which are merely tests of a variety of methods by which a single feature could be coded.  In this kind of environment, manually triggering every reload via the Manager application is not feasible or efficient enough.  

To address this issue, Tomcat includes a method called "backgroundProcess" as part of the Catalina component.  Normally, this process provides sessions expiration, but when properly configured, it can also monitor all of an application's classes for changes, and call for a reload if any of them change.

To configure reloading, add the "reloadable" attribute to your application's Context element, either in its Context fragment or in Server.xml:

<Context ... reloadable="true">

You can also configure the delay in seconds before the backgroundProcess is run on the container in the context element, via the backgroundProcessorDelay attribute, although this value can also be inherited from the Host or Engine.

Hot reload with WatchedResource

When you define a Context as "reloadable", Catalina's default behavior is to watch its classes, libraries, and web.xml configuration files for changes to trigger reload.  Sometimes you'll want to add other files to this list, such as logger configuration files.  In these situations, you can use the WatchedResource element nested inside the Context to specify additional files that Tomcat should watch.  Use the following syntax:


<Context ... reloadable="true">






Note that only one file may be contained in each pair of WatchedResource tags.  You can configure these settings either in the application's context.xml fragment, the server.xml file, or in Catalina's conf/context.xml file, if you would like to create global settings for all contexts.

Hot reload with Eclipse IDE

By configuring your Context to automatically reload when classes are altered and integrating Tomcat and Eclipse (or any other Java IDE) using the Web Tools Platform, you can add a hot reload functionality to your development environment.

Follow these simple configuration steps:

  • If you have not already integrated Tomcat with Eclipse, visit our illustrated step-by-step Guide to Tomcat Eclipse Integration, which will walk you through this process.
  • Follow the configuration steps provided in the previous section to enable hot reloading on your Tomcat server.
  • Configure your Eclipse workspace to point directly at your running Tomcat server's folder structure.  This may require some permissions configuration.
  • Directly edit your classes while your server is running, and watch Tomcat automatically reload your application as you save them.

Moving to production

Hot reloading is very useful for development, but you should make sure to disable all automatic reloading configurations prior to moving your application to production.  Here's some insight into why this is so important.

Reloading classes is complicated.  If only one reference is retained to the old class when the new class is created, the old class will not be properly disposed of, which is known as a Classloader leak.  This is one of the most commonly reported problems for any Java platform.

In addition to this consideration, the Servlet.init() method used by Tomcat to reload applications requires the entire application to be re-initialized, a multi-step process that becomes higher in overhead as application complexity increases.


Lastly, a failed automatic reload can result in lost state data, which is not acceptable in a production environment.

For these reasons, it is best to disable all automatic reloading when you move to production, and rely on the Tomcat Manager or an alternate administrative tool such as Tcat to manage applications.