Migrating applications to new Java versions

It is important to review differences between Java versions when migrating applications.

Applications must be modified if they use APIs that are removed in later versions of Java.

Available versions

  • 6.3 IBM® Semeru Runtime® Certified Edition for z/OS®, Version 17 and Version 21
  • 6.16.2 IBM Semeru Runtime Certified Edition for z/OS, Version 11, Version 17 and Version 21
  • IBM 64-bit SDK for z/OS, Java™ Technology Edition, Version 8

For more information, see Java runtime environments.

Benefits of moving to a new Java version

The following are some of the benefits from working with the most recent Java version:
  • Gain advantage from new API.
  • Stay up to date with security fixes.
  • Remain current with performance improvements.
  • Benefit from improved interoperability with distributed platforms.

Check your programs for deprecated APIs

The need to make changes when you move to a later version depends on whether your program uses APIs which are removed in later versions of Java. For more information, see,

Check your Java programs for compatibility issues between the supported IBM SDK for z/OS and previous versions. Code that was compiled with an older version of Java continues to run unless it uses APIs that are removed in the newer version of Java or CICS. If code does use APIs that are removed, make any changes necessary to enable your programs to run with the supported versions.

In addition to Java APIs, check your programs for deprecated or removed CICS JCICS APIs. For more information, see Upgrading the Java environment.

File encoding and UTF-8 as default charset

Java 21 Applies to Java 21.

In Java 21, the default character set for standard Java APIs is UTF-8, except for the console input and output encoding. Earlier versions of Java use an EBCDIC default character set. Processing of EBCDIC-based data is common in CICS Java applications so this change is significant.

Applications that were designed and tested for use with earlier versions of Java are likely to behave differently with Java 21. Check your Java programs to make sure that they do not assume that the default encoding is EBCDIC.

Applications deployed to Liberty are not affected since Liberty is only supported when it is running under a JVM with the UTF-8 or ISO-8859-1 character encoding in CICS.

JCICS APIs that use String objects automatically handle code page conversions. Update Java applications to use String-based JCICS methods rather than older JCICS methods that interact with byte[] data.

Where application code converts Java byte[] data to or from String objects, you must specify the correct encoding explicitly. Take particular care with API calls that use the default character set, such as:
  • Calls to String.getBytes().
  • InputStreamReader, FileReader, OutputStreamWriter, FileWriter, and PrintStream APIs of the java.io package.
  • Formatter and Scanner APIs of the java.util package.
  • URLEncoder, and URLDecoder APIs of the java.net package.

Setting -Dfile.encoding=COMPAT in the JVM profile reverts to Java 17 behavior, where native encoding is determined based on locale. This option should be used with caution because Java software libraries are likely to assume UTF-8 encoding everywhere in the future.

For more information, file.encoding property values, and auto-conversion of input files, see File encoding and UTF-8 as default charset in the IBM Semeru Runtime Certified Edition for z/OS documentation.