How to Set Up Hot Code Replacement with Tomcat and Eclipse

This blog post will guide you through setting up Tomcat hot code replacement (also called hotswap debugging) in Eclipse.

  • What Is “Hot Code Replace”?
  • What’s the Catch?
  • What About JavaRebel?
  • Configuring Your Web Application in Eclipse
    1. Download Eclipse “JEE” Edition
    2. Switch to the “Java EE” Perspective
    3. Configure Your WAR Project
    4. Create a New Server
    5. Magic Setting: Disable “Auto Reloading” on Each Project in the Server
    6. Performance Tip: Adjust Memory Settings
    7. Start Your Tomcat Server in Debug Mode
  • Why Disable Auto Reloading?
  • Disable Auto Reloading but Enable Auto Publishing
  • Finding the tmp0 Fake Tomcat Directory
  • Exorcising the tmp0 Directory
  • Troubleshooting: What Do I Do If I Still Can’t Get It to Work?

What Is “Hot Code Replace”?

Hot Code Replace” (HCR) lets you make modifications to a Java class and see the effect immediately in a running JVM, without restarting your application. HCR is part of the Java Platform Debugger Architecture (JPDA) and is available on all modern JVMs.

Consider this ordinary application:

public class Sample {
  public static void main(String[] args) {
    String foo = "unchangeable";
    foo += blah();
    System.out.println(foo);
  }
  
  public static String blah() {
    String bar = "bar";
    bar += "blah";
    return bar;
  }
  
}

If you debug this class in Eclipse, you can make changes to it, on the fly, without restarting the JVM. For example, try setting a breakpoint on the second line of blah(). Next, change the literal blah to quz. Save the file and the program will continue running with the new code.

You can do this with Tomcat web applications in Eclipse, but it’s a lot trickier.

What’s the Catch?

There are a few limitations when using hot code replace. You can’t use JPDA HCR to change the signature of a class (add/remove methods or fields) or to add new classes on the fly. Additionally, some method calls (“stack frames”) can’t be modified, including the main method or any method invoked via reflection, that is, by using java.lang.reflect.Method.invoke().

Here’s what happens if you try to replace the unchangeable variable in the main method of Sample.java above.

unchangeable

What About JavaRebel?

JavaRebel is a hot code replacement system that’s a little better than JPDA HCR. (Maybe a lot better.)

With JavaRebel you can add/remove methods and classes without restarting Tomcat. However, JavaRebel costs $149 per developer per year, so it may or may not be worthwhile for you.

