Pre-General Availability: 2017-05-24

Java Platform, Standard Edition

Oracle JDK 9 Migration Guide

Release 9

E82965_03

June 2017

Migrating to Oracle JDK 9

The purpose of this guide is to help you identify potential issues and give you suggestions on how to proceed as you migrate your existing Java application to JDK 9.

Every new Java SE release introduces some binary, source and behavioral incompatibilities with previous releases. The modularization of the Java SE Platform brings many benefits but also many changes. Code that uses only official Java SE Platform APIs and supported JDK-specific APIs should continue to work without change. Code that uses certain features or JDK-internal APIs may not run or may give different results.

To migrate your application, start by following the steps listed in Prepare for Migration.

Finally, once your application is running successfully on JDK 9, review Looking Forward, which will help you avoid problems with future releases.

This guide focuses on changes required to make your code run on JDK 9. For a comprehensive list of all of the new features of JDK 9, see Java Platform, Standard Edition What's New in JDK 9.

Get the JDK 9 Early Access Build

Download and install the latest Oracle JDK 9 early access release. Early access builds are only meant to be used for testing and debugging, not in production environments.

Run Your Program Before Recompiling

Try running your application on the Oracle JDK 9 early access version and see what happens. If your program uses only standard Java SE APIs, you may find that it runs without any modification.

Note:

Migrating is an iterative process. You will probably find it best to try running your program (this task) first, then complete these three tasks more or less in parallel:

When you run your application, look for warnings from the JVM about unrecognized VM options. If the VM fails to start, check for removed options, as VM flags that were deprecated in JDK 8 have been removed in JDK 9. See Removed GC Options.

If your application launches successfully, look carefully at your tests and make sure the behavior is the same as on JDK 8. For example, a few early adopters have noticed that their dates and currencies are formatted differently. See Use CLDR Locale Data by Default.

Even if your program appears to run successfully, you need to complete the rest of the steps in this guide, plus review the list of issues.

Update Third-Party Libraries

For every tool and third-party library that you use, you may need to have an updated version that supports JDK 9.

Check your third-party libraries and tools vendors websites for a version of each library or tool that is designed to work on Java 9. If one exists, download and install the new version.

If you use an IDE to develop your applications, it can help to migrate existing code. The NetBeans, Eclipse, and IntelliJ IDEs all have early access versions available that include JDK 9 support.

You can see the status of the testing of many Free Open Source Software (FOSS)  projects with OpenJDK builds at Quality Outreach on the OpenJDK wiki.

Compile Your Application

Compile your code using the JDK 9 compiler and check for warnings and errors.

Compilation may fail for a number of reasons specific to JDK 9.

  • Most of the JDK’s internal APIs have been made inaccessible by default. You may get compilation errors, or, at run time, IllegalAccessErrors, that indicate that your application or its libraries are dependent on internal APIs .

    To identify the dependencies, run the Java Dependency Analysis tool. See Run jdeps on Your Code. If possible, update your code to use the supported replacement APIs.

    Check compilation warnings for any clues. You may see more deprecation warnings than previously. If you see deprecation with removal warnings, you should address those to avoid future problems.

  • If you use the underscore character ("_") as a one-character identifier in source code, it won’t compile in JDK 9. Its use generates a warning in JDK 8, and an error in JDK 9.

    As an example, this code:

    static Object _ = new Object();
    

    generates the following error message from the compiler.

    MyClass.java:2: error: as of release 9, '_' is a keyword, and may not be used as a legal identifier.
    
  • If you use the -source and -target options with javac, check the values that you use. In JDK 9, javac uses a "one plus three back" policy of supporting -source and -target options.

    The supported -source/-target values are 9 (the default), 8, 7, and 6 (6 is deprecated, warning issued when used).

    In JDK 8, -source and -target values of 1.5/5 and earlier were deprecated and caused a warning to be generated. In JDK 9, those values cause an error.

    >javac -source 5 -target 5 Sample.java 
    warning: [options] bootstrap class path not set in conjunction with -source 1.5 
    error: Source option 1.5 is no longer supported. Use 1.6 or later. 
    error: Target option 1.5 is no longer supported. Use 1.6 or later.
    

    If possible, use the new --release flag instead of -source and -target. The --release N flag is conceptually a macro for

    -source N -target N -bootclasspath $PATH_TO_rt.jar_FOR_RELEASE_N
    

    The valid arguments for the --release flag follow the same policy as for -source and -target, one plus three back.

    javac can recognize and process class files of all previous JDKs, going all the way back to JDK 1.0.2 class files.

    See JEP 182: Policy for Retiring javac -source and -target Options.

