Java 8 to Java 25 migration guide

Migration Guide: Java 8 to IBM Semeru Runtime Certified Edition for z/OS, 25

• Download the latest SDK

This document provides a consolidated, end-to-end migration guide for migrating applications from IBM® SDK, Java™ Technology Edition 8 to IBM Semeru Runtime® Certified Edition for z/OS® 25. Migration spans multiple major releases (11, 17, 21 and 25) and introduces changes in product packaging, platform support, security, encoding, performance, native access, and APIs.

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.

Migration Path Guidance

• IBM recommends migrating directly from Java 8 to Java 25.
• For complex applications, a phased validation approach can help isolate compatibility issues. However, given that Java 11 is already end of support and Java 17 reaches end of support in September 2026, we do not recommend using these interim versions as migration targets. To avoid unnecessary rework and repeated migrations, customers are encouraged to move directly from Java 8 to a currently supported long term platform such as Java 21 or Java 25 and perform validation there.
• Java 8 to Java 21 migration guide can be accessed here.

Action required: Choose an appropriate migration strategy based on application complexity and risk tolerance.

Product, Platform, and Packaging Changes

• The product name changed from IBM SDK, Java Technology Edition to IBM Semeru Runtime Certified Edition for z/OS starting with Java 11.
• 31-bit SDKs are no longer supported. Applications using 31-bit JNI libraries must be ported to 64-bit. For more information, see Porting Java applications to 64-bit systems.
• Support for z/OS 2.5 and earlier releases has been removed in Java 25.
• Fonts are not bundled with the SDK. Semeru Runtimes relies on system-installed WorldType fonts located in /usr/lpp/fonts/worldtype. For more information, see Semeru fonts support on z/OS.

Action required: Validate operating system support, recompile any 31-bit native code, and ensure required fonts are installed.

Module system and class libraries

• Java 11 introduced the Java Platform Module System, which enforces strong encapsulation of JDK internals.
• Class libraries are now based on OpenJDK’s implementation.
• Applications relying on com.ibm.* internal packages, sun.* packages, or other JDK internals must be refactored. Use the Java Dependency Analysis Tool (jdeps) and the --illegal-access=warn option of the java command to help you determine if your applications use any internal APIs. For more information, see Determining application compatibility: internal APIs.

Action required: Identify and replace unsupported APIs or apply supported access mechanisms where available.

Removed and deprecated technologies

• The IBM implementation of XML is replaced with the OpenJDK implementation of XML.
• Java EE and CORBA technologies were removed in Java 11 (JEP 320), including JAX-WS, JAXB, JAF, CORBA, and RMI-IIOP.
• Java deployment technologies such as Applets and Java Web Start are no longer available.
• Legacy tools including javah, native2ascii, and the JVMTI hprof agent have been removed.
• Many internal and proprietary APIs available in Java 8 are no longer accessible.
• Deprecated methods such as addPropertyChangeListener and removePropertyChangeListener removed.

Action required: Migrate to supported APIs, external libraries, and modern tooling alternatives.

Encoding and Charset Changes

• UTF-8 has been the default charset across platforms since Java 18 (JEP 400).
• Many IBM-specific code pages available in Java 8 are no longer supported. For more information, see Java 11 migration guide.
• Applications requiring additional code page support can use ICU4J.
• The JMX password file must be encoded with UTF-8 rather than EBCDIC.

Action required: Validate character encoding handling and evaluate alternatives for removed code pages.

Security and Cryptography

• IBMJCE and IBMJSSE2 proprietary security and cryptographic providers from Java 8 were replaced with OpenJDK-based providers SunJCE and SunJSSE.
• New providers introduced from Java 11 onward: IBMZSecurity and OpenJCEPlus.
• OpenJCEPlus is the default cryptographic provider from Java 11 onward, replacing IBMJCEPlus that was used in Java 8.
• Internal IBM security classes under com.ibm.security and com.ibm.misc are no longer available in Java 25.
• The Java Security Manager is permanently disabled in Java 25 (JEP 486).
• New JNDI properties introduced in Java 21: jdk.jndi.ldap.object.factoriesFilter and jdk.jndi.rmi.object.factoriesFilter.
• Cipher transformation formats are strictly enforced from Java 21 onward (algorithm/mode/padding).
• JAAS APIs changed: doAs() migrated to callAs(); doAsPrivileged() and privateDoAs() migrated to callAsPrivileged().
• Kerberos authentication behavior changed in Java 11 due to migration to the OpenJDK Krb5LoginModule implementation.

Action required:

• Review cryptographic configurations, refactor references to removed internal classes, and validate cipher usage.
• Refactor security-manager-dependent code, update JAAS usage, and review Kerberos configuration.

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 25, 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.

Native Code and JNI Changes

• Starting with Java 25, calls to restricted native methods such as System.load() and System.loadLibrary() generate warnings (JEP 472). For more information, see Java 25 migration guide.
• Native access must be explicitly enabled using JVM command-line options or JAR manifest attributes.
• Future Java releases might block restricted native access by default.
• Java 25 includes the Foreign Function and Memory (FFM) API, finalized in JDK 22, which provides a modern, standardized approach for interoperating with native code and off heap memory. The FFM API enables Java applications to call native functions, manage native memory, and integrate with existing C, C++, and system libraries in a safe and efficient manner. When migrating from Java 8, applications that use the Java Native Interface (JNI) can evaluate whether the FFM API is appropriate for new development or selective modernization, while existing JNI based implementations can continue to be used where they meet current application and performance requirements.

Action required: Update application startup scripts or JAR manifests to explicitly enable native access.

XML Processing (JAXP) Security Limits

• JAXP entity expansion and size limits were significantly reduced starting in Java 24 to mitigate XML-based attacks.
• Applications processing large or deeply nested XML documents might encounter parsing failures under the new defaults.
• Limits can be configured using system properties, JAXP configuration files, or programmatic APIs. For more information, see Java 25 migration guide.

Action required: Review XML processing workloads and adjust limits cautiously where required.

Compression, Performance, and z/OS-specific Considerations

• Corrections in zIIP dispatching may increase general CP usage compared to Java 8; this behavior is intentional.
• OpenJ9 memory defaults introduced in Java 11, including heap sizing and the use of derived limits for Direct Byte Buffers, continue to apply in Java 25. Note the following.
• Heap sizing defaults: When -Xmx is not specified, the JVM derives the maximum heap size from available physical memory, defaulting to 25% of available memory up to a maximum of 25 GB. On systems with 2 GB or less of physical memory, the maximum heap size defaults to 50% of available memory, with enforced minimum (16 MB) and maximum (512 MB) bounds.
• Direct Byte Buffer limits: -XX:MaxDirectMemorySize controls how much native memory the JVM may use for Direct Byte Buffers. By default, the JVM derives this limit from the maximum heap size and enforces a minimum of 67,108,864 bytes (64 MiB).
• When configuring heap size or limiting native or direct buffer memory, ensure this limit is set to at least 64 MiB, as applications that rely on NIO, TLS, networking, or compression libraries can otherwise encounter direct buffer allocation failures when heap size is reduced or native memory usage is constrained.

Action required: Monitor performance metrics, validate zEDC availability, and review JVM memory tuning when migrating from Java 8.

Console, Logging, and Diagnostics

Console redirection

• Default redirection using JAVAIN, JAVAOUT, and JAVAERR DD names is no longer supported. Applications must explicitly redirect standard streams by using the JZOS API, for example ZUtil.redirectStandardStreams(), to map standard input, output, and error streams to STDIN, STDOUT, and STDERR.

JVM logging configuration (OpenJ9)

• IBM Semeru Runtime Certified Edition for z/OS uses the Eclipse OpenJ9 JVM, which provides JVM specific logging through the -Xsyslog option. The -Xsyslog command replaces the operations run by the -Xlog command in IBM SDK, Java Technology Edition, Version 8.
• A Hotspot compatible -Xlog option is also provided for compatibility with the reference implementation. However, this option does not replace -Xsyslog and provides a different and more limited set of logging capabilities.
• Applications that relied on legacy IBM SDK Java 8 logging behavior must review and update JVM logging configurations when migrating to IBM Semeru Runtimes.

Diagnostic tools and Attach API

• OpenJ9 implementations of diagnostic tools such as jcmd, jmap, jps, and jstack rely on the Java Attach API. On z/OS, use of the Attach API must be explicitly enabled and permitted through system configuration and security settings. This requirement applies to Java 8 as well and is not specific to later Java versions.
• These tools are OpenJ9 implementations and may differ in behavior or output compared to the reference Java implementation.
• Health Center is deprecated now, and JDK Flight Recorder is available in IBM Semeru Runtimes. For more information, see JDK Flight Recorder.

Action required: Update console redirection mechanisms and verify monitoring and diagnostic tooling on z/OS.

Developer Migration Checklist

• Verify supported z/OS level and hardware prerequisites.
• Identify use of removed or internal APIs (com.ibm.*, sun.*, or other JDK internals).
• Assess use of JNI or other native libraries and plan for native access enablement.
• Review security provider configuration and JAAS usage.
• Validate XML processing workloads against reduced JAXP security limits.
• Audit file I/O and character encoding assumptions after UTF-8 becomes the default charset.
• Review logging, console output, and monitoring configurations.
• Perform functional and performance testing, including zIIP and CP usage analysis.

Reference Documentation

IBM Semeru Runtime Certified Edition for z/OS migration documentation for Versions 11, 17, 21, and 25:

• Java 11 migration guide
• Java 17 migration guide
• Java 21 migration guide
• Java 25 migration guide