General Page
Migration Guide: Java 8 to Java 21 on IBM Semeru Certified Edition for z/OS
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.
Loopback address selection behavior
Starting from Java 11 (JDK 8223214), the JVM no longer selects the loopback address solely based on the java.net.preferIPv6Addresses system property. In IBM SDK, Java Technology Edition 8, the JVM always returned either the IPv4 (127.0.0.1) or IPv6 (::1) loopback address based on this setting, without verifying address availability, which could cause failures in IPv4 only, IPv6 only, or misconfigured dual stack environments. From Java 11 onward, including IBM Semeru Runtime Certified Edition for z/OS 21, the JVM attempts both IPv4 and IPv6 loopback addresses and returns a valid address based on availability. Preference is still given to IPv6 when java.net.preferIPv6Addresses is set to true or system, and to IPv4 otherwise.
Action required: Review application logic or configuration that assumes a specific loopback address or forces java.net.preferIPv6Addresses and validate networking behavior after migration.
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.
Was this topic helpful?
Document Information
Modified date:
24 April 2026
UID
ibm17247070