Configuring Your Web Application in Eclipse

  1. Download Eclipse “JEE” edition

    Most developers already use this, since it’s the first option available on the Eclipse download page, but if you’re using “Eclipse IDE for Java Developers” (92MB), you’ll need to go back and download “Eclipse IDE for Jave EE Developers” (189MB). It’s worth it, I promise!

    download-screenshot

    Note: The difference between the regular Java IDE and the Java EE IDE is that the JEE edition comes with the Eclipse “Web Tools Project” (WTP), which includes “Web Server Tools” (WST). The terms are sometimes used interchangeably; keep an eye out for this if you need to search for them.

  2. Switch to the “Java EE” Perspective

    Make sure you’re in the “Java EE” perspective, not the “Java” perspective. If it’s not in the upper-right corner of your Eclipse window, you might need to enable it manually (Window menu -> Open Perspective -> Other…). If “Java EE” doesn’t appear on this list, you’ve probably downloaded the wrong package of Eclipse; go back and download the Java EE version.

    jee-screenshot

  3. Configure Your WAR Project

    From scratch: From the New menu, select “Dynamic Web Project”. Configure your source and output folders, as well as your “Content directory”, which will contain your JSPs, your WEB-INF directory, etc.

    Via Maven: Use Maven to create a WAR project. For example:

    mvn archetype:create -DarchetypeArtifactId=maven-archetype-webapp -DartifactId=YOURNAMEHERE -DgroupId=YOURNAMEHERE

    Modify your pom.xml to include an explicit reference to maven-eclipse-plugin, like this:

    <!-- ... -->
    <build>
        <!-- ... -->
        <plugins>
            <!-- ... -->
            <plugin>
                <artifactId>maven-eclipse-plugin</artifactId>
                <configuration>
                    <wtpversion>2.0</wtpversion>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <!-- ... -->
    

    Now generate an Eclipse project from the command line, like this:

    mvn eclipse:eclipse

    Here’s an example Maven project you can use. Just download it, extract it, and run mvn eclipse:eclipse to generate your Eclipse project. (If this is your first time using Maven with Eclipse, you’ll also need to add an M2_REPO classpath variable in your Eclipse workspace preferences that points to your Maven repository, typically $HOME/.m2/repository or %USERPROFILE%.m2repository.)

  4. Create a New Server

    From the New menu, select Other… -> Server -> Server. For your server type, expand the “Apache” folder and select the version of Tomcat you intend to use. Choose “Next” and then specify the path to your Tomcat installation directory, e.g. c:toolstomcat-6.0. Add your web project as a “resource” to this server.

  5. Magic Setting: Disable “Auto Reloading” on Each Project in the Server

    You now have a weird pseudo-project called “Servers” in your Project Explorer. In the explorer, your server looks like a folder called something like “Tomcat v6.0 Server at localhost-config” …but that’s not what you want. You need to interact with your server using the “Servers” tab. (Eclipse calls these tabs “Views,” but everybody else just calls them “tabs.”)

    The “Servers” tab should be exposed by default, but in case it isn’t, you can expose it via Window -> Show View -> Servers. From there you can double-click on your server to configure it.

    Note that the configuration panel for your server has two tabs, “Overview” and “Modules”, down at the bottom of the window. Click on the “Modules” tab to bring up the list of projects associated with the server.

    Select your project in the list and click on “Edit”. You’ll see the magic secret checkbox: “Auto reloading enabled”. It’s checked by default. For the love of Pete, uncheck it!

    (It’s interesting to note that JavaRebel also requires disabling auto reloading to work properly in Eclipse.)

    magic-checkbox-screenshot

  6. Performance Tip: Adjust Memory Settings

    Before you start up your server, I strongly recommend adjusting your server’s -Xmx memory settings; otherwise, it will constrain itself to the default value, 64 MB, which is just not enough!

    Double-click on your server in the “Servers” tab and switch to the “Overview” tab. Click on the “Open launch configuration” link. Switch to the Arguments tab; there you can add relevant memory settings to the “VM Arguments” section. For example, you might add -Xmx512m to the end of the existing arguments.

    memory-screenshot

  7. Start Your Tomcat Server in Debug Mode

    Now you can right-click on the Server in your Servers tab and choose “Debug”. Changes you make to your JSPs or Java classes will be instantly hotswapped into your running WAR.

Why Disable Auto Reloading?

Auto reloading is a feature of Tomcat that allows you to replace Java classes at runtime without using JPDA. In this mode, Tomcat uses Java classloaders to try to unload classes and reload them; whenever it reloads, it also tries to reinitialize your application, re-launching any servlets that are marked load-on-startup in your web.xml file.

As a result, Tomcat auto reloading may not save you any time at all if your webapp has a lot of startup code. For example, if your load-on-startup code needs to warm up Hibernate database caches, Spring/Guice dependency injection configuration, etc., it may take almost as long to restart your webapp as it does to restart Tomcat.

Worse, an app that has been auto reloaded can behave strangely, and can quickly run out of PermGen memory due to frequent unloading/reloading of classes. When this happens, restarting Tomcat typically fixes the problem. If you spend even five minutes investigating a weird auto reloading problem, you’ve just wasted all the time you were hoping to save by avoiding a restart. (Not to mention your stress and frustration!)

By disabling auto reloading and using JPDA hot code replace instead, you get a more reliable code replacement system.

Disable Auto Reloading but Enable Auto Publishing

In the screenshot above you can see how to disable auto reloading on the “Modules” tab of the Tomcat server; auto reloading is bad for JPDA debugging. But there’s another setting called “Automatically publish when resources change” on the “Overview” tab of the Tomcat server. It’s hidden by default, collapsed under the “Publishing” section. You can see it if you expand that section; you want to make sure auto publishing is enabled while auto reloading is disabled.

autopublish-screenshot

