What Do We Know About Tomcat 9.0

Apache Tomcat is a very popular and preferred industry choice for web application development as a Servlet/JSP container. Apache Tomcat version 9.0 implements the Servlet 4.0 and Java Server Pages 2.3 specifications from the Java Community Process and includes many additional features that make it a useful platform for developing and deploying web applications and web services.

I take this opportunity to summarize some of the new features in Tomcat 9.0 and steps to keep in mind before upgrading from Tomcat 8.x to Tomcat 9.0.

Migrating From Tomcat 8.0.x or 8.5.x to Tomcat 9.0

The decision to migrate to a new platform is never an easy decision but we all make it, keeping in mind the benefits of using current software release and also better support within the support community. Upgrading to Tomcat 9.0 from Tomcat 8.0.x or 8.5.x also comes with some known backward compatibility issues which we should be all aware of:

• Java 8 is required: Apache Tomcat 9.0.x requires Java 8 or later. Apache Tomcat 8.0.x and 8.5.x required Java 7.
• Specification APIs: Apache Tomcat 9 supports the Java Servlet 4.0, Java Server Pages 2.3, Java Unified Expression Language 3.0, and Java API for WebSocket 1.0 specifications. The changes between versions of specifications may be found in the Changes appendix in each of specification documents.
• Servlet 4.0 APIs: In JSP, pages that use wildcard import syntax the new classes added in Servlet API may conflict with ones in web applications. For example, if package "a" contains class PushBuilder, the following JSP page will cease to compile in Tomcat 9:

xxxxxxxxxx

<%@page import="a.*"%>

<% PushBuilder pushBuilder = new PushBuilder(); %>

This happens because the implicit import of javax.servlet.http.* and the explicit import of a.* will provide conflicting definitions of class PushBuilder that was added in Servlet 4.0. The solution is to use the explicit import,

x

<%@page import="a.PushBuilder"%>

<% PushBuilder pushBuilder = new PushBuilder(); %>

• JavaServer Pages 2.4: It is anticipated that Java EE 8 will include a maintenance release of JSP with a version of 2.4.
• Expression Language 3.1: It is anticipated that Java EE 8 will include a maintenance release of expression language with a version of 3.1.
  
  WebSocket 2.0: It is anticipated that Java EE 8 will include an updated Java API for WebSocket specification with a version of 2.0.
• BIO connector removed: The following change is present in 8.5.0 onwards. The Java blocking IO implementation (BIO) for both HTTP and AJP has been removed. Users are recommended to switch to the Java non-blocking IO implementation (NIO). This change is present starting Tomcat 8.5.0 version.
  
  Comet support removed: Comet support has been removed without a direct replacement. Applications using Comet are recommended to migrate to WebSockets. This change is present starting Tomcat 8.5.0 version.
• HTTP/2 support added: HTTP/2 is supported for h2 (over TLS, negotiated via ALPN) and h2c (clear text, negotiated via HTTP/1.1 upgrade). HTTP/2 needs to be explicitly enabled for a connector. To enable it, insert:

<UpgradeProtocol className="org.apache.coyote.http2.Http2Protocol" />

inside the connector for which you wish to enable HTTP/2. Note that to enable HTTP/2 for a secure NIO or NIO2 connector, those connectors must be using the OpenSSL engine for TLS. This change is present starting with Tomcat 8.5.0 version.

TLS Virtual Hosting and Multiple Certificate Support Added

Tomcat 9 supports multiple TLS virtual hosts for a single connector with each virtual host able to support multiple certificates. Virtual host definitions are nested inside the Connector element with the default specified using the defaultSSLHostConfigName attribute on the Connector if more than one virtual host is specified. Certificate definitions are nested inside the virtual host.

The following example shows how to use this to configure a single APR/native connector for multiple TLS virtual hosts with each host having both an RSA and EC certificate.

x

<Connector port="8443"

            protocol="org.apache.coyote.http11.Http11AprProtocol"

            maxThreads="150"

            SSLEnabled="true"

            defaultSSLHostConfigName="openoffice.apache.org" >

    <SSLHostConfig hostName="openoffice.apache.org" >

        <Certificate certificateKeyFile="conf/openoffice.apache.org-rsa-key.pem"

            certificateFile="conf/openoffice.apache.org-rsa-cert.pem"

                type="RSA" ></Certificate>

        <Certificate certificateKeyFile="conf/openoffice.apache.org-ec-key.pem"

            certificateFile="conf/openoffice.apache.org-ec-cert.pem"

                type="EC" ></Certificate>

    </SSLHostConfig>

    <SSLHostConfig hostName="www.openoffice.org" >

        <Certificate certificateKeyFile="conf/www.openoffice.org-rsa-key.pem"

                certificateFile="conf/www.openoffice.org-rsa-cert.pem"

                type="RSA" ></Certificate>

        <Certificate certificateKeyFile="conf/www.openoffice.org-ec-key.pem"

                certificateFile="conf/www.openoffice.org-ec-cert.pem"

                type="EC" ></Certificate>

    </SSLHostConfig>

