Migrating from earlier releases of IBM SDK, Java Technology Edition

A summary of changes to the SDK and runtime environment that you must be aware of when you migrate from earlier releases of IBM® SDK, Java™ Technology Edition.

This release contains many differences from earlier releases, which might require careful planning. For an overview, read the What's new section.

If you are migrating from IBM SDK, Java Technology Edition Version 8, the following changes apply:
Changes to product deliverables and support
The following changes apply to deliverables and support:
  • The name is changed from IBM SDK, Java Technology Edition to IBM Semeru Runtime Certified Edition.
  • The 31-bit SDK package for z/OS is no longer available. If your application uses 31-bit JNI libraries, you must port them to 64-bit JNI libraries. For more information, see Porting Java applications to 64-bit systems.
  • Support is removed for older operating systems levels. For a list of the levels that are currently supported, see Installing the SDK.
Significant changes to SDK components
This release of the SDK contains the following significant changes when compared to earlier releases:
  • The components of the SDK are rewritten to use the new Java module system, which introduces several changes to the structure, content, and operation of the Java runtime.
  • This release contains class libraries from the OpenJDK project rather than proprietary class libraries that are licensed from Oracle.
  • The IBM implementation of XML is replaced with the OpenJDK implementation of XML. Some OpenJDK XML modules, notably JAX-WS and JAXB, were deprecated in Java SE 9 and removed in Java 11.
  • Many of the security providers in the IBM security implementation are replaced with the OpenJDK security implementation:
    • IBM JSSE2 provider
    • IBM JCE provider
    • IBM JCEFIPS provider
    • IBM JGSS provider
    • IBM Certification Path provider
    • IBM SASL provider
    • IBM JAAS provider
    • IBM SecureRandom provider
    • Start of changes for 11.0.16.0IBM PKCS11 providerEnd of changes for 11.0.16.0
    • XML Digital Encryption
    For more information, see Comparable OpenJDK security providers.
  • The following security providers and components are not yet available in this release. For more information about the future of these components, see the IBM Semeru Runtime Certified Edition for z/OS, Version 11: Supplementary documentation technote.
    • iKeyman utility
    • IBM Key Certificate Management utility
    As an alternative, for key and certificate management, use one of the following tools.
    • Use zseckeytool utility for JCERACFKS (RACF Software) keystore management
    • Use keytool utility for general use keystore management
    • Use IBMJCECCA keytool utility for JCECCARACFKS (RACF Hardware) keystore management
  • Make sure that the security providers that you used in Java 8 have an equivalent in the java.security file in Java 11. Also verify that the order of the providers in the file is as similar as possible to that of the java.security file in Java 8. These actions are essential for providers such as IBMJCEHYBRID and IBMJCECCA since they are not listed in the default security provider list.
  • The IBMJCEPlus cryptographic provider is renamed to OpenJCEPlus and is now the default provider. However, support for the RSAPSS and XDH algorithms, which existed in the IBMJCEPlus provider in version 8, was not added until release 11.0.19.0. For more information, see OpenJCEPlus provider.
  • Because the IBMJCE provider does not exist in this release, the getIBMJCEPrivateKey() and setIBMJCEPrivateKey() methods in the com.ibm.crypto.ibmjcehybrid.provider.HybridRACFPrivateKey class are deprecated. These methods were used for interacting with the JCERACFKS aspect of a JCEHYBRIDRACFKS keystore. Use the new getSoftwareJCEPrivateKey() and setSoftwareJCEPrivateKey() methods instead.
  • The -Dcom.ibm.security.jurisdictionPolicyDir system property, which specified an alternative directory for security policy files, is removed. This property was useful when you had to copy unlimited jurisdiction policy files to the jre/lib/security/ directory for them to be used because that directory was overwritten when you upgraded the SDK. When limited and unlimited jurisdiction policy files were moved to dedicated folders in version 8, this property became redundant and is therefore removed in this release. The ibmjcefw suboption for the -Djava.security.debug system property, which was used to print the alternative directory that you specified in the -Dcom.ibm.security.jurisdictionPolicyDir property, is also removed. For more information about these properties in version 8, see SDK Security policy files.
  • The IBM Object Request Broker (ORB) is removed. The ORB relies on CORBA and RMI-IIOP, which were deprecated by Oracle in Java SE 9 and removed in Java 11.
  • The following IBM API packages are not available in this release:
    • Networking (com.ibm.net (SocketKeepAlive)) - As an alternative, use the Java SE 11 ExtendedSocketOptions class .
    • NIO Utilities (com.ibm.nio (NioUtils)) - No known alternative exists to this class.
    • Language management (com.ibm.lang (Thread Properties)) - The ThreadProperties and ThreadPropertyMap public classes have no known alternatives.
    • Bidirectional support (com.ibm.bidiTools) - Some bidirectional support is available in the java.awt and java.awt.font packages. More information is provided in the tutorial Working with Bidirectional Text.
    • Blocked connector interrupts (com.ibm.jvm (InterrruptibleThread)) - The InterruptibleContext interface and InterruptibleIOContext, InterruptibleLockContext, and InterruptibleThread public classes have no known alternatives.
  • The T2K font rendering engine is no longer included. OpenJDK uses the open source FreeType font rendering library instead.
  • The monotype Lucida fonts are no longer included and no direct replacement exists.
  • Starting from version 11, fonts are no longer bundled with the SDK. Semeru now relies on system-installed WorldType fonts. The latest version of WorldType fonts is found as UNIX files (Hierarchical File System (HFS) or z/OS® File System (zFS) files) in this location:
    /usr/lpp/fonts/worldtype
    For more information on font support, see Semeru fonts support on z/OS.
  • The Ductus 2D renderer is no longer included. OpenJDK uses the Marlin renderer instead.
  • The Kodak Color Matching System library is no longer included. OpenJDK uses the Little Color Matching System (LCMS) open source library instead.
  • The Simple Network Management Protocol (SNMP) package is no longer included. Use Java Management Extensions (JMX) or SNMP4J as an alternative.
  • The JMX password file conf/management/jmxremote.password.template must be UTF-8 encoded. This encoding format requirement for the JMX password file in Semeru for z/OS, version 11 is a change from Java 8 on z/OS, where the JMX password file uses EBCDIC encoding.
  • The following code pages that were provided in IBM SDK, Java Technology Edition, Version 8 to support character encoding are no longer available in this release:
    • KZ-1048, PTCP154, x-IBM-udcJP, x-IBM1041, x-IBM1043, x-IBM1046S, x-IBM1047_LF, x-IBM1088, x-IBM1114, x-IBM1115, x-IBM1130, x-IBM1141_LF, x-IBM1164, x-IBM1351, x-IBM1362, x-IBM1363C, x-IBM1370, x-IBM1377x-IBM1380, x-IBM1382, x-IBM1385, x-IBM1386, x-IBM1390A, x-IBM1399A, x-IBM16684A, x-IBM29626, x-IBM300A, x-IBM301, x-IBM33722A, x-IBM33722C, x-IBM420S, x-IBM4933, x-IBM808, x-IBM835, x-IBM836, x-IBM837, x-IBM859, x-IBM954C, x-ISO-8859-6S, x-KOI8_RU, x-IBM864S, x-IBM897, x-IBM924_LF, x-IBM927, x-IBM930A, x-IBM939A, x-IBM941, x-IBM947, x-IBM951, x-mswin-936A, x-UTF_8J, x-windows-1256S
    • For a list of code pages that are available in OpenJDK 11, see Java 11 Internationalization guide: Supported Encodings. Only 172 character sets are shown, instead of 173. The missing character set is x-IBM29646C.
    • For details on using the ICU4J library for additional code page support, see Determining application compatibility: Code page support.
  • The -Dcom.ibm.dbgmalloc=true system property, which provided memory allocation diagnostic information for class library native code, is removed in this release. The equivalent environment variable, IBM_MALLOCTRACE=TRUE, is also removed. No replacement exists.
  • Support for RMI-IIOP APIs is removed from Java 11 as part of JEP 320. As a result, the default transport protocol for the Health Center agent (specified by the com.ibm.java.diagnostics.healthcenter.agent.transport configuration property) is changed to jrmp. For more information about Health Center configuration, see Health Center configuration properties in the IBM Monitoring and Diagnostic Tools - Health Center documentation.
  • The JGSS SPNEGO server attempts to contact the Kerberos Key Distribution Center (KDC) after migration from IBM SDK, Java Technology Edition, version 8 to Java 11. This is because the Kerberos login class Krb5LoginModule implementation has changed between the two versions. The IBM SDK for Java 8 uses com.ibm.security.auth.module.Krb5LoginModule whereas Java 11 uses the OpenJDK implementation, com.sun.security.auth.module.Krb5LoginModule. These two implementation classes have different configuration options, as summarized at JAAS options for Kerberos login.

    If the configuration for a Kerberos service that runs on Java 11 does not set the Krb5LoginModule option isInitiator to false, then the option defaults to true. When the option value is true, the Kerberos service attempts to log in as an initiator, meaning that it must contact the KDC to get the tickets it needs for requesting services. For more information, see this support article.

  • Default redirection support for JAVAIN, JAVAERR, and JAVAOUT DD names which were available in Java 8 is removed from Java 11 onwards and these DD names are not supported. The suggested alternative is to call the JZOS toolkit method com.ibm.jzos.ZUtil.redirectStandardStreams() during the initialization phase of your application to redirect to DD names STDIN, STDOUT, or STDERR. For more information, see ZUtil class documentation.
  • Start of changes for 11.0.14.1Support is added for using 31-bit native C or C++ code with the 64-bit Java VM. This feature was available in IBM SDK, Java Technology Edition, version 8 but was not available in the first release of version 11. The following paths are changed compared to version 8:
    • The JNI header file directory is changed from $JAVA_HOME/include31 to $JAVA_HOME/include/jni31.
    • The libjvm31.x sidedeck file directory is changed from $JAVA_HOME/lib/s390x/j9vm to $JAVA_HOME/lib/j9vm.
    End of changes for 11.0.14.1
  • Start of changes for 11.0.14.1Time zone data in the OpenJDK COMPAT locale provider is no longer overridden by IBM time zone data. Currently, the OpenJDK data does not include time zone name translations for the following locales, which did exist in the IBM data: ca, cs, hu, pl, ru, sk, sl, tr, and zh (the OpenJDK data does include translated time zone names for the zh_CN, zh_HK, and zh_TW locales). Minor differences in the time zone data might also exist compared with the previous release. You can use the java.locale.providers system property to specify the locale provider to use; the default value is CLDR, COMPAT. End of changes for 11.0.14.1
  • Start of changes for 11.0.15.0The OpenJCEPlus provider now supports the HMAC-SHA3 and SHA3 algorithms. These algorithms were supported by the IBMJCE provider in IBM SDK, Java Technology Edition, version 8 but were not supported by the OpenJCEPlus provider in the earlier releases of version 11.End of changes for 11.0.15.0
  • Start of changes for 11.0.15.0The IBMJCECCA provider, IBMJCEHYBRID provider, and JAAS z/OS extensions are now added. These security providers were available in version 8 but were not available in the earlier releases of version 11.End of changes for 11.0.15.0
  • Start of changes for 11.0.15.0The IBMZSecurity provider is added to provide the JCERACFKS keystore implementation that was provided by the IBMJCE provider in version 8 (other keystore types are implemented by the SUN and SunJCE providers). The following changes apply:
    Table 1. Provider-functional differences across releases
    Function Version 8 Version 11
    Key and certificate management Use the keytool utility in the IBMJCE provider. Use the zseckeytool utility in the IBMZSecurity provider.
    RACF® key ring value Specify by using safkeyring in the IBMJCE provider. Specify by using safkeyringjce in the IBMZSecurity provider.
    Class to handle the RACF key ring Specify the class by using the option -J-Djava.protocol.handler.pkgs in the keytool command in the IBMJCE provider. This option is removed from zseckeytool utility, and is no longer necessary in the IBMZSecurity provider.
    RACF keystore function usage RACF keystore function is enabled by default because the IBMJCE provider is in the default security provider list. To use the RACF keystore function, you must enable it by adding the IBMZSecurity provider to the default security provider list. For more information, see section Enabling the IBMZSecurity provider in IBMZSecurity topic.
    End of changes for 11.0.15.0
  • Start of changes for 11.0.16.0The SunPKCS11 provider is added to provide the PKCS#11 capability that was provided by the IBMPKCS11Impl component in version 8. Certain features that were available in IBMPKCS11Impl are not available in SunPKCS11. For more information, see PKCS#11 provider differences.End of changes for 11.0.16.0
  • Start of changes for 11.0.17.0The IBMZSecurity provider is added to the default security provider list, so it is now enabled by default. For more information, see Security guide.End of changes for 11.0.17.0
  • Start of changes for 11.0.20.1The zEDC (zEnterprise® Data Compression) Express adapter and the Integrated Accelerator for zEDC solution for z15® or later, which was supported in the IBM SDK, Java Technology Edition, version 8 but was not available in the previous releases of version 11, is now supported. For more information, see zEnterprise Data Compression.End of changes for 11.0.20.1
  • In contrast to IBM Java 8, Semeru SDKs contain an intentional correction of what processing is dispatched to IBM z Integrated Information Processor (zIIP) that can cause an increment in general central processor (CP) usage for some specific workloads. The change is working as designed and corrects a situation in Java 8 where some processing was dispatched to zIIP when it was not zIIP eligible.
