misc - Tomcat 5.0 -> 5.5 Upgrade

Tomcat Upgrade Guide, v5.0 to v5.5

(Warning: this is still a work in progress!)

(Last update: 2005/01/11 - fleshed out logging section)

Intro

This is a basic guide on how to upgrade Tomcat from version 5.0 to version 5.5. (For instructions on setting up Tomcat 5 from scratch, refer to the Tomcat documentation.) It is based mostly on first-hand experience, but it also includes accounts reported on the tomcat-user mailing list.

If you've read my Tomcat v4 -> v5 guide, you'll note that the v5.0 -> v5.5 is less bumpy. (You may also notice I've lifted much of the boilerplate text from that doc.) That's due mostly to the fact that v4 and v5 implement different versions of the servlet spec. By comparison, v5.5 is more an internal reworking of Tomcat itself. That means you should have to make fewer code-level changes when upgrading from v5.0 to v5.5.

This document is not endorsed by the Apache Tomcat crew.

Please report errors to tomcat-upgrade-doc at BrandXDev dot net.

Legalities

This document was written in the hope that it would be useful, but is provided AS IS, WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Follow the steps in this document at your own risk.

Content Copyright © 2005 QM, BrandXDev Software.
Reproduction without express authorization is prohibited.

Before You Start

Should I Upgrade?

Only you can decide that. Tomcat 5.5 implements servlet spec 2.4, as does Tomcat 5.0. That means there are no spec-related benefits to upgrading. On the other hand, Tomcat 5.5 uses JDK 1.5. If you want to take advantage of the newer JDK 1.5 features (such as autoboxing and generics) then Tomcat 5.5 is the way to go.

As with any product upgrade, you do yourself a favor to approach this with a firm test plan and a realistic schedule.

Will It Be Difficult?

If you've maintained a clean, spec-compliant webapp, your upgrade may be as simple as "rebuild" and "adjust the config files."

Likely, the greatest challenge will be the change in logging configuration.

The Upgrade Process

  1. Rebuild your app

    Rebuild your app using JDK 1.5.x and the Tomcat 5.5 JARs. Tomcat 5.5 is based on JDK 1.5. There's a 1.4 compatability package, but I haven't tried it.

  2. Note changes in context.xml

    (Coming soon: changes in context.xml)

  3. Update your logging configuration

    This will likely be the toughest part of your upgrade.

    Tomcat's <Logger>s have been phased out in favor of commons-logging. (The <Logger>s were deprecated as of 5.0, but they're officially gone now in 5.5.) You'd do yourself to read up on log4j and commons-logging before you tackle this. In the meantime, your log output will go to catalina.out.

    Option 1: per-app logging.

    • put log4j.properties under WEB-INF/classes
    • put log4j.jar and commons-logging.jar under WEB-INF/common/lib

    The downside here is that the webapp controls where it logs its data, which is at odds with the "drop a WAR in and let the framework (container) take care of the rest" philosophy. For example, if you distribute a WAR file to other people, arguably it's unreasonable for you to determine where the log data goes.

    The upside is that each webapp (context) gets its own log file. (Well, this may or may not be an upside, depending on how you feel about merged logs.)

    Sample per-webapp log4j configuration: 

    log4j.rootLogger=WARN

log4j.appender.WEBAPP=org.apache.log4j.RollingFileAppender 
log4j.appender.WEBAPP.File=${catalina.base}/logs/tomcat-app.log 
log4j.appender.WEBAPP.layout=org.apache.log4j.PatternLayout 
log4j.appender.WEBAPP.layout.ConversionPattern=%d [%t] %-6p %c - %m%n 

log4j.logger.org.apache.catalina=INFO , WEBAPP
    (NOTE: This isn't perfect, as I'm still working out some bugs; but it should be enough to get you started.)

    Option 2: Appwide logging, controlled by the container. This is similar to the old <Logger> configuration, in which the app blindly called Servlet#log() and the container took care of dumping it out to a file.

    • drop log4j.jar and commons-logging.jar into ${tomcat.home}/common/lib
    • for the app start, pass 
      -Dlog4j.configuration=file:///path/to/log4j.properties
      to Tomcat's JVM (aka the $JAVA_OPTS environment variable).

    You don't have to hard-code the fully-qualified path in the URL; instead, just use "file://${CATALINA_BASE}/conf/log4j.properties"

    (Coming soon: an example log4j.properties for this configuration.)

    Option 3: Mix and match Options 1 and 2. Do you really want this? That could be confusing: "who generates that logfile, the container itself or the webapp?" You'd do yourself a favor to steer clear of this one.

    Finally, here are some links that may help get you started:

Corrections and More...

Please send corrections and/or document contributions to tomcat-upgrade-doc at BrandXDev dot net. There will certainly be corrections, as this document is still a work in progress.