BrandXDev.Net: misc - Tomcat 4 -> 5 Upgrade

misc - Tomcat 4 -> 5 Upgrade

Tomcat Upgrade Guide, v4 to v5

Intro

This is a basic guide on how to upgrade Tomcat from version 4 to version 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.

The goals of this document are few:

provide a resource to people who want to upgrade, and don't want to wait for responses from the list
reduce the number of "how do I upgrade" questions on the list

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 © 2004 QM, BrandXDev Software.
Reproduction without express authorization is prohibited.

Before You Start

Should I Upgrade?

Only you can decide that. Reading the Tomcat release notes, which list the new features and bug fixes, should help you make an informed decision. Well-known features include clustering support and implementation of the servlet 2.4/JSP 2.0 specs.

As with any product's major-release 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."

Please review the servlet spec (2.3, 2.4) and JSP spec (1.2, 2.0) for changes (especially deprecations). These documents are available in PDF from the Sun Java website.

Debunking The Myths

There are several myths surrounding the Tomcat 5 upgrade path. Before you begin, please note the following:

Tomcat 5 does not require Apache 2. If you were using Apache 1 with Tomcat 4, you should be able to use the same setup with Tomcat 5. Adding an unrelated, unneeded upgrade to the process will just compound your headache.
Tomcat 5 does not require JDK 1.5. In fact, there have been reports of failed builds based on JDK 1.5.
Tomcat 5 does not require JK2. Nor does Apache 2. It is entirely possible to use Apache 1 (or 2) + JK + Tomcat 5. JK2 is improving by the day, but it still appears to be a task for the adventurous, patient, and experienced.

The Upgrade Process

While still at Tomcat4...

Rebuild your app using JDK 1.4.x, if you're not already using it. The newer JDK is a Tomcat 5 requirement. Be sure to check for deprecated methods.
If your app uses packageless classes -- that is, you use bare ClassName and not some.package.ClassName -- you must package them. This is required by the servlet spec 2.4, and Tomcat enforces it.

Such a change will likely cause a ripple effect throughout your app, so be prepared for headaches.
Test this new build of your app. You don't want to mistake JDK migration issues for Tomcat 5 problems.

Building with Tomcat 5

As Tomcat 5 implements newer versions of the servlet and JSP specs, you must rebuild your app against the newer JAR files. Again, check for deprecations. Note the following:

In your build $CLASSPATH, replace any references to

{Tomcat4_install}/common/lib/servlet.jar

with

{Tomcat5_install}/common/lib/servlet-api.jar
{Tomcat5_install}/common/lib/jsp-api.jar
JSP spec 2.0 adds a rule that may conflict with your use of <jsp:useBean>: if the specified object is not found in the specified context, containers may throw an exception or attempt to create the object using the default (no-args) constructor.

If the object doesn't have a no-args constructor, problems will ensue. Tomcat will fail to compile the page, because it cannot instantiate the object. (Refer to Tomcat Bugzilla ID 26444)
There have been some changes to the servlet spec between 2.3 and 2.4; for example, SingleThreadModel has been deprecated. Review the spec to make sure you don't have to make any code-level changes.
The JavaMail JARs -- such as activation.jar and mail.jar -- are no longer included with Tomcat. Depending on your needs you can download them from Sun or simply copy them to from your old Tomcat install, into {Tomcat5_install}/common/lib.
Lastly, don't forget to copy any third-party JARs you had in {Tomcat4_install}/common/lib to {Tomcat5_install}/common/lib (e.g. database drivers).

Making the Switch

The serverwide web.xml and catalina.policy have changed. If you use the single Tomcat install (all of your webapps are under the Tomcat install directory), your webapp will pick this up automatically. If, instead, you use private Tomcat instances ($CATALINA_BASE vs $CATALINA_HOME), you must copy the new file to $CATALINA_BASE/conf.

The <Connector> element in server.xml has changed.

Tomcat 4:

  <Connector
    className="org.apache.catalina.connector.http.HttpConnector"
    port="{tomcat port}"
    minProcessors="2"
    maxProcessors="5"
    enableLookups="true"
    address="{tomcat IP}"
  />

Tomcat 5:

  <Connector
    protocol="HTTP/1.1"
    port="{tomcat port}"
    address="{tomcat IP}"
    enableLookups="false"
    maxThreads="150"
    minSpareThreads="25"
    maxSpareThreads="75"
    acceptCount="100"
    debug="0"
    connectionTimeout="-1"
    disableUploadTimeout="true"
  />

(The numbers are purely for display.)

Notice that the "className" attribute is not required. Specifying protocol="HTTP/1.1" indicates that the HTTP connector will be used.

If you forget to address this the container will provide plenty of "HttpConnector class not found" messages as a reminder.

It is encouraged that context-specific settings be placed in context.xml and not the serverwide server.xml. The Tomcat docs have the details, but in short: context.xml contains a raw <Context> element. It permits you to change per-webapp settings without disturbing the global server.xml file.
Tomcat 5 includes a newer, pickier XML parser (Xerces 2.6.0). If you suddenly encounter problems parsing XML, this is the place to look.

Corrections and More...

Please send corrections and/or document contributions to tomcat-upgrade-doc at BrandXDev dot net.