These changes might affect the compatibility of applications with this release. For more information about these changes and how to determine whether your applications have compatibility issues, see Version compatibility.
Changes from the Eclipse OpenJ9 project
In 2017, IBM contributed the J9 virtual machine to the Eclipse Foundation, where it is now known as the Eclipse OpenJ9 VM. Although this VM is a component of IBM SDK, Java Technology Edition, Version 8, the following differences apply to IBM Semeru Runtime Certified Edition for z/OS, 11:
  • Class data sharing is enabled by default only for bootstrap classes, which is the equivalent of specifying -Xshareclasses:bootClassesOnly,nonFatal,silent on the command line.
  • The default maximum heap size is changed to be 25% of the available memory with a maximum of 25 GB. Where there is 2 GB or less of physical memory, the value set is 50% of available memory with a minimum value of 16 MB and a maximum value of 512 MB.
  • The amount of heap memory that can be used for direct byte buffers is set to 87.5% (seven eighths) of the maximum heap size.
  • The count field is removed from String, which means that substring() with a beginIndex value of zero can no longer be shared. If performance is significantly degraded because char[] data is now being copied, try reimplementing the code to avoid copying the String data.
  • A 1 G char[] or larger StringBuffer and StringBuilder immediately grows to the maximum size in this release, rather than growing to the size required to accommodate the String that is being added.
  • The trace formatter utility is run in a different way. For more information, see Trace formatter in the OpenJ9 user documentation.
  • The -Xsyslog command replaces the operations run by the -Xlog command in IBM SDK, Java Technology Edition, Version 8. For compatibility with the reference implementation, a new -Xlog command-line option is introduced that runs a subset of HotSpot -Xlog operations.
  • OpenJ9 adds support for JEP 331, which provides a mechanism for sampling Java heap allocations with a low overhead through the JVM Tool Interface (JVMTI). For more information about the limitations, see Support for low-overhead heap profiling.
  • Several new tools are introduced for compatibility with the reference implementation, including jcmd, jmap, jps, jstack, and jstat. These tools are OpenJ9 implementations and might differ in specific ways. In particular, these tools rely on the Attach API. To use these tools on z/OS systems, you must enable the Attach API. Follow the links provided for more information.
  • The dump extractor tool, jextract, is replaced by the jpackcore tool.
  • Some shared libraries that used to be found in the /bin or /bin/j9vm directories are now located in the /lib directory. For applications that call JNI or JNI invocation APIs, the directory locations of libjvm.so and the libjvm.x DLL sidedeck file are updated to improve consistency with the reference implementation. The library search path (LD_LIBRARY_PATH or LIBPATH) must be updated to reference lib/j9vm or lib/server directories.
  • The -Xzero option was deprecated in Version 7 Release 1 and is removed from Version 11.
