Changes/Tomcat10ChangeProposal

Change Proposal Name

Tomcat 10.1.x

Summary

This change involves upgrading the Apache Tomcat application server from versions 9.0.x to 10.1.x. This update will enhance the application server's performance, security, and support for the latest specifications. The affected packages include tomcat and related libraries and services that rely on the Tomcat server for web application deployment and management.

Owner

• Name: Dimitris Soumis
• Email: dsoumis@redhat.com
• Name: Coty Sutherland
• Email: csutherl@redhat.com
• Name: Sokratis Zappis
• Email: szappis@redhat.com

Current status

• Targeted release: Fedora Linux 42
• Last updated: 2024-06-20
• [Announced]
• [<will be assigned by the Wrangler> Discussion thread]
• FESCo issue: <will be assigned by the Wrangler>
• Tracker bug: <will be assigned by the Wrangler>
• Release notes tracker: <will be assigned by the Wrangler>

Detailed Description

The proposed migration from Apache Tomcat 9.0.x to 10.1.x in Fedora releases aims to leverage the improvements and new features introduced. Tomcat 10.1.x supports the Jakarta EE 10 specification, which involves a namespace change from javax.* to jakarta.*. This upgrade will provide better performance, enhanced security features, and compatibility with modern Java applications. It will impact the tomcat package and any related libraries and services, requiring updates to ensure compatibility with the new Jakarta EE namespace and other changes in Tomcat 10.1.x.

Details:

• Apache Tomcat 10.1.x requires Java 11 or later.
• Specification APIs: Apache Tomcat 10.1 supports the Jakarta Servlet 6.0, Jakarta Pages 3.1, Jakarta Expression Language 5.0, JakartaWebSocket 2.1 and Jakarta Authentication 3.0 specifications. There is a significant breaking change between Tomcat 9.0.x and Tomcat 10.1.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 10 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 can be used ahead of time to benefit from faster deployment time and more precise conversion configuration options.
• Servlet 6.0 API: The Java package has changed from javax.servlet to jakarta.servlet.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.
• Pages 3.1: The Java package has changed from javax.servlet.jsp to jakarta.servlet.jsp. Added an option to raise a PropertyNotFoundException when an EL expression contains an unknown identifier.
• Expression Language 5.0: The Java package has changed from javax.el to jakarta.el. The EL API now uses generics where appropriate. The deprecated MethodExpression.isParmetersProvided() method has been removed from the API.
• WebSocket 2.1: The Java package has changed from javax.websocket to jakarta.websocket. 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 4.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.
• 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.

Feedback

No feedback is received.

Benefit to Fedora

This migration ensures that Fedora stays aligned with the latest standards and best practices in Java-based web server technology. The enhancements in Tomcat 10.1.x lead to a more robust and secure application server, providing a stronger foundation for applications deployed on Fedora. By keeping Fedora's software stack updated, the distribution maintains its reputation for cutting-edge technology. Developers will benefit from Tomcat's latest features, improved support for modern development practices, and better integration with contemporary tools, making Fedora a more attractive platform for Java developers. Additionally, staying current with software versions attracts new contributors and keeps the community engaged. Providing the latest tools and technologies by default simplifies onboarding and encourages effective contributions from new participants.

Scope

• Proposal owners: To complete this feature in time for the release, feature owners need to perform the following tasks:

   * Update the tomcat package to the latest 10.1.x version using upstream sources.
   * Ensure that all necessary patches and custom modifications are applied to maintain compatibility and functionality within the Fedora ecosystem.
   * Update the tomcat-native recommended package to the latest 2.0.x to ensure compatibility with Tomcat 10.1.x.

This migration is an isolated change, primarily affecting the tomcat package and does not have an impact on other parts of the distribution.

• Other developers: N/A

• Release engineering: N/A

• Policies and guidelines: N/A

• Trademark approval: N/A

• Alignment with the Fedora Strategy: Yes

Upgrade/compatibility impact

There is a significant breaking change between Tomcat 9.0.x and Tomcat 10.1.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 10 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 can be used ahead of time to benefit from faster deployment time and more precise conversion configuration options.

When migrating from one major Tomcat version to another (9.0.x -> 10.1.x), users 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.

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.

   * 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.
   * 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.
   * The system property org.apache.juli.AsyncLoggerPollInterval is no longer used.
   * The default value for the Connector attribute maxParameterCount has been reduced from 10,000 to 1,000.
   * The EL API no longer uses a privileged block to obtain the thread context class loader unless explicitly configured to do so via the org.apache.el.GET_CLASSLOADER_USE_PRIVILEGED system property. When using the EL API within Apache Tomcat this system property does not need to be set as all calls are already wrapped in a privileged block further up the stack. It may be required if using the EL API under a SecurityManager outside of Apache Tomcat.
   * The APR connector has been removed. Along with that, APIs that are not needed for the use of OpenSSL have been removed from the tomcat-native library.
   * 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.

Early Testing (Optional)

Do you require 'QA Blueprint' support? Y/N

N

How To Test

To ensure the successful implementation of the migration from Tomcat 9.0.x to 10.1.x, follow these steps to test the change.

• Ensure your system has the latest Fedora release installed.
• Install the Tomcat package using the following command:

   dnf install tomcat

• Develop or obtain a sample web application that uses Jakarta EE APIs.
• Deploy your application by placing your WAR file in the Tomcat webapps directory:

   cp your-application.war /var/lib/tomcat/webapps/

• Start the Tomcat service:

   systemctl start tomcat

• Check Tomcat logs to ensure the server is running and the application has been deployed successfully:

  cat /usr/share/tomcat/logs/catalina.*.log

• The Tomcat service should start without errors. You can verify the status with:

  systemctl status tomcat

• The web application should be deployed successfully. You can access it via a web browser at:

  http://localhost:8080/your-application

User Experience

Users will experience better support for modern Java standards as Tomcat 10.1.x fully supports Jakarta EE 10. This means developers can leverage the latest APIs and features in their applications, promoting more efficient and robust application development. Overall, the upgrade to Tomcat 10.1.x will provide a more powerful, secure, and developer-friendly environment, enhancing the overall user experience on Fedora.

Dependencies

Tomcat dependencies:

alsa-lib
apr
copy-jdk-configs
cups-libs
ecj
java-21-openjdk-headless
javapackages-filesystem
javapackages-tools
lksctp-tools
lua
lua-posix
tomcat-el-3.0-api
tomcat-jsp-2.3-api
tomcat-lib
tomcat-servlet-4.0-api
tzdata-java

Tomcat weak dependencies:

tomcat-native 

Contingency Plan

Revert the update.

• Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
• Contingency deadline: N/A (not a System Wide Change)
• Blocks release? N/A (not a System Wide Change), Yes/No

Documentation

Upstream documentation

Release Notes

Upstream changelog