Update Custom Plugins for JDK 17 Upgrade

The upcoming version of Digital.ai Deploy 24.1 requires upgrading to Java 17 as it is the next Long Term Support (LTS) version of the JDK. This ensures that Deploy has access to the latest Java functionalities and as well as up to date security fixes.

Note: The official Deploy 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 Deploy 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 Deploy 24.1.

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 Deploy database are scanned for Java 17 compatibility
• -verifyPlugins filesystem - The plugins stored in the local filesystem for the Deploy 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.

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 Deploy 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 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 Deploy service and it's running JDK 17.
2. Follow the installation procedure for Deploy.
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 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.

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

2. Stage the 24.1 version on the Deploy server.

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

4. From the staged 24.1 version, run the following command to upgrade to 24.1 For more information about upgrading, see Upgrade Deploy.

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

5. 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'

6. 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'

7. Launch the Deploy 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 jdk-plugin-compatibility-check.on-product-upgrade to false in the deployit.conf file.

Plugin Install Check

To turn off the compatibility check during plugin install or update, set the configuration entry jdk-plugin-compatibility-check.on-plugin-install to false in the deployit.conf file.