Update Custom Plugins for JDK 17 Upgrade

The upcoming version of Digital.ai Release 24.1 or later requires upgrading to Java 17 as it is the next 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 17. However, all locally developed (custom) plugins should be validated for full Java 17 compatibility before deploying them on a 24.1 or later Release 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 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.jms	jakarta.jms
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 JDK 17 packages to run it with Release 24.1 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 17 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 17 compatibility
• -verifyLocalPlugins "file path" - The specified plugin file is scanned for Java 17 compatibility
• -verifyPlugins database - The plugins in the Release database are scanned for Java 17 compatibility
• -verifyPlugins filesystem - The plugins stored in the local filesystem for the Release instance are scanned for Java 17 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 17 compatibility. For more information, see Plugin Manager.
• If a plugin is found to be incompatible with Java 17, 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 17 compatibility:

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

If a deployment is running these plugins, they must be upgraded before launching to Release 24.1 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 24.1 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 17.
2. Follow the installation procedure for Release.
3. Verify that locally developed plugins to be installed are checked for Java 17 compatibility.

Verify for Upgrade

Before upgrading to 24.1 or later version, check all local plugins for Java 17 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 24.1 or later versions from the distribution site.

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

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

3. Update the JDK version for Release to JDK 17.

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

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

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

6. Delete any Java 17 incompatible local plugins:

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

7. Install the Java 17 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