Update Custom Plugins for JDK 21 Upgrade

Digital.ai Release 25.3 and later requires Java 21 (OpenJDK 21), the latest Long Term Support (LTS) version of the JDK. This ensures that Release has access to the latest Java functionalities and up-to-date security fixes.

note

The official Release plugins are already updated to operate with Java 21. However, all locally developed (custom) plugins should be validated for full Java 21 compatibility before deploying them on a Release 25.3 or later instance.

What is Changed

With the rebranding of Java EE to Jakarta EE, many libraries have undergone changes in package names and are no longer compatible with the previous versions. For more information, see Transition from Java EE to Jakarta EE.

The following packages have been removed from JDK 17 (and later) and reintroduced in a jakarta namespace:

Pre-jakarta	Post-jakarta
javax.activation	jakarta.activation
javax.annotation	jakarta.annotation
javax.batch	jakarta.batch
javax.ejb	jakarta.ejb
javax.el	jakarta.el
javax.enterprise	jakarta.enterprise
javax.faces	jakarta.faces
javax.json	jakarta.json
javax.jws	jakarta.jws
javax.mail	jakarta.mail
javax.persistence	jakarta.persistence
javax.resource	jakarta.resource
javax.servlet	jakarta.servlet
javax.validation	jakarta.validation
javax.websocket	jakarta.websocket
javax.ws.rs	jakarta.ws.rs
javax.xml.bind	jakarta.xml.bind

Why Upgrade is Needed

If you're using one or more of the above-mentioned Pre-JDK 17 packages in your custom plugin code, you must update your plugin with the corresponding jakarta packages to run it with Release 25.3 or later.

Follow the instructions below to understand how to verify the local plugins for compatibility and upgrade them.

Verify using Plugin Manager CLI

The Plugin Manager CLI is enhanced to scan plugins for Java 21 compatibility. For more information, see Plugin Manager CLI.

The following commands are added to the Plugin Manager CLI:

• -verifyLocalPlugins "directory path" - All Java and Python plugin files available in the specified directory are scanned for Java 21 compatibility
• -verifyLocalPlugins "file path" - The specified plugin file is scanned for Java 21 compatibility
• -verifyPlugins database - The plugins in the Release database are scanned for Java 21 compatibility
• -verifyPlugins filesystem - The plugins stored in the local filesystem for the Release instance are scanned for Java 21 compatibility

Verify using Plugin Manager UI

• The Plugin Manager UI is updated to ensure that plugins installed or updated using the Upload button are scanned for Java 21 compatibility. For more information, see Plugin Manager.
• If a plugin is found to be incompatible with Java 21, it will not be installed or updated, and an error message will be displayed in the upper-right corner of the screen.

Updating Non-Bundled Official Plugins on Upgrade

The following official plugins are not bundled with the kit but require an updated version for Java 21 compatibility:

• xlr-delivery-insights-integration
• xlr-auth-spnego-plugin

If a deployment is running these plugins, they must be upgraded before launching to Release 25.3 or later.

Verify Local Plugin Compatibility

If a locally developed plugin uses classes from any of the above pre-JDK 17 packages, an update to use the jakarta counterpart is required.

1. Access the Plugin Manager CLI by navigating to the bin folder of the Digital.ai Release distribution and execute:

   Linux:

   ./plugin-manager-cli.sh

   Windows:

   plugin-manager-cli.cmd

2. Run the following command to verify plugins in the plugins/__local__ folder for incompatibility:

   ./plugin-manager-cli.sh -verifyLocalPlugins 'path_to_directory_containing_local_plugins'

3. If an incompatible plugin is identified, update it to use the jakarta packages listed above.

4. Prepare a new version of the local plugin with an incremented version number for use in the 25.3 or later deployment.

Verify for New Installation

1. Ensure that the JAVA_HOME environment variable is set correctly for the user or service that will run the Release service and it's running JDK 21 or later.
2. Follow the installation procedure for Release.
3. Verify that locally developed plugins to be installed are checked for Java 21 compatibility.

Verify for Upgrade

Before upgrading to 25.3 or later version, check all local plugins for Java 21 compatibility. Update any incompatible plugins and prepare new versions before upgrading.

note

Check if you are running either the xlr-delivery-insights-integration or xlr-auth-spnego-plugin plugins. If so, download 25.3 or later versions from the distribution site.

1. Stop the Release service on each node in the cluster.

2. Stage the 25.3 or later version on the Release server.

3. Update the JDK version for Release to JDK 21 or later.

4. From the staged 25.3 or later version, run:

   ./run.sh -setup -previous-installation XL_RELEASE_SERVER_HOME_EXISTING

5. If needed, copy the 25.3 or later versions of xlr-delivery-insights-integration or xlr-auth-spnego-plugin to the plugins/xlr-official directory.

6. Delete any Java 21 incompatible local plugins:

   ./plugin-manager-cli.sh -delete 'plugin_name'

7. Install the Java 21 compatible versions of the local plugins:

   ./plugin-manager-cli.sh -add 'plugin_file_to_add'

8. Launch the Release service, confirming the execution of upgraders when prompted.

Turn On/Off Compatibility Checks

note

Be cautious when disabling compatibility checks. This action can allow incompatible plugins to be installed, potentially causing service disruptions.

For valid exceptions during system upgrade or plugin installation, you can turn off the following checks:

System Upgrade Check

To disable compatibility checking during system upgrade, set this property in xl-release.conf:

xl.features.plugins.check-jdk17-compatibility.on-product-upgrade = false

Plugin Install Check

To disable compatibility checking during plugin installation or updates, set this property in xl-release.conf:

xl.features.plugins.check-jdk17-compatibility.on-plugin-install = false

Troubleshoot Plugin Validation Warning

While scanning plugins or validating JDK 21 compatibility, you may encounter the following error in the logs:

ERROR o.j.w.d.f.FernflowerDecompiler - Unable to simplify switch on enum: 1 not found, available: {}

This warning is generated by a third-party decompiler used during plugin validation. This does not indicate a problem with the plugin itself, and does not affect its functionality.

If the plugin has been confirmed to be JDK 21 compatible, you can safely ignore this message.