To understand the difference between auto publishing and auto reloading, we’ll have to go into how exactly Eclipse WTP works. When you create a “Server” in Eclipse, the IDE creates a fake Tomcat directory, complete with the conf, logs, temp, webapps and work directories. When you configured the server, you told Eclipse where to find Tomcat, but it doesn’t use any of your settings files or any data from your webapps directory. Instead, Eclipse launches Tomcat with special command-line arguments, indicating where to find the fake Tomcat directory.

“Publishing” means to populate the fake Tomcat directory with all of your code. It copies your JSPs, JARs up your Java, regenerates settings files, etc.

If you turn off auto publishing, then you have to right-click on your Server and “Publish” your changes manually every time you save your Java code. Additionally, auto publishing allows Tomcat to reload JSPs automatically, regardless of whether you use JPDA or not.

server-menu-screenshot

Finding the tmp0 Fake Tomcat Directory

Sometimes it can be helpful to look inside the fake Tomcat directory and see what’s going on in there. Eclipse tells you where it put the Tomcat directory in the “Server Locations” section of your “Tomcat” server configuration panel. (Double-click on your Server in the “Servers” tab to open the configuration panel.) Typically, Eclipse says that your server is in .metadata/.plugins/org.eclipse.wst.server.core/tmp0; for this reason I typically call it the tmp0 directory (pronounced “tempo”).

The .metadata folder is inside your Eclipse workspace directory. (You can find your Eclipse workspace directory by going to File -> Switch Workspace; the default value is your current workspace directory.) In the worst case, you can always just search your hard drive for tmp0. It’s there somewhere!

Inside, you can see all the folders Eclipse has created. Check out the generated server.xml file in tmp0/conf. Examine generated .java files in tmp0/work. Your tmp0/webapps directory is probably empty; Eclipse has probably generated your webapp in wtpwebapps.

Exorcising the tmp0 Directory

Unfortunately, sometimes Eclipse gets a little confused about what to put in your WAR file, and you need to perform various stages of exorcism depending on how badly your tmp0 directory is messed up.

  • Try republishing your tmp0 directory. Open the “Servers” tab, right-click on your server and select “Clean…” (not “Clean Tomcat Work Directory…”). Then select “Publish.” That should completely rebuild your tmp0 directory.
  • Try restarting Eclipse. This works more often than I’d like to admit.
  • Try completely deleting and recreating your server. Follow this ritual:
    1. Open the “Servers” tab, right-click on the server and select “Delete”.
    2. Make sure “Delete unused server configuration(s)” is checked, then click OK.
    3. Look at your “Servers” pseudo-project; make sure the folder for your server is gone. If it isn’t, right-click on it and Delete it.
    4. Quit Eclipse.
    5. Go find your tmp0 directory (if it’s still present) and delete it from your file system.
    6. Launch Eclipse and recreate your server from scratch.
  • Try creating a new workspace. File -> Switch Workspaces: specify an empty directory. Create your server from scratch.

