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 9.0.x to 10.0.x

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

Java 8 required

Apache Tomcat 10.0.x requires Java 8 or later. This is unchanged from Tomcat 9.0.x.

Specification APIs

Apache Tomcat 10 supports the Jakarta Servlet 5.0, Jakarta Pages 3.0, Jakarta Expression Language 4.0, JakartaWebSocket 2.0 and Jakarta Authentication 2.0 specifications.

There is a significant breaking change between Tomcat 9.0.x and Tomcat 10.0.x. The Java package used by the specification APIs has changed from javax... to jakarta.... It will be necessary to recompile web applications against the new APIs.

Tomcat can convert an existing web application from Java EE 8 to Jakarta EE 9 at deployment time using the Apache Tomcat migration tool for Jakarta EE. To make use of the feature, the web application should be placed in the Host legacyAppBase folder (by default named webapps-javaee) and they will be converted to an equivalent Jakarta EE web application in the Host appBase folder (by default named webapps).

Alternately, the Apache Tomcat migration tool for Jakarta EE or any similar conversion tool can be used ahead of time to benefit from faster deployment time and more precise conversion configuration options.

Servlet 5.0 API

The Java package has changed from javax.servlet to jakarta.servlet.

Pages 3.0

The Java package has changed from javax.servlet.jsp to jakarta.servlet.jsp.

Expression Language 4.0

The Java package has changed from javax.el to jakarta.el.

WebSocket 2.0

The Java package has changed from javax.websocket to jakarta.websocket.

Authentication 2.0

The Java package has changed from javax.security.auth.message to jakarta.security.auth.message.

Internal APIs

Whilst the Tomcat 10 internal API is broadly compatible with Tomcat 9 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:

  • GenericPrincipal.getPassword() has been removed.

web.xml defaults

conf/web.xml sets the default request and response character encoding to UTF-8.

Session management

Session persistence on restart has been disabled by default. It may be re-enabled globally in conf/context.xml or per web application.

HTTP/2

The configuration settings that were duplicated between the HTTP/1.1 and HTTP/2 connectors have been removed from the HTTP/2 connector which will now inherit them from the associated HTTP/1.1 connector.

Logging

The logging implementation now only creates log files once there is something to write to the log files.

Access Log Patterns

To align with httpd, the %D pattern now logs request time in microseconds rather than milliseconds. To log request time in milliseconds, use %{ms}T.

Upgrading 10.0.x

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

Tomcat 10.0.x noteable changes

The Tomcat developers aim for each 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.0.3 onwards, the semantics of the HostConfig.check(String) method have changed. Rather than marking the application as serviced before calling the method, the method will mark the application as serviced before checking resources and then un-mark the application as being serviced after the checks are complete. If the application is marked as serviced when the method is called, the method will be a NO-OP.

  • In 10.0.9 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.

  • In 10.0.11 onwards, as a result of the updated fork of Commons FileUpload now using java.nio.file.Files, applications using multi-part uploads need to ensure that the JVM is configured with sufficient direct memory to store all in progress multi-part uploads.

  • In 10.0.14 onwards, the system property org.apache.juli.AsyncLoggerPollInterval is no longer used.

Tomcat 10.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 10.0.0 10.0.12 -- conf/