Run jdeps on Your Code

Run the jdeps tool on your application to see what packages and classes your applications and libraries depend on. If you use internal APIs, jdepssuggests replacements to help you update your code.

To look for dependencies on internal JDK APIs, run jdeps with the -jdkinternals option. For example, if you run jdeps on a class that invokes sun.misc.BASE64Encoder, you will see:

>jdeps -jdkinternals Sample.class
Sample.class -> JDK removed internal API
   Sample  -> sun.misc.BASE64Encoder  JDK internal API (JDK removed internal API)

Warning: JDK internal APIs are unsupported and private to JDK implementation that are
subject to be removed or changed incompatibly and could break your application.
Please modify your code to eliminate dependency on any JDK internal APIs.
For the most recent update on JDK internal API replacements, please check:
https://wiki.openjdk.java.net/display/JDK8/Java+Dependency+Analysis+Tool

JDK Internal API                         Suggested Replacement
----------------                         ---------------------
sun.misc.BASE64Encoder                   Use java.util.Base64 @since 1.8

If you use Maven, there is a jdeps plugin available.

For jdeps syntax, see jdeps in the Java Platform, Standard Edition Tools Reference.

Keep in mind that jdeps is a static analysis tool, and static analysis of code does not tell you everything. If the code uses reflection to call an internal API, jdeps does not warn you. At runtime, you may get a java.lang.IllegalAccessException.

Break Encapsulation

You may find that you have to violate the access-control boundaries defined by the module system. For example, you may have to allow a module that your application depends on to access some of the unexported types of another module. JDK 9 allows you to break those boundaries while you wait for those other applications to migrate.

Some popular libraries and frameworks use the core reflection API to access internal JDK APIs. Because most internal APIs are strongly encapsulated in JDK 9, these components will need to be updated. If you are not able to get a version of a required library that already works on JDK 9, you can use the --add-opens or the --permit-illegal-access switch on the command line to allow reflective components to run.

If you see IllegalAccessException or InaccessibleObjectException messages, you could use the --add-opens runtime option, basing the arguments upon the information shown in the exception message.

However, if you have a large application that uses several reflective components, you would have to repeat this process many times. The result would be a long list of command-line options that you could record in a launch script or an @-file. In order to expedite the process, use the --permit-illegal-access option at run time.

There are three options that allow you to break encapsulation:
  • If you need to use an internal API that has been made inaccessible by default, use the --add-exports option.
  • If you have to allow code on the class path to do "deep reflection" to access non-public members, use the --add-opens option.
  • If you depend on a large application that uses several reflective components, use the --permit-illegal-access option rather than multiple --add-opens options.

These options may be combined. --permit-illegal-access generates warning messages, while the other two options do not.

If a component needs to be fixed, then you should contact its maintainers and ask them to stop using JDK-internal APIs.

--add-exports

If you need to use an internal API that has been made inaccessible by default, you can break encapsulation using the --add-exports command line option.

The syntax of the --add-exports is:
--add-exports <source-module>/<package>=<target-module>(,<target-module>)*
where <source-module> and <target-module> are module names and <package> is the name of a package.

--add-exports allows code in the target module to access types in the named package of the source module if the target module reads the source module.

If, for example, an application oldApp must use the unexported com.sun.jmx.remote.internal package of the java.management module, then the access it requires can be granted in this way:
--add-exports java.management/com.sun.jmx.remote.internal=oldApp
You can also break encapsulation with the JAR file manifest:
--add-exports:java.management/sun.management
As a special case, if the <target-module> is ALL-UNNAMED, then the source package will be exported to all unnamed modules, whether they exist initially or are created later on. For example, the option:
--add-exports java.management/sun.management=ALL-UNNAMED
allows code in all unnamed modules (code on the class path) to access the public members of public types in java.management/sun.management. If the code on the class path attempts to do "deep reflection" to access non-public members then it will fail.

Use the --add-exports option carefully. You can use it to gain access to an internal API of a library module, or even of the JDK itself, but you do so at your own risk: if that internal API changes or is removed, then your library or application will fail.

See also JEP 261.

--add-opens

If you need to allow code on the class path to do "deep reflection" to access non-public members, use the --add-opens runtime option.

Some libraries do deep reflection, meaning setAccessible(true), so they can access all members, including private ones. You can grant this access using --add-opens on the java command line. No warning messages are generated as a result of using this option.

