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 as well as up to date security fixes.

Note: The official Release plugins are already updated to operate with Java 17. However, all the locally developed (custom) plugins should be validated for full Java 17 compatibility before deploying it 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.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, in order 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 the 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. As a result, an error message is displayed on 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, then the plugin must be upgraded before launching it to the 24.1 or later Release.

Verify Local Plugin Compatibility

If a locally developed plugin uses classes coming 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 the following commands:

   Linux

   plugin-manager-cli.sh 

   Windows

   plugin-manager-cli.cmd

2. Run the following command to verify the 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, use the jakarta packages listed above to update.

4. Now, prepare a new version of the local plugin with an incremented version number to be used 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, if the locally developed plugins that will be installed are checked for Java 17 compatibility.

Verify for Upgrade

Before upgrading to 24.1 or later version, all the local plugins should be checked for Java 17 compatibility. Any incompatible plugins should be updated, and a new plugin must be prepared with a new version before you upgrade.

Note: Identify if you are running the following official plugins:

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

If so download a 24.1 or later version of the plugins to update, 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 the following command to upgrade to 24.1 or later. For more information about upgrading, see Upgrade Release:

   ./run.sh -setup -previous-installation `XL_RELSE_SERVER_HOME_EXISTING`

5. If the deployment has the xlr-delivery-insights-integration or xlr-auth-spnego-plugin installed, copy the 24.1 or later version of the plugin to the plugins/xlr-official directory on the 24.1 or later release tree.

6. Using the Plugin Manager CLI, delete any local plugins that are installed on the system that are Java 17 incompatible, by running the following command:

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

7. Using the Plugin Manager CLI, install the Java 17 compatible version of the local plugins that were deleted in the previous step, by running the following command:

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

8. Launch the Release service. Enter Yes when prompted to execute upgraders.

Turn On/Off Compatibility Checks

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

Sometimes valid exceptions can exist during a system upgrade or plugin installation. In such cases, you can turn off the following checks:

System Upgrade Check

To turn off the compatibility check during system upgrade, set the configuration entry xl.features.plugins.check-jdk17-compatibility.on-product-upgrade to false in the xl-config.conf file.

Plugin Install Check

To turn off the compatibility check during plugin install or update, set the configuration entry xl.features.plugins.check-jdk17-compatibility.on-plugin-install to false in the xl-config.conf file.