IBM Java for AIX Reference : Java Upgrade Checklist

When planning a product upgrade or migration, it is important to assess the current application requirements, then identify and resolve all potential compatibility concerns that may be introduced by the more recent IBM Java version. The following list contains common areas of focus:

a. Compatibility with native code modules such as executables and native libraries
b. Changes to security models and configuration
c. Application specific features such as language support and depreciated or modified API calls
d. Changes in application workload, program behavior, expected input and output format.
e. Modifications to tools and utilities provided by IBM and other vendors

For applications obtained through other vendors, customers should work directly with those vendors to identify and resolve all compatibility issues. For in-house designed applications, developers should (at a minimum) attempt to recompile all application modules (Java and native) to identify any potential issues that need to be resolved.

An upgrade or migration of IBM Java on AIX may result in some existing configuration, properties and security policy files being overwritten or introduce a conflict of shared modules between the previous and newer versions. Therefore, it is strongly recommended that the complete Java installation be backed up prior to any upgrade or migration. To further ensure a successful upgrade or migration, the following files should be backed up, restored or reconfigured after the upgrade is completed (when applicable). Make sure to check the syntax of the new files before restoring the original files, the format or options for the files might have changed.


After the upgrade, if the existing configuration, properties, and any security files are overwritten during the upgrade process, restore or reconfigure the files.

Back up all the configuration, properties, security policy files or the directories they reside in before the upgrade.

Java security and policy files may be overwritten during the upgrade or migration process. Newer versions of IBM Java will attempt to maintain a backup copy of these files, however it is recommended that the files in the following directories be backed up prior to the start of the upgrade or migration:

Example:
/JAVA_PATH/jre/lib/ext
/JAVA_PATH/jre/lib/security
/etc/JAVA

Many times, the application environment is configured for the specific version and location of Java being used. When upgrading or migrating to a newer version or release level, review and modify key environment settings that made references to the previous installation. Most of these configuration parameters can be found in user profiles (e.g., $HOME/.profile), application profiles, scripts used to launch the application, and/or system profiles (e.g., /etc/environment). Below is a list of common environment variables that should be reviewed.


a. JAVA_HOME variable

Set the JAVA_HOME environment variable to the upgraded Java install location:


Example:

# export JAVA_HOME=JAVA_PATH




b. PATH variable

Make sure the environment is set to use the upgraded Java install:

Set the user's profile, any scripts that launch java application and or /etc/environment to use the upgraded Java:


Example:

# export PATH=JAVA_PATH/bin:$PATH



c. Add the path to the Java launchers and tools:


Example:

# export PATH=JAVA_PATH/bin:JAVA_PATH/jre/bin:$PATH



d. LIBPATH variable

Set the LIBPATH variable to a colon-separated list of directories to define from where system and user libraries are loaded.


Example:

# export LIBPATH=JAVA_PATH/lib:JAVA_PATH/lib/ARCH:JAVA_PATH/lib/ARCH/default:$LIBPATH



e. CLASSPATH variable


Set the CLASSPATH to search for application CLASSES and resources.


Example:
# export CLASSPATH=JAVA_PATH/lib:JAVA_PATH/jre/lib:$CLASSPATH

Once the upgrade or migration is completed and environment changes have been made, confirm the changes by following these steps:

a. Log in to the system as the appropriate user id
b. From the command prompt, execute any modified user or application profiles containing the references to environment settings.
c. From the same command prompt, execute the following commands to confirm they have the correct configuration:


a. Verify Java executable, its permissions and its location.


# which java
/usr/java7_64/bin/java


# java -version
java version "1.7.0"
Java(TM) SE Runtime Environment (build pap6470sr10fp1-20170215_01(SR10 FP1))
IBM J9 VM (build 2.6, JRE 1.7.0 AIX ppc64-64 Compressed References 20170111_332921 (JIT enabled, AOT enabled)
J9VM - R26_Java726_SR10_20170111_1358_B332921
JIT - tr.r11_20170107_130494
GC - R26_Java726_SR10_20170111_1358_B332921_CMPRSS
J9CL - 20170111_332921)
JCL - 20170215_01 based on Oracle jdk7u131-b12


If the environment variables do not reference the correct Java location or an incorrect version of Java is shown, then work with the system administrator, application development team, or application vendor team to identify the correct location to modify the configuration for the specific application.



b. Run commands against the shared class cache after the upgrade has been successfully completed to confirm there are no issues.

If Java application fails to start, investigate if the Java shared class cache can be read:

Run some commands against the cache.:



To display summary information for the cache, run:

# java -Xshareclasses:CacheDir=PathToCache,printStats

or

# java -Xshareclasses:name=CacheName,printStats



If any errors in displaying the cache, remove the shared class cache:

# java -Xshareclasses:name=CacheName,destroy


Once the cache is destroyed, cache can be recreated either manually or automatically on startup or using shared classes printStats or printAllStats Java command line option.



For other Cache commands, refer to
https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.aix.80.doc/diag/appendixes/cmdline/Xshareclasses.html

After reading and following the above instructions, if further assistance is required, please complete the following steps:

1. Confirm that you have reviewed and completed all of the above steps.

2. Contact IBM and open a new IBM service request (i.e., a new IBM PMR).

3. Collect and upload data as per the data collection procedures noted in the above sections or package and upload the current data and details by following the instructions on this web page:

IBM Java for AIX MustGather: How to upload diagnostic data and testcases to IBM

If, after reading and following the above instructions, further assistance is required, please complete the following steps:

1. Confirm that you have review and completed all of the above steps.

2. Contact IBM and open a new IBM service request (i.e., a new IBM PMR).

3. Collect and upload data as per the data collection procedures noted in the above sections or package and upload the current data and details by following the instructions on this web page:

IBM Java for AIX MustGather: How to upload diagnostic data and testcases to IBM