Troubleshooting: What Do I Do If I Still Can’t Get It to Work?

  • My project works in regular Tomcat, but doesn’t work in Tomcat under Eclipse

    Try using Eclipse to generate a WAR file for Tomcat. Right-click on your web project and select Export -> WAR file, and install it in Tomcat by dropping the exported WAR into your Tomcat webapps directory.

    If the exported WAR file doesn’t work, then you now have two WARs: one working WAR generated by your build script, and one non-working WAR generated by Eclipse. WAR files are just zips; extract them both, find the difference, and fix it! Right-click on your web project and select “Properties”. The problem is somewhere in here.

    On the other hand, if the exported WAR file does work, then you know that the problem has to do with the way Eclipse is launching Tomcat. Find your tmp0 directory (described above) and poke around. Does everything look OK in there? Be sure to check your server.xml file, as well as your webapp itself in wtpwebapps. Make sure to note your WEB-INF/lib directory, typically in tmp0/wtpwebapps/YOURAPP/WEB-INF/lib.

  • Tomcat is throwing NoClassDefFoundError or ClassNotFoundException

    First, double-check whether this problem happens in regular Tomcat. See My project works in regular Tomcat, but doesn’t work in Tomcat under Eclipse above.

    If this problem occurs in the exported WAR file under regular Tomcat, then your webapp is probably missing JARs. See My exported WAR is missing JARs below.

    If the exported WAR works but your webapp is still broken under Tomcat, you may need to perform an exorcism. (See Exorcising the tmp0 Directory above.) If this happens to you often, double-check that you haven’t accidentally disabled auto publishing. (See Disable Auto Reloading but Enable Auto Publishing above.)

  • My exported WAR is missing JARs

    Right-click on your web project and select “Properties.” The problem is somewhere in here. Make sure you see your JAR listed under “Java Build Path” in the Properties dialog.

    Beware: not every JAR in “Java Build Path” gets exported to the WAR. The list of JARs for the WAR is under “Java EE Module Dependencies.” If a JAR/project is unchecked on that list, it won’t appear in your WAR file.

  • My tmp0 directory is missing an important configuration file

    Eclipse will publish files that it finds in the “Tomcat” folder of the “Servers” pseudo-project to your tmp0/conf directory; if you’re missing files, you can add them here.

  • My server.xml file is messed up

    That file is copied from the “Tomcat” folder in your “Servers” pseudo-project to your tmp0/conf directory. But note that the server.xml file is at least partially autogenerated by Eclipse. If you make direct changes to the file, Eclipse will do its best to try to incorporate your changes, but it often gets confused and does the wrong thing. When possible, it’s better to find the appropriate Eclipse settings and change them there instead of modifying the server.xml file directly.

    Note that one of the most common problems with server.xml is an incorrect path attribute on your webapp’s <Context> element, causing your webapp to appear on a non-standard URL. See the following question about 404 errors for more details about this problem.

  • Tomcat is giving me strange 404 errors

    First, double-check whether this problem happens in regular Tomcat. (See My project works in regular Tomcat, but doesn’t work in Tomcat under Eclipse) If it happens in regular Tomcat too, then it’s probably a bug in your code.

    If the problem only happens in Eclipse, then it’s probably a server.xml configuration problem. Check your tmp0/conf/server.xml file’s <Context> element; check the path attribute. The path attribute indicates the virtual directory of your webapp. For example, if your Context/path is “examplePath”, then your webapp will appear at http://localhost:8080/examplePath. If it’s misconfigured, your webapp may not be available at the URL you expect.

    The path attribute is auto-generated based on settings in the properties of your WAR project. Right-click on your web project, select “Properties” and go to the “Web Project Settings” section. There’s only one setting here; it’s called “Context root”. Specify the context you intend to use here. If you want your project to appear in the root directory, you’ll need to put / as your context root (since you aren’t allowed to leave it blank).

    context-root-screenshot

  • Tomcat times out when starting under Eclipse (“Server [...] was unable to start within 45 seconds”)

    The Eclipse developers, in their infinite wisdom, have added a timeout to Tomcat startup. If Tomcat doesn’t declare a successful startup in 45 seconds, it kills Tomcat automatically. (Gee, thanks, guys!)

    You can increase that timeout. Open the “Servers” tab and double-clicking on your server to open the server configuration panel. Make sure the panel’s “Overview” tab is selected. Expand the “Timeouts” section and increase the Start timeout to something reasonable for your server.

  • I had Tomcat working under Eclipse, but now it’s broken and I can’t figure out why

    You may need to perform an exorcism. (See Exorcising the tmp0 Directory above.)

  • My web project starts up fine, but when I save .java files in Eclipse, it doesn’t take effect until I restart
    • Did you make sure to launch the server in Debug mode, as opposed to Run mode? JPDA only works when you Debug the server.
    • Is your server configured to auto publish? (See Disable auto reloading but Enable auto publishing above.)
    • Did you change something that broke JPDA? (See What’s the catch? above.) If you make large changes to your classes, JPDA may be unable to replace the code; if you choose to “Continue” past that point, further changes will have no effect.
  • My web project starts up fine, but when I save .jsp files in Eclipse, it doesn’t take effect until I restart

    This is typically due to disabled auto publishing. Double-check that your server is configured to auto publish. (See Disable auto reloading but Enable auto publishing above.)

    If that doesn’t work, examine your tmp0 directory to make sure Tomcat is using the correct JSP. It should automatically begin consuming new JSPs as they are installed in the tmp0/wtpwebapps directory.

  • Whenever I save a .java file in Eclipse, Tomcat restarts

    This is typically due to Tomcat auto reloading. Double-check that you correctly disabled auto reloading. (See Magic Setting above.)

  • Tomcat in Eclipse is much slower than regular Tomcat

    Try increasing your memory settings as described above, if you haven’t already.

    Try running Tomcat in “Run” mode (as opposed to “Debug”) mode. If that fixes the problem, then there may be nothing you can do about it. JPDA does have some overhead; you can turn it off, but while you’ve turned it off you won’t have access to hot code replacement.

