Java 21 / Tomcat 10.1 Upgrade Guide

Brightspot 5.0 requires Java 21 and Tomcat 10.1. This guide covers the steps to upgrade your project's Java version, migrate to Jakarta EE, and update your container images.

Prerequisites

• Review the Java 11 / Tomcat 9 Upgrade Guide if your project has not yet completed that upgrade.
• Ensure the environments the upgrade will be deployed to (lowers and production) support Java 21.

Update Java version

If your project uses the Brightspot Gradle plugins, set the Java version in settings.gradle:

1
brightspot {
2

3
    versions {
4
        java = 21
5
    }
6
}

Otherwise, replace the Java version in your root build.gradle:

1
sourceCompatibility = JavaVersion.VERSION_21
2
targetCompatibility = JavaVersion.VERSION_21

Java EE to Jakarta EE migration

Tomcat 10.1 requires Jakarta EE. Your project's packages and imports must be migrated from javax.* to jakarta.*. For full details on the migration, see the Apache Tomcat 10 migration guide.

As a temporary solution, you can use the Brightspot Gradle Jakarta Substitution Plugin instead of migrating all packages immediately.

Brightspot Gradle Jakarta Substitution Plugin

This plugin substitutes Java EE for Jakarta EE at build time to support projects running on Jakarta EE 10 (Tomcat 10.1). It includes the Apache Tomcat Migration CLI tool.

Add the plugin to your WAR module's build.gradle (e.g., web/build.gradle or site/build.gradle):

1
plugins {
2
    id 'com.brightspot.war'
3
    id 'com.brightspot.jakarta-substitution' version '3.4.0'
4
}

warning

This plugin is intended as a temporary solution. Plan to fully migrate your packages and imports to Jakarta EE.

Update container images

Local container

Update the image in your docker-compose.yml and etc/container/Dockerfile:

1
image: brightspot/tomcat:10.1.43-jdk21-86

Hosted container

Update the ECR reference in etc/container/Dockerfile. Replace the region with your own and verify you are using the latest container release:

1
348878804585.dkr.ecr.<region>.amazonaws.com/brightspot-cloud/10.1.48.20260130-jdk21-temurin-noble