The syntax for --add-opens is:
--add-opens module/package=target-module(,target-module)*
It allows module to open package to target-module, regardless of module declaration.
As a special case, if the <target-module> is ALL-UNNAMED, then the source package will be exported to all unnamed modules, whether they exist initially or are created later on. For example,
--add-opens java.management/sun.management=ALL-UNNAMED
allows all of the code on the class path to access non-public members of public types in java.management/sun.management.

--permit-illegal-access

If some of the third party libraries that you depend on still use core reflection APIs, and you can’t get an updated version, then use the --permit-illegal-access option so that you can continue to make your code work on JDK 9. This option is only supported in JDK 9.

--permit-illegal-access allows illegal access operations by code on the class path to members of types in any named module via the standard reflective APIs (java.lang.reflect and java.lang.invoke).

If you use --permit-illegal-access, the run-time system displays a warning on each illegal access operation.

Here are some examples of these messages, from running Jython:

>java --permit-illegal-access -jar jython-standalone-2.7.0.jar
WARNING: --permit-illegal-access will be removed in the next major release
WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/C:/Jython/jython2.7.0/jython-standalone-2.7.0.jar) to method sun.nio.ch.SelChImpl.getFD() (permitted by --permit-illegal-access)
WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/C:/Jython/jython2.7.0/jython-standalone-2.7.0.jar) to field sun.nio.ch.FileChannelImpl.fd (permitted by --permit-illegal-access)
WARNING: Illegal access by jnr.posix.JavaLibCHelper (file:/C:/Jython/jython2.7.0/jython-standalone-2.7.0.jar) to field java.io.FileDescriptor.fd (permitted by --permit-illegal-access)
...
Jython 2.7.0 (default:9987c746f838, Apr 29 2015, 02:25:11) 
[Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java9-ea
Type "help", "copyright", "credits" or "license" for more information.

--permit-illegal-access doesn’t permit illegal access operations by code in named modules to members of types in other named modules. For that, you must use the --add-opens or --add-exports options. Those options can be combined with --permit-illegal-access.

Changes to the Installed JDK/JRE Image

These are things you should know about the JDK and JRE.

New Version-String Scheme

JDK 9 provides a new simplified version-string format. If your code relies on the version-string format to distinguish major, minor, security, and patch update releases, you may need to update it.

The format of the new version-string is:

$MAJOR.$MINOR.$SECURITY.$PATCH

For example, under the old scheme, the Java 9u5 release would have the version string 1.9.0_5-b20.

Under the new scheme, the short version of the same release is 9.0.1, and the long version is 9.0.1+20.

This change impacts java -version and related system properties, java.runtime.version, java.vm.version, java.specification.version, and java.vm.specification.version.

A simple Java API to parse, validate, and compare version strings has been added. See java.lang.Runtime.

See Version String Format in the Java Platform, Standard Edition Installation Guide and JEP 223: New Version-String Scheme.

Changed JDK and JRE Layout

The layout of files in the installed JDK and JRE image has changed in JDK 9.

After you install JDK 9, if you look at the file system, you’ll notice that the directory layout is different from that of previous releases.

In the past there was always a separate JRE, which you could download if you wanted a runtime environment, but not the full suite of developer tools. It consisted of a jre directory which had a subset of the various runtime binaries, such as the java launcher and other runtime tools.

If you wanted to develop software, you would download the full JDK, which wrapped that same jre/ directory in a higher level jdk/ directory and added more tools and libraries. In previous releases, both the jre/ and jdk/ directories each had their own bin/ directories, resulting in duplicate binary files in the full JDK. In addition, the files that a user could edit and configure were scattered throughout the various directories. It wasn't clear exactly what files were intended to be tweaked by end users, and what files were internal to the JDK.

New Runtime Image Structure

In JDK 9, the JDK and JRE are two types of modular runtime images, where each contains the following directories:

  • bin: contains binary executables

  • conf: contains .properties, .policy, and other kinds of files intended to be edited by developers, deployers, and end users, which were formerly found in the lib directory or its subdirectories.

  • lib: contains dynamically linked libraries and the complete internal implementation of the JDK.

There are still separate JDK and JRE downloads, but you get the same directory structure regardless of the image that you download. The JDK image contains the extra tools, such as javac, and libraries that have historically been found in the JDK. There are no more jdk/ versus jre/ wrapper directories, and binaries (such as the java tool) are not duplicated.

See JEP 220: Modular Run-Time Images.

Removed rt.jar and tools.jar

Class and resource files previously stored in lib/rt.jar, lib/tools.jar, lib/dt.jar and various other internal jar files are stored in a more efficient format in implementation-specific files in the lib directory.

The removal of rt.jar and similar files leads to issues in these areas:

  • In JDK 9, ClassLoader::getSystemResource doesn’t return a URL pointing to a JAR file (since there are no JAR files). Instead it returns a valid URL.

    For example, when run on JDK 8 the code:

    ClassLoader.getSystemResource("java/lang/Class.class");

    returns a JAR URL of the form:

    jar:file:/usr/local/jdk8/jre/lib/rt.jar!/java/lang/Class.class

    which embeds a file URL to name the actual JAR file within the run-time image. The getContent method of that URL object can be used to retrieve the content of the class file, via the built-in protocol handler for the jar URL scheme. A modular image doesn’t contain any JAR files, so URLs of the above form make no sense.

  • The java.security.CodeSource API and security policy files use URLs to name the locations of code bases that are to be granted specific permissions. See Policy File Syntax in Java Platform, Standard Edition Security Developer's Guide. Components of the run-time system that require specific permissions are currently identified in the conf/security/java.policy file via file URLs.

  • IDEs and other development tools require the ability to enumerate the class and resource files stored in a runtime image, and to read their contents directly by opening and reading rt.jar and similar files. This is not possible with a modular image.

Removed Extension Mechanism

In previous releases, the extension mechanism made it possible for the runtime environment to find and load extension classes without specifically naming them on the class path.

In JDK 9, a more robust mechanism has been added to achieve the same result. Use upgradeable modules or put JARs on the classpath.

The javac compiler and java launcher will exit if the java.ext.dirs system property is set, or if the lib/ext directory exists. To additionally check the platform-specific system-wide directory, specify the -XX:+CheckEndorsedAndExtDirs command-line option. This will cause the same exit behavior to occur if the directory exists and is not empty. The extension class loader is retained in JDK 9 for compatibility reasons.

The following error means that your system is configured to use the extension mechanism:

<JAVA_HOME>/lib/ext exists, extensions mechanism no longer supported; Use -classpath instead.
.Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

You’ll see a similar error if the java.ext.dirs system property is set.

To fix this error, remove the ext/ directory or the java.ext.dirs system property.

If you need to use the extension classes, make sure the jar files are on the classpath.

See JEP 220: Modular Run-Time Images.

Removed Endorsed Standards Override Mechanism

The java.endorsed.dirs system property and the lib/endorsed directory are no longer present. The javac compiler and java launcher will exit if either are detected.

In JDK 9, a more robust mechanism has been added to achieve the same result. Use upgradeable modules or put JARs on the classpath.

This mechanism was mostly intended for application servers to override components used in the JDK. Packages to be updated would be placed into JAR files, and the system property java.endorsed.dirs would tell the Java runtime environment where to find them. If a value for this property was not specified, the default of $JAVA_HOME/lib/endorsed would be used.

In JDK 8, you can use the -XX:+CheckEndorsedAndExtDirs command-line argument to check for such directories anywhere on the system.

In JDK 9, the javac compiler and java launcher will exit if the java.endorsed.dirs system property is set, or if the lib/endorsed directory exists.

The following error means that your system is configured to use the endorsed standards override mechanism:

<JAVA_HOME>/lib/endorsed is not supported. Endorsed standards and standalone APIs
in modular form will be supported via the concept of upgradeable modules.
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

You’ll see a similar error if the java.endorsed.dirs system property is set.

To fix this error, remove the lib/endorsed directory, or unset the java.endorsed.dirs system property.

See JEP 220: Modular Run-Time Images.

Removed or Changed APIs

This section highlights APIs that have been made inaccessible, removed, or altered in their default behavior. You may encounter the issues described in this section when compiling or running your application.

Removed java.* APIs

The Java team is committed to backwards compatibility. If an application runs in JDK 8, then it will run on JDK 9 as long as it uses APIs that are supported and intended for external use.

These include:

  • JCP standard, java.*, javax.*
  • JDK-specific API, some com.sun.*, some jdk.*

Supported APIs can be removed from the JDK, but only with advance notice. Find out if your code is using deprecated APIs by running the static analysis tool jdeprscan.

The only java.* APIs that have been removed in JDK 9 are the previously deprecated methods from the java.util.logging.LogManager and java.util.jar.Pack200 packages:

java.util.logging.LogManager.addPropertyChangeListener
java.util.logging.LogManager.removePropertyChangeListener
java.util.jar.Pack200.Packer.addPropertyChangeListener
java.util.jar.Pack200.Packer.removePropertyChangeListener
java.util.jar.Pack200.Unpacker.addPropertyChangeListener
java.util.jar.Pack200.Unpacker.removePropertyChangeListener

See JEP 162: Prepare for Modularization.

Removal and Future Removal of sun.misc and sun.reflect APIs

JDK 9 makes most of the JDK's internal APIs inaccessible by default, but leaves a few widely-used internal APIs accessible until supported replacements exist for most or all of their functionality.

Unlike the previously described APIs, almost all of the sun.* APIs are unsupported, JDK-internal APIs, and may go away at any time.

A few sun.* APIs have been removed in JDK 9. Notably, sun.misc.BASE64Encoder and sun.misc.BASE64Decoder have been removed. Instead, use the supported java.util.Base64 class, which was added in JDK 8.

The APIs in sun.misc and sun.reflect packages that remain accessible in JDK 9 are:
  • sun.misc.{Signal,SignalHandler}.
  • sun.misc.Unsafe. The functionality of many of the methods in this class is now available via variable handles, see JEP 193: Variable Handles.
  • sun.reflect.Reflection::getCallerClass(int). Instead, use the stack-walking API, see JEP 259: Stack-Walking API.
  • sun.reflect.ReflectionFactory.newConstructorForSerialization.

These APIs are accessible by default at run time. They have been moved to the jdk.unsupported module, which is present in the JRE and JDK images. Modules that need these APIs must declare a dependency upon the jdk.unsupported module.

The remaining internal APIs in the sun.misc and sun.reflect packages have been moved, since they should not be accessible. See JEP 260: Encapsulate Most Internal APIs. If you need to use one of these internal APIs, you can break encapsulation using the --add-exports command line option described in JEP 261. This option should only be used as a temporary aid to migration.

java.awt.peer Not Accessible

The java.awt.peer and java.awt.dnd.peer packages are not accessible in JDK 9. The packages were never part of the Java SE API, despite being in the java.* namespace.

All methods in the Java SE API that refer to types defined in these packages have been removed from JDK 9. Code that calls a method which previously accepted or returned a type defined in these packages will no longer compile or run.

There are two common uses of the java.awt.peer classes. You should replace them as described below.
  • To see if a peer has been set yet:
    if (component.getPeer() != null) { .. }
    
    Replace with Component.isDisplayable() from the JDK 1.1 API:
    public boolean isDisplayable() {
            return getPeer() != null;
    
  • To test if a component is lightweight:
    if (component.getPeer() instanceof LightweightPeer) ..
    
    Replace with Component.isLightweight() from the JDK 1.2 API:
    public boolean isLightweight() {
            return getPeer() instanceof LightweightPeer;
    

Removed com.sun.image.codec.jpeg Package

The non-standard package com.sun.image.codec.jpeg has been removed. Use the Java Image I/O API instead.

com.sun.image.codec.jpeg was added in JDK 1.2 as a non-standard way of controlling the loading and saving of JPEG format image files. It has never been part of the platform specification.

In JDK 1.4, the Java Image I/O API was added as a standard API, residing in the javax.imageio package. It provides a standard mechanism for controlling the loading and saving of sampled image formats and requires all compliant Java SE implementations to support JPEG based on the Image I/O specification.

Removed HTTP Proxy System Properties from RMI

The RMI HTTP proxy implementation and RMI/JRMP HTTP tunneling implementation have been removed. This mechanism was deprecated in JDK 8.

The following system properties have been removed in JDK 9:

  • sun.rmi.transport.proxy.logLevel
  • sun.rmi.transport.tcp.proxy
  • sun.rmi.transport.proxy.connectTimeout
  • sun.rmi.transport.proxy.eagerHttpFallback
  • java.rmi.server.disableHttp

Removed Tools Support for Compact Profiles

In JDK 9, you can choose to build and run your application against any subset of the modules in the Java runtime image, without needing to rely on predefined profiles.

Profiles, introduced in Java SE 8, define subsets of the Java SE Platform API that can reduce the static size of the Java runtime on devices that have limited storage capacity. The tools in JDK 8 support three profiles, compact1, compact2, and compact3. For the API composition of each profile, see Detailed Profile Composition and API Reference in the JDK 8 documentation.

In JDK 8, you use the -profile option to specify the profile when running javac and java. In JDK 9, the -profile option is supported by javac only in conjunction with the --release 8 option, and is not supported by java.

JDK 9 allows you to choose the modules that are used at compile and run time. By specifying modules with the new --limit-modules option, you can obtain the same APIs that are in the compact profiles. This option is supported by both javac and java, as shown in the following examples:

javac --limit-modules java.base,java.logging MyApp.java
java --limit-modules java.base,java.logging MyApp
The packages specified for each profile in Java SE 8 are exported, collectively, by the following sets of modules:
  • For the compact1 profile: java.base, java.logging, java.scripting

  • For the compact2 profile: java.base, java.logging, java.scripting, java.rmi, java.sql, java.xml

  • For the compact3 profile: java.base, java.logging, java.scripting, java.rmi, java.sql, java.xml, java.compiler, java.instrument, java.management, java.naming, java.prefs, java.security.jgss, java.security.sasl, java.sql.rowset, java.xml.crypto

You can use the jdeps tool to do a static analysis of the Java packages that are being used in your source code. This gives you the set of modules that you need to execute your application. If you had been using the compact3 profile, for example, you may see that you do not need to include that entire set of modules when you build your application. See jdeps in Java Platform, Standard Edition Tools Reference.

See JEP 200: The Modular JDK.

Use CLDR Locale Data by Default

In JDK 9, the Unicode Consortium's Common Locale Data Repository (CLDR) data is enabled as the default locale data, so that you can use standard locale data without any further action.

In JDK 8, although CLDR locale data is bundled with the JRE, it is not enabled by default.

Code that uses locale-sensitive services such as date, time, and number formatting may produce different results with the CLDR locale data. Remember that even System.out.printf() is locale-aware.

To enable behavior compatible with JDK 8, set the system property java.locale.providers to a value with COMPAT ahead of CLDR, e.g., java.locale.providers=COMPAT,CLDR

See CLDR Locale Data Enabled by Default in the Java Platform, Standard Edition Internationalization Guide and JEP 252: Use CLDR Locale Data by Default.

Thread.stop(Throwable) Throws Exception

Thread.stop(Throwable) is unsupported in JDK 9. If you use it, you will get an UnsupportedOperationException.

Thread.stop(Throwable), which forces the target thread to stop and throw a given Throwable as an exception, has the potential to compromise security. Objects may be left in an inconsistent state or the exception may be something that the thread is not prepared to handle.

There is no change to the deprecated no-argument Thread.stop() method.

See Java Thread Primitive Deprecation in the JDK 8 documentation.

Removed stopThread RuntimePermission from the Default java.policy

The default java.policy no longer grants stopThread runtime permission in JDK 9.

In previous releases, untrusted code had the stopThread runtime permission by default. This allows untrusted code to call Thread.stop on threads other than the current one. Trusted code should not be expected to gracefully handle an arbitrary exception thrown asynchronously.

The following line is deleted from the file conf/security/java.policy :
permission java.lang.RuntimePermission "stopThread";

Deployment

This section includes issues that appear only when deploying an application.

Removed Launch-Time JRE Version Selection

The ability to request a version of the JRE that is not the JRE being launched at launch time is removed in JDK 9.

Modern applications are typically deployed via Java Web Start (JNLP), native OS packaging systems, or active installers. These technologies have their own methods to manage the JREs needed, by finding or downloading and updating the required JRE, as needed. This makes the launcher's launch-time JRE version selection obsolete.

In the previous releases, you could specify what JRE version (or range of versions) to use when launching an application. Version selection was possible through both a command-line option and manifest entry in the application's JAR file.

In JDK 9, the java launcher is modified as follows:
  • Emits an error message and exits if the -version option is given on the command line.
  • Emits a warning message and continues if the JRE-Version manifest entry is found in a jar file.

See JEP 231: Remove Launch-Time JRE Version Selection.

Removed Support for Serialized Applets

In JDK 9, the ability to deploy an applet as a serialized object is not supported. With modern compression and JVM performance, there is no benefit to deploying an applet in this way.

The object attribute of the applet tag and the object and java object applet parameter tags are ignored during applet launching.

Instead of serializing applets, use standard deployment strategies.

JNLP Specification Update

JNLP has been updated to remove inconsistencies, make code maintenance easier, and enhance security.

JNLP has been updated as follows:

  1. &amp; replaces & in JNLP files.

    The JNLP file syntax now conforms with the XML specification and all JNLP files should be able to be parsed by standard XML parsers.

    JNLP files allow you to specify complex comparisons. Previously this was done using & but this not supported in standard XML. If you are using & to create complex comparisons, then replace it with &amp; in your JNLP file. &amp; is compatible with all versions of JNLP.

  2. Comparison of numeric version element types against non-numeric version element types.

    Previously, when an int version element was compared with another version element that could not be parsed as an int, the version elements were compared lexicographically by ASCII value.

    In JDK 9, if the element that can be parsed as an int is a shorter string than the other element, it will be padded with leading zeros before being compared lexicographically by ASCII value. This ensures there can be no circularity.

    In the case where both version comparisons and a JNLP servlet are used, you should use only numeric values to represent versions.

  3. Component extensions with nested resources in java (or j2se) elements.

    This is now permitted in the specification. It was previously supported, but this support was not reflected in the specification.

  4. FX XML extension.

    The JNLP specification has been enhanced to add a "type" attribute to application-desc element, and add sub-element "param" in application-desc (as it already is in applet-desc).

    This does not cause problems with existing applications because the previous way of specifying a JavaFX application is still supported.

See the JNLP specification updates at JSR-056.

Changes to Garbage Collection

This section includes changes to garbage collection in JDK 9.

Make G1 the Default Garbage Collector

The Garbage-First Garbage Collector (G1 GC) is the default garbage collector on 32- and 64-bit server configurations.

A low-pause collector such as G1 GC should provide a better overall experience, for most users, than a throughput-oriented collector such as the Parallel GC, which is the JDK 8 default.

See Ergonomic Defaults for G1 GC and Tunable Defaults in Java Platform, Standard Edition Java Virtual Machine Guide for more information about tuning G1 GC.

Removed GC Options

The following GC combinations will cause your application to not start in JDK 9.

  • DefNew + CMS
  • ParNew + SerialOld
  • Incremental CMS

The foreground mode for CMS has also been removed. The command line flags that were removed are -Xincgc, -XX:+CMSIncrementalMode, -XX:+UseCMSCompactAtFullCollection, -XX:+CMSFullGCsBeforeCompaction, and -XX:+UseCMSCollectionPassing.

The command line flag -XX:+UseParNewGC no longer has an effect. ParNew can only be used with CMS and CMS requires ParNew. Thus, the -XX:+UseParNewGC flag has been deprecated and will likely be removed in a future release.

See JEP 214: Remove GC Combinations Deprecated in JDK 8.

Removed Permanent Generation

The permanent generation has been removed from the Java HotSpot Virtual Machine and therefore the options for tuning the size of the permanent generation have been removed.

Class metadata, interned strings, and class static variables have been moved to either the Java heap or native memory. Tools that are aware of the permanent generation may have to be updated.

The following options related to permanent generation, deprecated in JDK 8, are removed in JDK 9:

  • -XX:MaxPermSize=size: Sets the maximum size of the permanent generation

  • -XX:PermSize=size: Sets the initial size of the permanent generation

You should remove these options from your scripts. In JDK 9, the JVM issues a warning.

See JEP 122: Remove the Permanent Generation.

Changes to GC Log Output

Garbage Collection (GC) logging now uses the JVM unified logging framework, and there are some differences between the new and the old logs. Any GC log parsers you are working with will probably need to change.

You may also need to update your JVM logging options. All GC-related logging should use the gc tag (for example, —Xlog:gc), usually in combination with other tags. The —XX:+PrintGCDetails and -XX:+PrintGC options have been deprecated.

See Enable Logging with the JVM Unified Logging Framework in the Java Platform, Standard Edition Tools Reference and JEP 271: Unified GC Logging.

Removed Tools

This list includes tools and components that are no longer bundled with JDK 9.

Removed JavaDB

JavaDB, which was a rebranding of Apache Derby, is not included in JDK 9.

JavaDB was bundled with JDK 7 and JDK 8. It was found in the db directory of the JDK installation directory.

You can download and install Apache Derby from Apache Derby Downloads.

Removed the JVM TI hprof Agent

The hprof agent library has been removed.

The hprof agent was written as demonstration code for the JVM Tool Interface and was not intended to be a production tool. The useful features of the hprof agent have been superseded by better alternatives, including some that are included in the JDK.

For creating heap dumps in the hprof format, use a diagnostic command (jcmd) or the jmap tool:

  • Diagnostic command: jcmd <pid> GC.heap_dump. See jcmd.
  • jmap: jmap -dump. See jmap.

For CPU profiler capabilities, use the Java Flight Recorder which is bundled with the JDK.

Note:

Java Flight Recorder requires a commercial license for use in production. To learn more about commercial features and how to enable them please visit http://www.oracle.com/technetwork/java/javaseproducts/.

See JEP 240: Remove the JVM TI hprof Agent.

Removed the jhat Tool

The jhat tool was an experimental, unsupported heap visualization tool added in JDK 6. Superior heap visualizers and analyzers have been available for many years.

Removed java-rmi.exe and java-rmi.cgi Launchers

The launchers java-rmi.exe from Windows and java-rmi.cgi from Linux and Solaris have been removed.

java-rmi.cgi was in $JAVA_HOME/bin on Linux on Solaris.

java-rmi.exe was in $JAVA_HOME/bin on Windows.

These launchers were added to the JDK to facilitate use of the RMI CGI proxy mechanism, which was deprecated in JDK 8.

The alternative of using a servlet to proxy RMI over HTTP has been available, and even preferred, for several years. See Java RMI and Object Serialization.

Removed Support for the IIOP transport from the JMX RMIConnector

The IIOP transport support from the JMX RMI Connector along with its supporting classes have been removed in JDK 9.

In JDK 8, support for IIOP transport was downgraded from required to optional. This was the first step in a multi-release effort to remove support for the IIOP transport from the JMX Remote API. In JDK 9, support for IIOP has been removed completely.

Public API changes include:

  • javax.management.remote.rmi.RMIIIOPServerImpl class has been deprecated. Upon invocation, all its methods and constructors throw java.lang.UnsupportedOperationException with an explanatory message.

  • Two classes,org.omg.stub.javax.management.rmi._RMIConnection_Stub, and org.omg.stub.javax.management.rmi._RMIConnection_Tie, are not generated.

Dropped Windows 32 Client VM

In JDK 9, Windows 32–bit client VM is dropped and only a server VM is offered.

JDK 8 and earlier releases offered both a client JVM and a server JVM for Windows 32-bit systems. JDK 9 offers only the server JVM. The server JVM is tuned to maximize peak operating speed.

Removed VisualVM

VisualVM is a tool that provides information about code running on a Java Virtual Machine. It was provided with JDK 6, JDK 7, and JDK 8.

VisualVM is not bundled with JDK 9. If you would like to use VisualVM with JDK 9, you can get it from the VisualVM open source project site.

Removed native2ascii Tool

The native2ascii tool is removed in JDK 9. Because JDK 9 supports UTF-8 based properties resource bundles, the conversion tool for UTF-8 based properties resource bundles to ISO-8859-1 is no longer needed.

See UTF-8 Properties Files in Java Platform, Standard Edition Internationalization Guide.

Removed macOS-specific Features

This section includes macOS-specific features that have been removed in JDK 9.

Platform-Specific Desktop Features

 The java.awt.Desktop class now contains replacements for the APIs in the JDK-internal com.apple.eawt and com.apple.eio packages. The new APIs supersede the macOS APIs and are platform independent.

Internal APIs com.apple.eawt and com.apple.eio packages are not accessible by default in JDK 9. Existing libraries or applications that use the internal classes in the apple and com.apple packages and their sub-packages need to migrate to the new API.

The com.apple.concurrent and apple.applescript packages are removed without any replacement.

See JEP 272: Platform-Specific Desktop Features.

Removed AppleScript Engine

AppleScript engine, a platform-specific javax.script implementation, has been removed without any replacement in JDK 9.

The AppleScript engine has been mostly unusable in recent releases. The functionality only worked in JDK 7 or JDK 8 on systems that already had Apple's version of AppleScriptEngine.jar on the system.

Removed macOS-specific com.apple.concurrent.Dispatch Package

The com.apple.concurrent.Dispatch API, a seldom-used, unsupported macOS-specific API, is removed from JDK 9.

If your application used this API, use the standard java.util.concurrent.Executor and java.util.concurrent.ExecutorService implementations instead.

Looking Forward

Once you have your application working on JDK 9, here are some suggestions that can help you get the most from the Java SE Platform.

  • Read Java Platform, Standard Edition What's New in JDK 9 to learn about new features of JDK 9.

  • If needed, cross-compile to an older release of the platform using the new –release flag in javac.

  • Take advantage of your IDE’s suggestions for updating your code with the latest features.

  • Find out if your code is using deprecated APIs by running the static analysis tool jdeprscan. As already mentioned in this guide, APIs can be removed from the JDK, but only with advance notice.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.


Java Platform, Standard Edition Oracle JDK 9 Migration Guide, Release 9

E82965_03

Copyright © 2017, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

This documentation is in pre-General Availability status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

This guide will help you migrate your application to Oracle JDK 9.