- \n
- Download Eclipse “JEE” Edition<\/li>\n
- Switch to the “Java EE” Perspective<\/li>\n
- Configure Your WAR Project<\/li>\n
- Create a New Server<\/li>\n
- Magic Setting: Disable “Auto Reloading” on Each Project in the Server<\/li>\n
- Performance Tip: Adjust Memory Settings<\/li>\n
- Start Your Tomcat Server in Debug Mode<\/li>\n<\/ol>\n<\/li>\n
- Why Disable Auto Reloading?<\/li>\n
- Disable Auto Reloading but Enable<\/em> Auto Publishing<\/li>\n
- Finding the tmp0<\/kbd> Fake Tomcat Directory<\/li>\n
- Exorcising the tmp0<\/kbd> Directory<\/li>\n
- Troubleshooting: What Do I Do If I Still Can’t Get It to Work?<\/li>\n<\/ul>\n
What Is “Hot Code Replace”?<\/h2>\n
“Hot Code Replace<\/a>” (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.<\/p>\n
Consider this ordinary application:<\/p>\n
<\/p>\npublic class Sample {\n public static void main(String[] args) {\n String foo = \"unchangeable\";\n foo += blah();\n System.out.println(foo);\n }\n \n public static String blah() {\n String bar = \"bar\";\n bar += \"blah\";\n return bar;\n }\n \n}<\/pre>\n<\/code><\/p>\n
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()<\/code>. Next, change the literalblah<\/code> toquz<\/code>. Save the file and the program will continue running with the new code.<\/p>\nYou can do this with Tomcat web applications in Eclipse, but it’s a lot trickier.<\/p>\n
<\/a>What’s the Catch?<\/h2>\n
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<\/code> method or any method invoked via reflection, that is, by using java.lang.reflect.Method.invoke()<\/kbd>.<\/p>\nHere’s what happens if you try to replace the
unchangeable<\/code> variable in the main method of Sample.java<\/kbd> above.<\/p>\n![\"unchangeable\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/unchangeable-300x115.png\")
<\/p>\nWhat About JavaRebel?<\/h2>\n
JavaRebel<\/a> is a hot code replacement system that’s a little better than JPDA HCR. (Maybe a lot better<\/a>.)<\/p>\n
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.<\/p>\n
Configuring Your Web Application in Eclipse<\/h2>\n
- \n
- Download Eclipse “JEE” edition\n
Most developers already use this, since it’s the first option available on the Eclipse download page<\/a>, 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!<\/p>\n
![\"download-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/download-screenshot-300x188.png\")
<\/p>\nNote: 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.<\/p>\n<\/li>\n
- Switch to the “Java EE” Perspective\n
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.<\/p>\n
![\"jee-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/jee-screenshot.png\")
<\/p>\n<\/li>\n- Configure Your WAR Project\n
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.<\/p>\n
Via Maven: Use Maven<\/a> to create a WAR project. For example:<\/p>\n
mvn archetype:create -DarchetypeArtifactId=maven-archetype-webapp -DartifactId=YOURNAMEHERE -DgroupId=YOURNAMEHERE<\/kbd><\/p>\n
Modify your pom.xml<\/kbd> to include an explicit reference to
maven-eclipse-plugin<\/code>, like this:<\/p>\n<\/p>\n\n<!-- ... -->\n<build>\n <!-- ... -->\n <plugins>\n <!-- ... -->\n <plugin>\n <artifactId>maven-eclipse-plugin<\/artifactId>\n <configuration>\n <wtpversion>2.0<\/wtpversion>\n <\/configuration>\n <\/plugin>\n <\/plugins>\n<\/build>\n<!-- ... -->\n<\/pre>\n
<\/code><\/p>\n
Now generate an Eclipse project from the command line, like this:<\/p>\n
mvn eclipse:eclipse<\/kbd><\/p>\n
Here’s an example Maven project<\/a> you can use. Just download it, extract it, and run
mvn eclipse:eclipse<\/code> to generate your Eclipse project. (If this is your first time using Maven with Eclipse, you’ll also need to add an M2_REPO<\/kbd> classpath variable in your Eclipse workspace preferences that points to your Maven repository, typically $HOME\/.m2\/repository<\/kbd> or %USERPROFILE%.m2repository<\/kbd>.)<\/p>\n<\/li>\n- Create a New Server\n
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<\/kbd>. Add your web project as a “resource” to this server.<\/p>\n<\/li>\n
- <\/a>Magic Setting: Disable “Auto Reloading” on Each Project in the Server\n
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.”)<\/p>\n
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.<\/p>\n
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.<\/p>\n
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!<\/p>\n
(It’s interesting to note that JavaRebel also requires disabling auto reloading<\/a> to work properly in Eclipse.)<\/p>\n
![\"magic-checkbox-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/magic-checkbox-screenshot-300x216.png\")
<\/p>\n<\/li>\n- <\/a>Performance Tip: Adjust Memory Settings\n
Before you start up your server, I strongly recommend adjusting your server’s -Xmx<\/kbd> memory settings; otherwise, it will constrain itself to the default value, 64 MB, which is just not enough!<\/p>\n
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<\/kbd> to the end of the existing arguments.<\/p>\n
![\"memory-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/memory-screenshot-300x273.png\")
<\/p>\n<\/li>\n- Start Your Tomcat Server in Debug Mode\n
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.<\/p>\n<\/li>\n<\/ol>\n
Why Disable Auto Reloading?<\/h2>\n
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<\/code> in your web.xml<\/kbd> file.<\/p>\nAs 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.<\/p>\n
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!)<\/p>\n
By disabling auto reloading and using JPDA hot code replace instead, you get a more reliable code replacement system.<\/p>\n
Disable Auto Reloading but Enable<\/em> Auto Publishing<\/a><\/h2>\n
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.<\/p>\n
![\"autopublish-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/autopublish-screenshot-300x205.png\")
<\/p>\nTo 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<\/kbd>, logs<\/kbd>, temp<\/kbd>, webapps<\/kbd> and work<\/kbd> 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<\/kbd> directory. Instead, Eclipse launches Tomcat with special command-line arguments, indicating where to find the fake Tomcat directory.<\/p>\n
“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.<\/p>\n
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.<\/p>\n
![\"server-menu-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/server-menu-screenshot-300x279.png\")
<\/p>\nFinding the tmp0<\/kbd> Fake Tomcat Directory<\/h2>\n
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<\/kbd>; for this reason I typically call it the tmp0<\/kbd> directory (pronounced “tempo”).<\/p>\n
The .metadata<\/kbd> 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<\/kbd>. It’s there somewhere!<\/p>\n
Inside, you can see all the folders Eclipse has created. Check out the generated server.xml<\/kbd> file in tmp0\/conf<\/kbd>. Examine generated .java<\/kbd> files in tmp0\/work<\/kbd>. Your tmp0\/webapps<\/kbd> directory is probably empty; Eclipse has probably generated your webapp in wtpwebapps<\/kbd>.<\/p>\n
Exorcising the tmp0<\/kbd> Directory<\/a><\/h2>\n
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<\/kbd> directory is messed up.<\/p>\n
- \n
- Try republishing your tmp0<\/kbd> directory. Open the “Servers” tab, right-click on your server and select “Clean…” (not<\/em> “Clean Tomcat Work Directory…”). Then select “Publish.” That should completely rebuild your tmp0<\/kbd> directory.<\/li>\n
- Try restarting Eclipse. This works more often than I’d like to admit.<\/li>\n
- Try completely deleting and recreating your server. Follow this ritual:\n
- \n
- Open the “Servers” tab, right-click on the server and select “Delete”.<\/li>\n
- Make sure “Delete unused server configuration(s)” is checked, then click OK.<\/li>\n
- 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.<\/li>\n
- Quit Eclipse.<\/li>\n
- Go find your tmp0<\/kbd> directory (if it’s still present) and delete it from your file system.<\/li>\n
- Launch Eclipse and recreate your server from scratch.<\/li>\n<\/ol>\n<\/li>\n
- Try creating a new workspace. File -> Switch Workspaces: specify an empty directory. Create your server from scratch.<\/li>\n<\/ul>\n
Troubleshooting: What Do I Do If I Still Can’t Get It to Work?<\/h2>\n
- \n
- <\/a>My project works in regular Tomcat, but doesn’t work in Tomcat under Eclipse\n
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<\/kbd> directory.<\/p>\n
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.<\/p>\n
On the other hand, if the exported WAR file does<\/em> work, then you know that the problem has to do with the way Eclipse is launching Tomcat. Find your tmp0<\/kbd> directory (described above) and poke around. Does everything look OK in there? Be sure to check your server.xml<\/kbd> file, as well as your webapp itself in wtpwebapps<\/kbd>. Make sure to note your WEB-INF\/lib<\/kbd> directory, typically in tmp0\/wtpwebapps\/YOURAPP\/WEB-INF\/lib<\/kbd>.<\/p>\n<\/li>\n
- Tomcat is throwing NoClassDefFoundError<\/kbd> or ClassNotFoundException<\/kbd>\n
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<\/a> above.<\/p>\n
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<\/a> below.<\/p>\n
If the exported WAR works but your webapp is still broken under Tomcat, you may need to perform an exorcism. (See Exorcising the tmp0<\/kbd> Directory<\/a> above.) If this happens to you often, double-check that you haven’t accidentally disabled auto publishing. (See Disable Auto Reloading but Enable<\/em> Auto Publishing<\/a> above.)<\/p>\n<\/li>\n
- <\/a>My exported WAR is missing JARs\n
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.<\/p>\n
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.<\/p>\n<\/li>\n
- My tmp0<\/kbd> directory is missing an important configuration file\n
Eclipse will publish files that it finds in the “Tomcat” folder of the “Servers” pseudo-project to your tmp0\/conf<\/kbd> directory; if you’re missing files, you can add them here.<\/p>\n<\/li>\n
- My server.xml<\/kbd> file is messed up\n
That file is copied from the “Tomcat” folder in your “Servers” pseudo-project to your tmp0\/conf<\/kbd> directory. But note that the server.xml<\/kbd> 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<\/kbd> file directly.<\/p>\n
Note that one of the most common problems with server.xml<\/kbd> is an incorrect
path<\/code> attribute on your webapp’s<Context><\/code> element, causing your webapp to appear on a non-standard URL. See the following question about 404 errors for more details about this problem.<\/p>\n<\/li>\n- Tomcat is giving me strange 404 errors\n
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<\/a>) If it happens in regular Tomcat too, then it’s probably a bug in your code.<\/p>\n
If the problem only happens in Eclipse, then it’s probably a server.xml<\/kbd> configuration problem. Check your tmp0\/conf\/server.xml<\/kbd> file’s
<Context><\/code> element; check thepath<\/code> attribute. Thepath<\/code> attribute indicates the virtual directory of your webapp. For example, if your Context\/path<\/kbd> is “examplePath”, then your webapp will appear at http:\/\/localhost:8080\/examplePath<\/kbd>. If it’s misconfigured, your webapp may not be available at the URL you expect.<\/p>\nThe path<\/kbd> 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 \/<\/kbd> as your context root (since you aren’t allowed to leave it blank).<\/p>\n
![\"context-root-screenshot\"](\"https:\/\/redfin.com\/blog\/devblog\/wp-content\/uploads\/sites\/3\/2009\/09\/context-root-screenshot-300x272.png\")
<\/p>\n<\/li>\n- Tomcat times out when starting under Eclipse (“Server […] was unable to start within 45 seconds”)\n
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!)<\/p>\n
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.<\/p>\n<\/li>\n
- I had Tomcat working under Eclipse, but now it’s broken and I can’t figure out why\n
You may need to perform an exorcism. (See Exorcising the tmp0<\/kbd> Directory<\/a> above.)<\/p>\n<\/li>\n
- My web project starts up fine, but when I save .java<\/kbd> files in Eclipse, it doesn’t take effect until I restart\n
- \n
- Did you make sure to launch the server in Debug mode, as opposed to Run mode? JPDA only works when you Debug the server.<\/li>\n
- Is your server configured to auto publish? (See Disable auto reloading but Enable<\/em> auto publishing<\/a> above.)<\/li>\n
- Did you change something that broke JPDA? (See What’s the catch?<\/a> 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.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
- My web project starts up fine, but when I save .jsp<\/kbd> files in Eclipse, it doesn’t take effect until I restart\n
This is typically due to disabled auto publishing. Double-check that your server is configured to auto publish. (See Disable auto reloading but Enable<\/em> auto publishing<\/a> above.)<\/p>\n
If that doesn’t work, examine your tmp0<\/kbd> 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<\/kbd> directory.<\/p>\n<\/li>\n
- Whenever I save a .java<\/kbd> file in Eclipse, Tomcat restarts\n
This is typically due to Tomcat auto reloading. Double-check that you correctly disabled auto reloading. (See Magic Setting<\/a> above.)<\/p>\n<\/li>\n
- Tomcat in Eclipse is much<\/i> slower than regular Tomcat\n
- Did you change something that broke JPDA? (See What’s the catch?<\/a> 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.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
- Tomcat is throwing NoClassDefFoundError<\/kbd> or ClassNotFoundException<\/kbd>\n
- Switch to the “Java EE” Perspective\n
- Finding the tmp0<\/kbd> Fake Tomcat Directory<\/li>\n