Content

Table of Contents

General

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

Migrating from 10.1.x to 11.0.x

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

Java 17 required

Apache Tomcat 11.0.x requires Java 17 or later. Apache Tomcat 10.1.x required Java 11.

The SecurityManager has been deprecated in Java 17 onwards and support for running under a SecurityManager was removed in the Jakarta EE 11 specification projects. Therefore, support for configuring a SecurityManager has been removed in Tomcat 11.0.x.

Specification APIs

Apache Tomcat 11.0 supports the Jakarta Servlet 6.1, Jakarta Pages 4.0, Jakarta Expression Language 6.0, JakartaWebSocket 2.2, Jakarta Authentication 3.1 and Jakarta Annotations 3.0 specifications.

Servlet 6.1 API

The expected behaviour for adding and setting HTTP headers with null or the empty string has been clarified.

The meaning of "write operation" in the context of the Javadoc for ServletOutputStream.isReady() has been clarified.

ServletRequest.getParameter() and the other parameter methods are now documented to throw a runtime exception if the call triggers parsing of the parameters and an error is encountered during that parsing.

Support for HTTP/2 sever push is now optional and has been removed from Tomcat.

Clarify the behaviour of Cookie.setAttribute(String,String) and Cookie.getAttribute(String) with cookie attributes such as HttpOnly, Secure and Partitioned that do not have a value.

Pages 4.0

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

Expression Language 6.0

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

Support for running under a SecurityManager has been removed.

WebSocket 2.2

Support for running under a SecurityManager has been removed.

Authentication 3.1

Support for running under a SecurityManager has been removed.

Annotations 3.0

None.

Internal APIs

Whilst the Tomcat 11.0 internal API is broadly compatible with Tomcat 10.1 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.1.x has been removed.
  • Conversions from bytes to characters now throw an exception if the conversion fails.
  • Support for using the ^ character to separate the WAR file and WAR contents in Tomcat's custom WAR URL handler has been removed. The current default separator character of * remains unchanged.
  • Cookie parsing and handling now treats the quotes in a quoted cookie value as part of the value as required by RFC 6265.

Upgrading 11.0.x

When upgrading instances of Apache Tomcat from one version of Tomcat 11.0 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 11.0.

Tomcat 11.0.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 11.0.0-M5 onwards, the default value for the Connector attribute maxParameterCount has been reduced from 10,000 to 1,000.

Tomcat 11.0.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 11.0.0-M1 11.0.0-M3 -- conf/