Changes from Oracle
Oracle provides documentation about migrating from earlier releases of Java. However, this information includes content that is not available in the IBM SDK, for example, changes related to the HotSpot VM. This section summarizes the changes that apply to the IBM SDK. For more information about these items, follow the links or read the Migrating from JDK 8 to later JDK releases documentation from Oracle.
  • In accordance with Oracle JEP 320, Java EE and CORBA technologies were deprecated in Java SE 9 and removed in Java 11:
    • java.xml.ws (JAX-WS, plus the related technologies SAAJ and Web Services Metadata)
    • java.xml.bind (JAXB)
    • java.activation (JAF)
    • java.xml.ws.annotation (Common Annotations)
    • java.corba (CORBA)
    • java.transaction (JTA)
    • java.se.ee (Aggregator module for the six modules listed previously)
    • jdk.xml.ws (Tools for JAX-WS)
    • jdk.xml.bind (Tools for JAXB)
    The JEP describes how you can access alternative solutions.
  • In accordance with Oracle JEP 240, the JVMTI hprof agent is removed.
  • Java deployment technologies (Java plug-in, Applet API and Applet View, and Java WebStart) were deprecated in Java SE 9 and 10, and are removed in Java SE 11. This change is due to the lack of support in modern browsers for Java plug-ins, and the continuing trend for application developers to include a JRE with their applications, which can now be achieved by using the jlink tool that was introduced in Java SE 9. For more information, see Oracle Java SE Support Roadmap.
  • In accordance with Oracle JEP 162, the following methods were deprecated in Java SE 8, and removed in this release:
    • java.util.logging.LogManager.addPropertyChangeListener (Consider coding the global LogManager to detect changes to the logging configuration by overriding the readConfiguration method)
    • java.util.logging.LogManager.removePropertyChangeListener (Consider coding the global LogManager to detect changes to the logging configuration by overriding the readConfiguration method)
    • java.util.jar.Pack200.Packer.addPropertyChangeListener (To monitor the progress of the packer, poll the value of the PROGRESS property instead)
    • java.util.jar.Pack200.Packer.removePropertyChangeListener
    • java.util.jar.Pack200.Unpacker.addPropertyChangeListener (To monitor the progress of the unpacker, poll the value of the PROGRESS property instead)
    • java.util.jar.Pack200.Unpacker.removePropertyChangeListener
  • The sun.misc.BASE64Encoder and sun.misc.BASE64Decoder APIs were deprecated in Java SE 8 and removed in Java SE 9. Use the java.util.Base64 class instead. Note that other sun.misc and sun.reflect APIs are also planned for removal in future releases.
  • The native header generation tool (javah) is superseded by functionality in the Java compiler (javac).
  • The encoding conversion tool, native2ascii, is removed because Java 9 and later releases support UTF-8 based properties resource bundles.
For a full list of methods that are deprecated and removed, see Removed APIs, Tools, and Components.
Other notable changes from Oracle
  • In accordance with Oracle JEP 252, the Unicode Consortium's Common Locale Data Repository (CLDR) data is enabled as the default locale data.
  • The Java version-string format is changed. If your application relies on identifying the format of the old string, you must update your code. For more information, see Version String Format.
For more information about JDK changes for each new release of Java, see the following documents, ignoring any changes for the HotSpot VM: For VM changes since version 8, see the earlier section: Changes from the Eclipse OpenJ9 project.

If you are migrating from a release before Version 8, read the Migrating from earlier releases topic for Version 8.