Compatibility Guide for JDK 9
Compatibility is a complex issue. This document discusses three types of potential incompatibilities relating to a release of the Java platform:
- Source: Source compatibility concerns translating Java source code into class files including whether or not code still compiles at all.
- Binary: Binary compatibility is defined in The Java Language Specification as: 'A change to a type is binary compatible with (equivalently, does not break binary compatibility with) pre-existing binaries if pre-existing binaries that previously linked without error will continue to link without error.'
- Behavioral: Behavioral compatibility includes the semantics of the code that is executed at runtime.
A source incompatibility arises from a change in the Java language; a binary incompatibility arises from a change in the public signatures of the Java SE API; a behavioral incompatibility arises from a change in the implementation of the Java SE API.
Source incompatibilities are very very rare; binary incompatibilities are very rare; behavioral incompatibilities are rare. That is, all types are unusual, but some are more unusual than others, and the amount of preparation/advertising they receive will be commensurate.
Examples drawn from the JDK 9 Migration Guide include:
- A source incompatibility is the disallowance of underscore as an identifier in Java programs.
- A binary incompatibility is the removal of methods in java.util.logging and java.util.jar.
- A behavioral incompatibility is the use of CLDR locale data by default.
For more information, see Kinds of Compatibility, a section in the OpenJDK Developer's Guide.
The following compatibility documents track incompatibility between adjacent Java versions. For example, this compatibility page reports only Java SE 9 incompatibilities with Java SE 8, and not with previous versions. To examine Java SE 9 incompatibilities with earlier Java versions, you must trace incompatibilities through the listed files, in order.
Binary Compatibility
Java SE 9 is binary-compatible with Java SE 8 except for the incompatibilities listed below. Except for the noted incompatibilities, class files built with the Java SE 8 compiler will run correctly in Java SE 9. Class files built with the Java SE 9 compiler will not run on earlier releases of Java SE.
Source Compatibility
Java SE 9 includes new language features and platform APIs. If these are used in a source file, that source file cannot be compiled on an earlier version of the Java platform.
In general, the source compatibility policy is to avoid introducing source code incompatibilities. However, implementation of some Java SE 9 features required changes that could cause code that compiled with Java SE 8 to fail to compile with Java SE 9.
Deprecated APIs are interfaces that are supported only for compatibility with previous releases. The javac compiler generates a warning message whenever one of these is used, unless the -nowarn command-line option is used. It is recommended that programs be modified to eliminate the use of deprecated APIs.
Some APIs in the sun.* packages have changed. These APIs are not intended for use by developers. Developers importing from sun.* packages do so at their own risk. For more details, see Why Developers Should Not Write Programs That Call 'sun' Packages.
Behavioral Compatibility
In its simplest form, behavioral compatibility means that with the same inputs a program performs the same (or an equivalent) operation under different versions of libraries or the platform. There are aspects of the platform's behavior that are intentionally unspecified and the underlying implementation may change in a platform release. For this reason, it is recommended that code is written in such a way so that it does not depend on unspecified behavior: In this scenario, the problem is not an incompatibility in the platform, is it a bug in the code.
Java Class Files
The Java class file format has been updated for the Java SE 8 release.
The class file version for Java SE 9 is 52.0 as per the JVM Specification. Version 52.0 class files produced by a Java SE 9 compiler cannot be used in earlier releases of Java SE.
The following document has information on changes to the Java Language Specification (JLS) and the Java VM Specification (JVMS).
Scripting
The Rhino javascript engine has been replaced with the Nashorn javascript engine. See the Rhino to Nashorn migration page.Incompatibilities between Java SE 9 and Java SE 8
Java SE 9 is strongly compatible with previous versions of the Java platform. Almost all existing programs should run on Java SE 9 without modification. However, there are some minor potential incompatibilities in the JRE and JDK that involve rare circumstances and "corner cases" that are documented here for completeness.
This section describes Java SE 9 incompatibilities in the Java Language, the JVM, or the Java SE API.
Note that some APIs have been deprecated in this release and some features have been removed entirely. While these are incompatibilities, they have been called out in separate lists. For more information, see Deprecated APIs and Features Removed from JDK 8.
Area: JVM
Synopsis
Default methods in interfaces do not cause eager interface initialization
Description
The presence of method bodies in interfaces (due to default methods and static methods) means that interfaces may have to be initialized prior to their static fields being accessed. The Java SE 8 Editions of the Java Language Specification and JVM Specification did not account for this, with the result that JDK 8 exhibited unspecified behavior. (During class initialization, any superinterface declaring or inheriting a default method was eagerly initialized). The correct behavior is to initialize an interface eagerly if it declares a default method, and otherwise lazily when its static field is accessed or its static method is invoked (whether by an invoke* bytecode, or via method handle invocation, or via Core Reflection).
Nature of Incompatibility
behavioral
Bug
Incompatibilities between JDK 9 and JDK 8
This section describes JDK 8 Incompatibilities in javac, in HotSpot, or in Java SE API.
Note that some APIs have been deprecated in this release and some features have been removed entirely. While these are incompatibilities, they have been called out in separate lists. For more information, see Deprecated APIs and Features Removed from JDK 8.
Area: JVM
Synopsis
Support default and static interface methods in JDI
Description
Java SE 8 Language Specification has introduced static and default methods for interfaces. Both JDI specification and implementation have now been updated to allow such invocations. In JDI, the "com.sun.jdi.InterfaceType" class now contains an additional method "Value invokeMethod(ThreadReference thread, Method method, List<? extends Value> arguments, int options)".
Nature of Incompatibility
behavioral
RFE
Features Removed from Java SE 9
Area: API / java.lang
Synopsis
Thread.stop(Throwable) has been disabled
Description
The Thread.stop method has been deprecated since release 1.2. This method now throws an UnsupportedOperationException.
Features Removed from JDK 9
Area: Install
Synopsis
Builds with automatic update turned off are no longer provided.
Description
To disable the automatic updating of the JRE, disable automatic updates and set the deployment.expiration.check.enabled property to false in the deployment configuration properties file. To disable automatic updates, remove the check from Check for Updates Automatically in the Update tab of the Java Control Panel. See Deployment Configuration File and Properties for information about the deployment.expiration.check.enabled property.
Deprecated APIs
Area: Core Libs / java.lang:class_loading
Deprecated Feature
The endorsed-standards override mechanism allows implementations of newer versions of standards maintained outside of the Java Community Process, or of standalone APIs that are part of the Java SE Platform yet continue to evolve independently, to be installed into a run-time image.
A modular image is composed of modules rather than jar files. Going forward we expect to support endorsed standards and standalone APIs in modular form only, via the concept of upgradeable modules.
This feature is deprecated in JDK 8u40. This deprecation is made in preparation for modules in a future release of the Java SE Platform.
RFE