Phil Zoio's Weblog, March 24, 2005

Tomcat's Startup Woes

One thing I've never been able to understand is why Tomcat has never created a decent startup mechanism. Apart from being the reference implementation for the Java Servlet and JSP specifications, its used on thousands of production systems. But it also has another significant and rather unique role in the Java world: just about every application framework, Java web app-based product or tutorial will use Tomcat as the example. That means that every Java web developer at some stage or other will need to run Tomcat, even if they never use or even plan to use it as a development or production server.

All this makes it a shame that Tomcat has such a nasty startup script. There seems to be an awful lot more happening in Tomcat's startup scripts (you'll find in the bin directory) than other application servers and Servlet engines. I got caught out by it again yesterday when trying to set up Tomcat 4.1.31 in debug mode. Here's what you need to do (on Windows):

1. make a copy of startup.bat and call it debug.bat
2. in debug.bat change
   set CMD_LINE_ARGS=
to
   set CMD_LINE_ARGS=jpda start
3. before
   call "%EXECUTABLE%" %CMD_LINE_ARGS%
   add
   set JPDA_ADDRESS=8000
set JPDA_TRANSPORT=dt_socket

That should be it. The problem is, if there is a problem starting the JVM, all you get to see is a Window opening for a split second, then disappearing. There were no logs - the Tomcat logging functionality only starts if the JVM actually starts. You don't even get any console output, because the just windows disappear. That's when you have to start mucking around with the Tomcat scripts to get them to print some usable diagnostic information, something you just shouldn't have to do. Going fast forward a little while, I eventually discovered that the JVM was failing to start with the following message:

Transport dt_socket failed to initialize, rc = 509

I managed to resolve the problem by changing the PATH environment variable to start with [java_1.4.2_home]/jre/bin, rather than [java_1.5.0_home]/jre/bin. Why exactly this should have been the cause of the problem will probably remain a mystery. I'm more concerned about what I needed to do to diagnose the problem:

• create a "debug" version of the catalina.bat file,
• add echo on to the top of the file, then
• change all the commands which launch new processes using start [processname] by removing the start command, which opens the new window

The result is ugly, but at least I could then see the arguments for the Java command being used to launch Tomcat, and piece together enough information to figure out how the catalina.bat script is being run.

One better answer is to user a platform neutral Java process to handle the Tomcat launch process. The bootstrap Java launch should be simpler to configure, should produce debugging information, and be platform neutral. Apparently, there is an Apache Jakarta Commons Launcher designed to do exactly this, whose "original classes came the Jakarta Tomcat 4.0 project". Unfortunately, there's no evidence of this mechanism being used in the Tomcat product itself (I base this comment on what's in the bin directory of the installation - both of the 4.1.31 and 5.5.4 versions - as well as the documentation on the Tomcat web site).

Perhaps, rather than whinging, I'll request an enhancement or even put in a fix myself. In the meantime, it will just remain something to watch out for.