</Connector>

Internal APIs

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

• Significant refactoring has taken place throughout the connectors to reduce duplicate code and to align behavior across implementations. (This change is present in 8.5.x.)
• The deprecated digest attribute has been removed from the Realm. (This change is present in 8.5.x.)

JSR-77 Implementation Removed

The JSR-77 implementation is incomplete and has been removed in 8.5.x and 9.0.x. Specifically, the following methods that exposed to JMX have been removed.

xxxxxxxxxx

StandardContext.getServlets()

StandardContext.isStateManageable()

StandardContext.getDeploymentDescriptor()

StandardWrapper.isStateManageable()

Clustering

 MessageDispatch15Interceptor had been used to add the Java 5 features to  MessageDispatchInterceptor.  MessageDispatch15Interceptor  has been removed in Tomcat 8.5.x and 9.0.x by merging the Java 5 features to MessageDispatchInterceptor. This change is present starting Tomcat 8.5.0 version.

InstanceListener Removed

The support of  InstanceListener  has been removed in 8.5.x and 9.0.x. Specifically, the following classes have been removed.

xxxxxxxxxx

org.apache.catalina.InstanceListener

org.apache.catalina.InstanceEvent

org.apache.catalina.util.InstanceSupport

SessionManager

The following session manager attributes have been completely removed in 8.5.x and 9.0.x.

•  distributable  
•  maxInactiveInterval 
•  sessionIdLength 

The replacements are as follows:

• The  distributable attribute has been deprecated in 8.0 and specified value is ignored. This should be configured via the Context. The value is inherited based on the presence or absence of the  <distributable />  element in /WEB-INF/web.xml.
• The maxInactiveInterval attribute has been deprecated in 8.0. If the value is specified, a warning log is issued. This should be configured via the Context. The value is inherited based on the value of the <session-timeout> element in /WEB-INF/web.xml.
• The  sessionIdLength attribute of Manager has been replaced by sessionIdLength attribute of SessionIdGenerator.

Cookies: The default CookieProcessor  is now the  Rfc6265CookieProcessor. The  CookieProcessor is configurable per Context and the  LegacyCookieProcessor  may be used to obtain the 8.0.x behavior.

Web Applications: The Manager and HostManager web applications are configured by default with a RemoteAddrValve that limits access to those applications to connections from localhost.

Engine and Host Configurations: The behavior for  startStopThreads has changed when the effective value is 1. In this case, children will be started on the current thread rather than via an ExecutorService configured with a single thread.

Context configurations: The  clearReferencesStatic  attribute has been removed in 8.5.x and 9.0.x.

Logging: By default the log files will be kept 90 days and then removed from the file system.

Upgrading 9.0.x: When upgrading instances of Apache Tomcat from one version of Tomcat 9.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 9. In 9.0.31 onwards,

• The default listen address of the AJP Connector was changed to the loopback address rather than all addresses.
• The  requiredSecret  attribute of the AJP Connector was deprecated and replaced by the secret attribute.
• The  secretRequired  attribute was added to the AJP Connector. If set to true, the default, the AJP Connector will not start unless a secret has been specified.
• The  allowedRequestAttributesPattern attribute was added to the AJP Connector. Requests with unrecognized attributes will now be blocked with a 403. 

Considerations Before Upgrading or Migrating

When updating from one major Apache Tomcat version a newer one, we need to make sure that the JVM that is installed on our system supports at least the required Java version. While it is possible that older versions of Tomcat may not be compatible with newer JVMs, all the currently supported Apache Tomcat versions (7.0.x, 8.5.x, 9.0.x and 10.0.x) are known to run correctly on Java 8 JVMs.

When migrating from one major Tomcat version to another (e.g. from Tomcat 7 to Tomcat 8, or from Tomcat 8 to Tomcat 8.5), we should not copy the configuration files from the old version to the new version. The recommended approach is to start with the default configuration of the new version of Apache Tomcat and to adjust it as necessary.

When migrating from one minor release to another minor release within the same major release (e.g. from Tomcat 7.0.27 to Tomcat 7.0.28) we can retain the configuration files, but we should check to see if any defaults have changed and/or if any new elements have been added and adjust your configuration files accordingly.