Skip to content

How to avoid Java Runtime failures during CF upgrade on older DX systems

Applies to

HCL Digital Experience version 8.5 and higher

Introduction

Starting from Cumulative Fix (CF) 238, CF packages include Java 8 binaries. Your HCL DX environment must run Java 8 before you apply new CFs. Environments that run on Java 7 fail during upgrade with class version incompatibility errors.

Important

This requirement is a permanent baseline for future CF upgrades. All new CF packages require Java 8. No fallback path exists for Java 7 environments.

Instructions

To avoid Java Runtime Environment (JRE) failures during CF upgrades, perform the following steps:

Installing Java 8 using the IIM

The IBM Java 8 Software Development Kit (SDK) for the WebSphere Application Server (WAS) is distributed as a fix pack through IBM Fix Central and installed using the IBM Installation Manager (IIM). Do not replace the Java Development Kit (JDK) manually. Install it through IIM to ensure proper package tracking.

Before using the IIM for this upgrade path, ensure the IIM runtime itself is running on Java 8 or newer. For more information, refer to Java Runtime Environment.

  1. Download the IBM Java 8 SDK package:

    1. Go to IBM Fix Central.
    2. Under Find product, in the Product selector box, search for and select WebSphere Application Server.
    3. In the Installed Version box, select your version (for example, 8.5.5.0).
    4. In the Platform box, select your platform (for example, AIX), and then select Continue.
    5. Search for Individual fix IDs matching the pattern 8.5.5.*-WS-IBMWASJAVA* (for example, 8.5.5.24-WS-IBMWASJAVA-LinuxX64), and then select Continue.
    6. Download the appropriate SDK package for your OS and architecture.

  2. Install the IBM Java 8 SDK using the IIM in silent mode:

    ${IIM_INSTALL_ROOT}/eclipse/tools/imcl install \
com.ibm.java.jdk.v8 \
-repositories /path/to/sdk/repo \
-installationDirectory ${WAS_INSTALL_ROOT}/AppServer \
-acceptLicense
    • /path/to/sdk/repo: The directory containing the extracted SDK package.

    • com.ibm.java.jdk.v8: The offering ID that installs the IBM Java 8 SDK into the WAS installation directory.

      To confirm the exact offering ID in your downloaded package:

      imcl listAvailablePackages -repositories /path/to/sdk/repo

  3. Verify that WAS recognizes the new SDK:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh -listAvailable

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat -listAvailable

    You should see an entry for 1.8 in the output.

Switching WAS profiles to Java 8

Installing the SDK does not automatically switch profiles to use it. Each profile must be explicitly updated using the managesdk command. For more information, refer to managesdk command and Upgrading to Java 8.

  • To switch to a specific profile:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh \
-enableProfile \
-profileName <ProfileName> \
-sdkname 1.8_64

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat \
-enableProfile \
-profileName <ProfileName> \
-sdkname 1.8_64
    • <ProfileName>: The profile name (For example, wp_profile)
    • 1.8_64: The exact SDK name. To check the SDK name, run -listAvailable.

  • To switch all profiles at once:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh \
-enableProfileAll \
-sdkname 1.8_64

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat \
-enableProfileAll \
-sdkname 1.8_64

    This command updates every profile registered under the WAS installation to use Java 8.

  • To set Java 8 as the default SDK for WAS:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh \
-setNewProfileDefault \
-sdkname 1.8_64

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat \
-setNewProfileDefault \
-sdkname 1.8_64

    This ensures future profile creations default to Java 8.

  • To set Java 8 as the command-line default:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh \
-setCommandDefault \
-sdkname 1.8_64

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat \
-setCommandDefault \
-sdkname 1.8_64

    This command configures administrative scripts to use Java 8 by default.

Verifying end-to-end resolution

Confirm that the ConfigEngine JRE, the profile JVM, and the IIM JRE all resolve to Java 8, not Java 7.

  • To verify ConfigEngine JRE:

    ${WAS_INSTALL_ROOT}/AppServer/java/bin/java -version

    "${WAS_INSTALL_ROOT}\AppServer\java\bin\java.exe" -version

  • To verify that all profiles run Java 8:

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.sh -listEnabledProfileAll

    ${WAS_INSTALL_ROOT}/AppServer/bin/managesdk.bat -listEnabledProfileAll

    All profiles used during the CF application process must show 1.8 (Java 8).

  • To verify IIM JRE:

    ${IIM_INSTALL_ROOT}/eclipse/jre/bin/java -version

    "${IIM_INSTALL_ROOT}\eclipse\jre\bin\java.exe" -version

Applying CF packages to your environment

Once all Java versions are verified, proceed with the upgrade. For details, refer to Applying a Combined Cumulative Fix

There is no supported path to apply a new CF while remaining on Java 7. This requirement applies to all future CFs.

Troubleshooting

Scenario Symptom Resolution
Java 8 is installed on the machine but the profile still points to Java 7. Class version errors during applyCF.sh Run managesdk to switch the profile to Java 8.
WAS SDK and profiles are on Java 8, but the IIM JRE is still running on Java 7. Class version errors Update IIM to use Java 8.
Multiple nodes in the topology use inconsistent SDK versions. Runtime class and method resolution failures (for example, NoSuchMethodError) on non-upgraded nodes. Update all nodes to Java 8 SDK.
Related information

Java installation instructions:

Operating system-specific SDK upgrade procedure:

Other related topics: