Semeru Runtimes migration guide

Changes resulting from IBM deprecations and removals

If you are migrating from IBM SDK, Java Technology Edition, version 8 you should be aware of the following significant changes:

• The IBM implementation of XML is replaced with the OpenJDK implementation of XML. Note that some Oracle XML modules, notably JAX-WS and JAXB, were deprecated in Java SE 9 and removed in Java SE 11.
• The IBM security implementation is replaced with the OpenJDK security implementation.
• 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 SE 11.
• Support for the following data compression devices will change to use the OpenJDK method of using system zlib for data compression.
  • Field Programmable Gate Array (FPGA) Accelerator Adapter (AIX and Linux on IBM Power systems). On AIX systems that contain the Nest accelerator (NX) co-processor, the zlibNX library is automatically used instead of zlib, if it is installed.
  • zEDC (zEnterprise® Data Compression) Express® feature: For more information about using this feature on IBM Z® and LinuxONE hardware, see Data compression with the Integrated Accelerator for zEDC.
• 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 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 Oracle 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.
  • RDMA (com.ibm.net.rdma): The jVerbs library is removed.
• 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. There is no direct replacement.
• The Ductus 2D renderer is no longer included. OpenJDK uses the Marlin renderer instead.
• The Kodac 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 native Windows DirectSound drivers are no longer included. Use the Microsoft sound drivers provided with the operating system.
• The HealthCenter agent that is available in earlier releases is no longer included.
• The following codepages that were provided in IBM SDK, Java Technology Edition, Version 8 to support character encodings are no longer available in this release:
  • hp-roman8, IBM00924, IBM274, ISO-8859-10, ISO-8859-14, KZ-1048, PTCP154, x-COMPOUND_TEXT, x-IBM-udcJP, x-IBM1027, x-IBM1041, x-IBM1043, x-IBM1046S, x-IBM1047_LF, x-IBM1088, x-IBM1114, x-IBM1115, x-IBM1130, x-IBM1141_LF, x-IBM1153, x-IBM1164, x-IBM1165, x-IBM1351, x-IBM1362, x-IBM1363, x-IBM1363C, x-IBM1370, x-IBM1371, x-IBM1377, x-IBM1379, x-IBM1380, x-IBM1382, x-IBM1385, x-IBM1386, x-IBM1388, x-IBM1390, x-IBM1390A, x-IBM1399, x-IBM1399A, x-IBM16684, x-IBM16684A, x-IBM29626, x-IBM300A, x-IBM301, x-IBM33722A, x-IBM33722C, x-IBM420S, x-IBM4933, x-IBM720, x-IBM808, x-IBM835, x-IBM836, x-IBM837, x-IBM859, x-IBM864S, x-IBM867, x-IBM897, x-IBM924_LF, x-IBM927, x-IBM930A, x-IBM939A, x-IBM941, x-IBM947, x-IBM951, x-IBM954, x-IBM954C, x-IBM971, x-ISO-8859-6S, x-KOI8_RU, x-KSC5601, x-mswin-936A, x-UTF_8J, x-windows-1256S
  • For a list of codepages that are available in OpenJDK 11, see Java 11 Internationalization guide: Supported Encodings. Note that only 172 character sets are shown, instead of 173. The missing character set is x-IBM29646C.
• The IBM system property ibm.swapLF, which handles character conversion between Line Feed (LF U+000A) and Next Line (NEL U+0085) characters in the IBM EBCDIC character set for Java, is no longer available in this release. An equivalent system property that works on the OpenJDK EBCDIC charsets is not available.
• 32-bit binary packages are no longer available for download. If your application uses 32-bit JNI libraries, you must port them to 64-bit JNI libraries. For more information, see Porting Java applications to 64-bit systems.

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.

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 version 11 of the IBM Semeru Runtimes:

• OpenJ9 supports OpenSSL for improved cryptographic performance when compared to the in-built OpenJDK Java cryptographic implementation.
• 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. However, if your application is running in a container, class data sharing is not enabled, which is the same behaviour as version 8.
• In version 8, the default shared classes cache directory is always /tmp/javasharedresources. In OpenJ9 on operating systems other than Windows, the default directory is in the user's home directory unless you also specify the groupAccess suboption.
• The default size of the shared classes cache is 300 MB, with a "soft" maximum limit for the initial size of the cache (-Xscmx) of 64 MB. For more information, see -Xshareclasses command in the OpenJ9 user documentation.
• 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 approximately 85% 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 re-implementing the code to avoid copying the String data.
• A 1 G char[] or larger StringBuffer and StringBuilder immediately grows to the maximum possible size in this release, rather than growing to the size required to accommodate the String that is being added.
• The trace formatter utility is launched 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 via the JVM Tool Interface (JVMTI). To read about the limitations, see Support for low-overhead heap profiling.
• A number of 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. Follow the links provided for more information.

More information about the changes from Eclipse OpenJ9 can be found in the OpenJ9 release topics on the project website.

Changes from Oracle

Oracle provide documentation on 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.

The following changes result from Oracle deprecations and removals:

• In accordance with Oracle JEP 320, Java EE and CORBA technologies were deprecated in Java SE 9 and removed in Java SE 11.
• In accordance with Oracle JEP 240, the JVMTI hprof agent is removed.
• Java deployment technologies (Java Plugin, 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 functionality 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 Java SE 9:
  • 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 supserseded 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.

Further information about JDK changes for each new release of Java can be found in the following documents:

• Release Notes for JDK 9 and JDK 9 Update Releases
• JDK 10 Release Notes
• Consolidated JDK 11 Release Notes

Note: These release notes contain changes for the HotSpot VM, which should be ignored. For VM changes since version 8, see Changes from the Eclipse OpenJ9 project.

Changes imposed by the Java module system

The components of the SDK are rewritten to use the Java module system, which introduces a number of changes to the structure, content, and operation of the Java runtime. The following changes are imposed by the Java module system, which was introduced in Java SE 9:

• Internal APIs are restricted
  • Although internal APIs are private and not intended for use, many were accessible to applications. By default in Java 11, access to internal APIs is allowed at run time for packages that were present in Java 8, although a warning is printed the first time an access occurs. However, most internal APIs are not accessible at compile time.
  • As a temporary workaround you can use the –add-exports option on the command line to break encapsulation. For accessing an internal API by using reflection, use the --add-opens option.
• The structure of the runtime image is changed.
  • Modularity removes the concept of a developer kit and a Java Runtime Environment as distinct entities. A modular runtime image is simply built to contain the components that are needed, which might include a subset of tools. One consequence of this design is the removal of the /jre directory. Issues are likely to arise if existing applications depend on the current structure of runtime images.
  • Configuration files, such as java.security and logging.properties, are now located in a new directory, /conf, and its subdirectories.
  • For applications that call JNI or JNI invocation APIs, the directory locations of libjvm.so are updated to improve consistency with OpenJDK 11. The library search path (LD_LIBRARY_PATH or LIBPATH) should be updated to reference lib/j9vm or lib/server directories.
• The endorsed-standards override mechanism is removed.
  • This mechanism, which involves placing JAR files on the jre/lib/endorsed path, is used in Java 8 to implement newer versions of standards that are maintained outside of the Java Community Process. Endorsed standards will be supported only in a modular form with the new concept of upgradeable modules. The java.endorsed.dirs system property is no longer defined. Code that assumes a non-null value for this system property might fail.
• The extensions mechanism is removed.
  • The extensions mechanism can be used to install additional APIs into a runtime image, by placing jar files into an extensions directory, lib/ext. The ext directory no longer exists in a modular image and applications that rely on this mechanism will fail. The java.ext.dir system property is no longer defined. Code that assumes a non-null value for this system property might fail.
• The rt.jar, tools.jar, and dt.jar files are removed.
  • JAR files are replaced by modules in the new system. Code that depends on finding these JAR files will fail. As an alternative, consider using the jrt: file system, intended for modular class files, as described in JEP 220, New URI scheme for naming stored modules, classes, and resources, item (3). More information is also available in the Oracle migration documentation.
• The bootstrap class path option is removed.
  • The default bootstrap class path can no longer be overridden, nor can you prepend the path with files and directories. If you attempt to use this option at runtime, the option is ignored. Note that -Xbootclasspath/a continues to be supported for appending to the end of the bootstrap class path.
• New class loader implementations:
  • The application class loader is now an instance of an internal class.
  • The extension class loader is now renamed to the platform class loader. It is also an instance of an internal class.

Determining application compatibility

This release contains significant changes from previous releases, which might cause compatibility issues in the following areas:

Internal APIs

For a methodical approach to identifying whether your application has a dependency on any internal APIs, use the jdeps tool.

XML support

For assistance with migrating to the OpenJDK XML implementation, read Migrating from the IBM XML implementation.

Codepage support

Many codepages that were provided with IBM SDK, Java Technology Edition, Version 8 to support character encodings are no longer available in this release. If your application relies on one of these codepages, switch to an ICU4J Unicode-based charset instead.

To use the ICU4J charset, download and install the ICU4J and ICU4J charset jars. For more information, see How to Install and Build. Then, create an instance of the charset as shown in the following example –
Charset cs = Charset.forName("IBM-5123");
For more information, see ICU API documentation. 

Major differences between available character sets are detailed in the following list:

• GBK character sets: The IBM GBK character set in Java 8 is based on GB18030. However, the OpenJDK Java 11 GBK character set is based on Unicode 2.0 based encoding, which is most similar to the IBM x-mswin-936A character set.
• Bidirectional support: IBM SDK, Java Technology Edition V8 contained bidirectional support, as described in the IBM documentation. The bidirectional layout transformations that are enabled by the -DJAVABIDI command line system property in Java 8 are no longer available (Codepages: IBM420, IBM424, x-IBM856, IBM862, IBM864, IBM-867, x-IBM1046, windows-1255, windows-1256, ISO-8859-6, ISO-8859-8, x-MacArabic, x-MacHebrew, UTF-8).
• Arabic character sets: Although some bidirectional support is available in the Java 11 OpenJDK character sets, the Arabic character sets do not support Arabic deshape.

Security

This release contains the OpenJDK security implementation, instead of the IBM security implementation. Differences between these implementations might require code changes to your applications.

For more information about the security implications of migrating to version 11 of the IBM Semeru Runtimes, see the Security migration guide.