Discussion

  • Jevgeni Kabanov

    Great article! Could I suggest to link to this page when talking about JRebel as compared to HotSwap?:
    http://www.zeroturnaround.com/jrebel/comparison/

  • Margotk

    Fantastic – thank you!

  • Andrew

    Excellent walk through. You not only explained the problem and the solution, but you explained why the solution works (and when it doesn’t). Very helpful.

    Thanks!

  • http://joshdick.net Josh

    Thanks for this information…it has eliminated a LOT of my frustration with Eclipse!

  • Shane

    You deserve an award. Seriously. Thank you thank you thank you.

  • Lex

    Wow…. Thank you so much. I usually don’t post on forum, but I have to say thanks. I was able to resolve the issue on compiling Java files and have to restart Tomcat Server thanks to your instruction.–This has been a frustration of mine for several months.

  • Gopalallam

    A wonderful article! The author has very deep knowledge of Tomcat, Eclipse and WTP. It saves me days of research.
    Thanks a bundle!!!!!

  • Chad

    A great article! This answered one big question (why hot-swap in eclipse was not working). Then the article went on to clear up a bunch of other items that I wondered about in the past. Thanks for taking the time to share.

  • ManiKanta

    Really an excellent & insightful article… waiting from the dawn for this feature…. thanks a lot…. :)

    ManiKanta

  • Jactive

    thanks for your share

  • Strzel_a

    Thanks for the tips !!!

  • Wopazar

    Awesome thanks a bunch man!

  • Ladislav Gatial

    Great article. I use also the DCEVM to make it even better. (see http://ssw.jku.at/dcevm/)

  • Stefan Tzeggai

    Great!

  • http://muzso.hu/ müzso

    Thanks for sharing. Very informative.

  • David

    THANKS!

  • GODzillaSDM

    Hi, I am trying to get Hot Swap to work.  I need to turn off Auto-Reload, but my project is not listed in the  Tomcat Configuration, Web Modules with the “magic” checkbox.  Is there a way to change this via an XML file?  Where?

    Thanks!

  • Roman Churin

    Hello!

    We do a promotion of iPhone/iPad applications and we want to offer you our services. We are a young but a very useful company that is why our prices are extremely low and our clients are more than satisfied by the results

    If you want your application to be known by as many people as possible we are what you need. What do we offer?

    1) A request to make a review of your app on 587 iPhone/iPad sites all over the world (includin sites in English and forums in Russian)
    2) A request to review you app on 144 sites in English
    3) A request to make a review of the app on 89 sites in Russian + 17 forums (also in Russian)
    4) A NEW SERVICE! Sending a request to make a video review of your app to 49 popular youtube video reviewers only for 29$

    You can also avoid filling boring forms on our site, you can just e-mail us and say what you want to order, give us a link to your application, pay for the order and we will find all the necessary information ourselves
    An additional service which is not offered to everyone: download+ 5 stars + positive comment on Appstore (US aacounts). If you want to know about the price, e-mail to promoarrow@gmail.com

    You can also order a free test of our service. We will send a request to review your app to 15 sites, so you can see how we work.
    You can visit our site promoarrow.com
    If you have any questions, we are always ready to answer you! E-mail us to support@promoarrow.com

    Sincerely,
    Roman
    Promoarrow.com team

  • Pingback: Spring-mvc + Velocity + DCEVM « Rafael Sanches

  • Manishgupta005

    Thanks !! But it only works in small maven projects

  • Manishgupta005

    As i said on big project changes is not reflecting in java files.
    I am using tomcat 6.0, maven, m2eclipse plugin, strust2.0 conventional pattern, domain object generated by xsd 2.0.

    Is there any limitation of hot deployment.

  • Joe

    An excellent article, thanks! Have used it several times to explain juniors how things operate

  • Pingback: Import a maven web project in eclipse for tomcat « Coding « laurii

  • Dattaprasad

    First great article read on tomcat deployment .. Hats off …