Java 8 to Java 21 migration guide

Migration Guide: Java 8 to Java 21 on IBM Semeru Certified Edition for z/OS

• Download the latest SDK

This guide contains considerations for users who are migrating from IBM® SDK, Java™ Technology Edition, Version 8 to version 21 of the IBM Semeru Runtime™ Certified Edition.

Significant differences exist between IBM SDK, Java Technology Edition V8 and the IBM Semeru Runtimes. Some changes might require updates to your application code.

Note: If you are migrating from IBM SDK, Java Technology Edition, version 7 or version 7.1, read the additional information provided in this IBM Documentation topic.

Product and platform changes

• Name changed from IBM SDK, Java Technology Edition to IBM Semeru Runtime Certified Edition.
• 31-bit SDK is no longer available. Applications using 31-bit JNI libraries must be ported to 64-bit.
• Older z/OS levels (e.g., z/OS 2.4) are no longer supported in Java 21.

Security and Cryptography

• IBM proprietary providers (e.g., IBMJCE, IBMJSSE2) replaced with OpenJDK equivalents.
• New providers introduced: IBMZSecurity, OpenJCEPlus.
• console.encoding deprecated in favor of stdout.encoding and stderr.encoding (Java 21.0.6 and earlier); reintroduced in 21.0.7 with precedence rules.
• New JNDI properties in Java 21: jdk.jndi.ldap.object.factoriesFilter and jdk.jndi.rmi.object.factoriesFilter.
• Stricter format validation for cipher transformation strings in Java 21.

Encoding and charset

• UTF-8 is the default charset from JDK 18 onwards. The change to adopt UTF-8 might cause migration challenges for existing Java applications that are running on z/OS and that interact with non-UTF-8 files while you migrate to Semeru 21. For more information, see Migration from previous releases section in JEP 400 topic.
• Many IBM-specific encodings from Java 8 are no longer supported.
• JMX password file must be UTF-8 encoded (was EBCDIC in Java 8).

Removed and deprecated APIs

• CORBA, RMI-IIOP, Java EE Modules removed in Java 11 (JEP 320).
• Applets, Java WebStart, and related tools removed.
• Tools removed: javah, native2ascii, hprof, and others.
• Deprecated methods such as addPropertyChangeListener and removePropertyChangeListener removed.

Module system and class libraries

• Java 11 introduces Java Platform Module System (JPMS).
• Class libraries now based on OpenJDK.
• XML, security, and font rendering libraries changed significantly.

Compression and performance

• The Semeru SDKs ensure that only eligible tasks are sent to the zIIP, unlike Java 8, which sometimes incorrectly directs ineligible tasks to zIIP; this change might increase CP usage for specific workloads as intended in Semeru.
• zEnterprise® Data Compression (zEDC) support available in Java 8 and 11; temporarily removed in early Java 17 and 21 releases, reintroduced later.
• Java 11 (OpenJ9) changes default heap size and memory allocation behavior.
• Direct byte buffer memory is now 87.5% of max heap.

Console and logging

• JAVAIN, JAVAOUT, JAVAERR DD names removed. Use STDIN, STDOUT, STDERR with ZUtil.redirectStandardStreams().
• Logging: -Xsyslog replaces -Xlog in OpenJ9.
• New tools introduced: jcmd, jmap, jps, jstack, jstat.

Compatibility and migration tools

• Check compatibility using IBM-provided tools and documentation.
• Kerberos configuration changes: Java 11 and higher versions use OpenJDK’s Krb5LoginModule with different behavior.

Recommendations

• Validate and configure java.security file for security provider changes.
• Test encoding behavior, especially with non-UTF-8 files.
• Update cipher configurations to comply with Java 21 rules.
• For more information, see the following migration documents.
  • Java 11 migration guide
  • Java 17 migration guide
  • Java 21 migration guide