Content

Table of Contents

General

Please read general Migration Guide page first, for common considerations that apply to migration or upgrade between versions of Apache Tomcat.

Migrating from 10.0.x to 10.1.x

This section lists all the known changes between 10.0.x and 10.1.x which may cause backwards compatibility problems when upgrading.

Java 11 required

Apache Tomcat 10.1.x requires Java 11 or later. This is a change from Apache Tomcat 10.0.x and 9.0.x which require Java 8 or later.

Specification APIs

Apache Tomcat 10.1 supports the Jakarta Servlet 6.0, Jakarta Server Pages 3.1, Jakarta Expression Language 5.0, JakartaWebSocket 2.1 and Jakarta Authentication 3.0 specifications.

Servlet 6.0 API

All methods and classes marked as deprecated in the 5.0 API have been removed.

Support for Cookie specifications other than RFC 6265 has been removed and a number of methods deprecated as a result.

A new method, Cookie.setAttribute(String name, String value) has been added.

The process for decoding and normalizing URIs has been clarified.

New methods and classes have been added to provide access to unique identifiers for the current request and/or associated connection.

Server Pages 3.1

Added an option to raise a PropertyNotFoundException when an EL expression contains an unknown identifier.

Expression Language 5.0

The EL API now uses generics where appropriate.

The deprecated MethodExpression.isParmetersProvided() method has been removed from the API.

WebSocket 2.1

The packaging of the API JARs has changed to remove duplicate classes. The server API now has a dependency on the client API JAR.

Authentication TBD

No changes.

Internal APIs

Whilst the Tomcat 10.1 internal API is broadly compatible with Tomcat 10.0 there have been many changes at the detail level and they are not binary compatible. Developers of custom components that interact with Tomcat's internals should review the JavaDoc for the relevant API.

Of particular note are:

  • All code marked as deprecated in 10.0.x has been removed.
  • A number of configuration options have been removed from the JreMemoryLeakPreventionListener as the leaks no longer exist in Java 11 onwards.

Upgrading 10.1.x

When upgrading instances of Apache Tomcat from one version of Tomcat 10.1 to another, particularly when using separate locations for $CATALINA_HOME and $CATALINA_BASE, it is necessary to ensure that any changes in the configuration files such as new attributes and changes to defaults are applied as part of the upgrade. To assist with the identification of these changes, the form below may be used to view the differences between the configuration files in different versions of Tomcat 10.1.

Tomcat 10.1.x noteable changes

The Tomcat developers aim for each stable patch release to be fully backwards compatible with the previous release. Occasionally, it is necessary to break backwards compatibility in order to fix a bug. In most cases, these changes will go unnoticed. This section lists changes that are not fully backwards compatible and might cause breakage when upgrading.

  • In 10.1.0-M3 onwards, Tomcat no longer adds an "Expires" HTTP response header when adding "Cache-Control: private" due to a CONFIDENTIAL transport-guarantee. This will likely cause a change in caching behavior for applications that do not explicitly set their own headers but rely on Tomcat's previous behavior. If you wish to disable caching, you will need to configure it explicitly in your application. See BZ 65513 for more information.

Tomcat 10.1.x configuration file differences

Select a configuration file, old version and new version from the boxes below and then click "View differences" to see the differences. The differences will be shown in a new tab/window.

Note: If there are no differences you will see an error page.

You can also use a Git command similar to the following from within a working copy:

git diff 10.1.0-M1 10.1.0-M2 -- conf/