Java SE 9 ( JSR 379)
Proposed Final Draft Specification — DRAFT
Iris Clark & Mark Reinhold
2017/7/27 12:59 -0700 [f84240a3c1ab]

This Specification defines version nine of the Java Platform, Standard Edition.

Contents
1Summary
2Structure
3Definitions
4Component JSR Specifications
5Feature summary
6Feature details
7Modules
8Non-API features removed
9APIs removed
10APIs proposed for removal
Annexes
A1API Specification change summary
A2API Specification differences
A3Java Language & Virtual Machine Specifications
A4Java Native Interface (JNI) Specification
A5Complete API Specification
1
Summary  

The key features of this release are the introduction of the Java Platform Module System (JSR 376) and the use of that system to modularize the Java SE Platform itself. The module system addresses two fundamental needs of all large Java applications, namely reliable configuration and strong encapsulation. The application of the module system to the Platform enables Platform Implementations to be customized for scenarios ranging from small computing devices to dense cloud deployments; to improve security by encapsulating implementation-internal APIs; and to improve performance via more effective ahead-of-time, whole-program optimization techniques.

This release also adds a collection of smaller yet significant features, removes some existing features, and proposes to remove yet more features in the next release.

2
Structure  

As an Umbrella Platform Specification, this document specifies significant features by reference to other Specifications which are either defined in new Component JSRs or revised in Maintenance Releases of existing such JSRs.

This Specification directly specifies smaller API features, enhancements, clarifications, and bug fixes that are not part of any Component JSR Specification. The specifications of those changes are contained in two accompanying documents: Annex 1 is a detailed change summary and Annex 2 is an annotated API specification showing the exact differences relative to Java SE 8. The Component JSR Specifications may include API specifications for some of the packages detailed in Annex 2; in case of discrepancy, the Component JSR Specifications take precedence.

This Specification also includes the Java SE 9 Editions of The Java Language Specification and The Java Virtual Machine Specification in Annex 3. The Java SE 9 Editions include all corrections and clarifications made since the Java SE 8 Editions, as well as additions for small features that are not themselves the subject of a Component JSR Specification. Changes to the Java SE 9 Editions due to Component JSR Specifications are also incorporated.

This Specification includes changes to the Java Native Interface Specification (JNI) for Java SE 9 in Annex 4.

Finally, this Specification includes the complete Java SE 9 API Specification in Annex 5.

3
Definitions  

Changes to the Java SE Platform Specification are categorized as either features or enhancements. A feature is, roughly speaking, a change of which at least one of the following statements is true:

Any addition that is not a feature is considered an enhancement.

There is, obviously, room for judgment when interpreting this definition. In order to maximize the visibility of Platform revisions we generally tend to consider borderline items to be features rather than enhancements.

4
Component JSR Specifications  

The significant new features of this release are specified in a separate new Component JSR Specification, which is incorporated here by reference:

JSR 376: Java Platform Module System

The following existing component JSRs are subsumed by this Specification:

JSR 003: Java Management Extensions (JMX) [MR 6]
JSR 160: Java Management Extensions (JMX) Remote API [MR 3]
JSR 173: Streaming API for XML (StAX)  [MR 5]
JSR 206: Java API for XML Processing (JAXP) [MR 3]
JSR 223: Scripting for the Java Platform [MR 1]

Some Component JSR Specifications previously incorporated into the Platform are still available separately or have significant Specifications themselves. Changes to their Specifications are therefore made in separate Maintenance Releases, which are incorporated here by reference:

JSR 067: Java APIs for XML Messaging (SAAJ) [MR 5]
JSR 199: Java Compiler API [MR 2]
JSR 221: JDBC API [MR 3]
JSR 222: Java Architecture for XML Bindings (JAXB) [MR 3]
JSR 224: Java API for XML-Based Web Services (JAX-WS) [MR 6]
JSR 269: Pluggable Annotation-Processing API [MR 3]
JSR 925: Java Beans Activation Framework [MR 2]

Each Component JSR Specification, or revision thereto, is related to one or more features in the detailed list below.

5
Feature summary  
Core LibrariesConvenience Factory Methods for Collections
Enhanced Deprecation
Enhanced Method Handles
Filter Incoming Serialization Data
Indify String Concatenation
More Concurrency Updates
Platform Logging API and Service
Process API Updates
Spin-Wait Hints
Stack-Walking API
UTF-8 Property Resource Bundles
Use CLDR Locale Data by Default
Variable Handles
SecurityCreate PKCS12 Keystores by Default
DRBG-Based SecureRandom Implementations
Datagram Transport Layer Security (DTLS)
OCSP Stapling for TLS
TLS Application-Layer Protocol Negotiation Extension
Client LibrariesDeprecate the Applet API
Multi-Resolution Images
Platform-Specific Desktop Features
TIFF Image I/O
LanguageElide Deprecation Warnings on Import Statements
Milling Project Coin
PlatformModule System (JSR 376)
Multi-Release JAR Files
New Version-String Scheme
Unicode 8.0
XMLXML Catalogs
6
Feature details  

If a feature description does not refer to a Component JSR Specification then the feature is specified directly in this Umbrella Platform Specification. If a feature is specified partly in a Component JSR Specification and partly in this Specification then a reference to this Specification, JSR 379, is included for clarity.

Work on features in the Java SE 9 Reference Implementation, which is the Java Development Kit, version 9 (JDK 9), is organized in terms of JDK Enhancement Proposals (JEPs). Each feature description includes a link to the corresponding JEP document as a convenience, but that document is not a normative part of this Specification.

Core Libraries
Convenience Factory Methods for Collections

Define library APIs to make it convenient to create instances of collections and maps with small numbers of elements, so as to ease the pain of not having collection literals in the Java programming language.

Enhanced Deprecation

Revamp the @Deprecated annotation, and provide tools to strengthen the API life cycle.

Enhanced Method Handles

Enhance the MethodHandle, MethodHandles, and MethodHandles.Lookup classes of the java.lang.invoke package to ease common use cases and enable better compiler optimizations by means of new MethodHandle combinators and lookup refinement.

Filter Incoming Serialization Data

Allow incoming streams of object-serialization data to be filtered in order to improve both security and robustness.

Indify String Concatenation

Change the static String-concatenation bytecode sequence generated by javac to use invokedynamic calls to JDK library functions. This will enable future optimizations of String concatenation without requiring further changes to the bytecode emitted by javac.

More Concurrency Updates

An interoperable publish-subscribe framework, enhancements to the CompletableFuture API, and various other improvements.

Platform Logging API and Service

Define a minimal logging API which platform classes can use to log messages, together with a service interface for consumers of those messages. A library or application can provide an implementation of this service in order to route platform log messages to the logging framework of its choice. If no implementation is provided then a default implementation based upon the java.util.logging API is used.

Process API Updates

Improve the API for controlling and managing operating-system processes.

Spin-Wait Hints

Define an API to allow Java code to hint that a spin loop is being executed.

Stack-Walking API

Define an efficient standard API for stack walking that allows easy filtering of, and lazy access to, the information in stack traces.

UTF-8 Property Resource Bundles

Define a means for applications to specify property files encoded in UTF-8, and extend the ResourceBundle API to load them.

Use CLDR Locale Data by Default

Use locale data from the Unicode Consortium's Common Locale Data Repository (CLDR) by default.

Variable Handles

Define a standard means to invoke the equivalents of various java.util.concurrent.atomic and sun.misc.Unsafe operations upon object fields and array elements, a standard set of fence operations for fine-grained control of memory ordering, and a standard reachability-fence operation to ensure that a referenced object remains strongly reachable.

Security
Create PKCS12 Keystores by Default

Transition the default keystore type from JKS to PKCS12.

DRBG-Based SecureRandom Implementations

Implement the three Deterministic Random Bit Generator (DRBG) mechanisms described in NIST 800-90Ar1.

Datagram Transport Layer Security (DTLS)

Define an API for Datagram Transport Layer Security (DTLS) version 1.0 (RFC 4347) and 1.2 (RFC 6347).

OCSP Stapling for TLS

Implement OCSP stapling via the TLS Certificate Status Request extension (section 8 of RFC 6066) and the Multiple Certificate Status Request Extension (RFC 6961).

TLS Application-Layer Protocol Negotiation Extension

Extend the javax.net.ssl package to support the TLS Application Layer Protocol Negotiation (ALPN) Extension, which provides the means to negotiate an application protocol for a TLS connection.

Client Libraries
Deprecate the Applet API

Deprecate the Applet API, which is rapidly becoming irrelevant as web-browser vendors remove support for Java browser plug-ins. Guide developers to alternative technologies such as Java Web Start or installable applications.

Multi-Resolution Images

Define a multi-resolution image API so that images with resolution variants can easily be manipulated and displayed.

Platform-Specific Desktop Features

Define a new public API to access platform-specific desktop features such as interacting with a task bar or dock, or listening for system or application events.

TIFF Image I/O

Extend the standard set of Image I/O plugins to support the TIFF image format.

Language
Elide Deprecation Warnings on Import Statements

As of Java SE 8, java compilers are required by reasonable interpretations of the Java Language Specification to issue deprecation warnings when a deprecated type is imported by name or when a deprecated member (method, field, nested type) is imported statically. These warnings are uninformative and should not be required. Deprecation warnings at actual uses of deprecated members should remain.

Milling Project Coin

The small language changes included in Project Coin / JSR 334 as part of JDK 7 / Java SE 7 have been easy to use and have worked well in practice. However, a few amendments could address the rough edges of those changes. In addition, using underscore ("_") as an identifier, which generates a warning as of Java SE 8, should be turned into an error in Java SE 9. It is also proposed that interfaces be allowed to have private methods.

Platform
Module System

Implement the Java Platform Module System, as specified by JSR 376, together with related JDK-specific changes and enhancements.

Multi-Release JAR Files

Extend the JAR file format to allow multiple, Java-release-specific versions of class files to coexist in a single archive.

New Version-String Scheme

Define a version-string scheme that easily distinguishes major, minor, and security-update releases, and apply it to the JDK.

Unicode 8.0

Upgrade existing platform APIs to support version 8.0 of the Unicode Standard.

XML
XML Catalogs

Develop a standard XML Catalog API that supports the OASIS XML Catalogs standard, v1.1. The API will define catalog and catalog-resolver abstractions which can be used with the JAXP processors that accept resolvers.

7
Modules  

A module is a named set of packages designed for reuse. A specification governed by the JCP defines standard packages, and may group them into one or more standard modules.

This Specification groups the standard packages of the Java SE Platform into 26 standard modules, which we refer to as the Java SE modules. The name of a Java SE module always starts with the string "java.". The complete list of such modules is:

java.activation
java.base
java.compiler
java.corba
java.datatransfer
java.desktop
java.instrument
java.logging
java.management
java.management.rmi
java.naming
java.prefs
java.rmi
java.scripting
java.se
java.se.ee
java.security.jgss
java.security.sasl
java.sql
java.sql.rowset
java.transaction
java.xml
java.xml.bind
java.xml.crypto
java.xml.ws
java.xml.ws.annotation

Using the Java Platform Module System, specified by JSR 376, these modules may be combined at compile time, build time, or run time into a variety of configurations including, but not limited to:

The module graph A module is a named set of packages designed for reuse, and it can depend upon one or more other modules. A set of related modules can therefore be seen as a directed graph, in which each module is a node and there is an edge from one module to another if the first depends upon the second. The module system guarantees that module graphs are acyclic.

The Java SE modules depend upon each other as stated in their specifications, which are part of the overall API Specification. The corresponding complete Java SE module graph has too many edges to be displayed easily in visual form; here is the transitive reduction of the graph, in which redundant edges are omitted (click to enlarge):

java.se.ee Spec Module Graph

Here is how to read this visualization of the module graph:

The module graph is an entirely new aspect of the Java SE Platform Specification. It will evolve over time just like any other API, and with the same degree of care and caution. Removing a module or changing it incompatibly, in particular, will require public notice at least one major release in advance.

Constraints on Java SE modules Each Java SE module is subject to the following constraints:

  1. A Java SE module must fully implement the corresponding part of this Specification. It must, in particular, implement every API element of that module including the module’s name, its exported packages, and any requires transitive dependences.

  2. If a Java SE module exports a package that contains a type that contains a public or protected member that, in turn, refers to a type from some other Java SE module, then the first module must grant implied readability to the second, via a requires transitive directive. (This ensures that method-invocation chaining works in the obvious way.)

  3. A Java SE module must export its standard packages without qualification.

  4. A Java SE module may export non-standard packages, in which case the exports must be qualified. The targets of such exports need not themselves be SE modules, but they are intended to be limited to modules that are intimately associated with the implementations of one or more SE modules.

  5. A Java SE module may depend upon one or more non-SE modules. It must not grant implied readability to any non-SE module.

An important consequence of constraints 3, 4, and 5 is that user code that depends only upon Java SE modules will depend only upon types declared in the standard packages of the Java SE Platform, and thus be portable to all Implementations of the Platform that include the necessary Java SE modules.

Constraints on all modules in an Implementation A module is said to be included in an Implementation of the Java SE Platform if, and only if, the module is an observable system module. An Implementation may, and typically will, include modules that are not Java SE modules but, rather, specific to the Implementation. An Implementation may also, in the case of a custom configuration, include additional library and application modules.

Every Implementation is subject to the following constraints upon the modules that it includes:

  1. An Implementation must include the java.base module.

  2. An Implementation may include one or more additional Java SE modules so long as the set of SE modules that the Implementation includes is closed, i.e., includes every SE module required, via requires transitive directives, by any member of the set.

    For example, an Implementation that includes just the java.base, java.sql, java.logging, and java.xml modules is closed because the only requires transitive dependences are from java.sql to java.logging and java.xml, and the latter two modules are members of the set.

  3. An Implementation may include standard modules that are not Java SE modules, i.e., modules whose specifications are governed by the JCP but which are not part of the Java SE Platform.

  4. An Implementation may include one or more non-standard modules. The name of a non-standard module must not start with the string "java.". A non-standard module must not export any standard packages. A non-standard module may grant implied readability to a standard module.

The Technology Compatibility Kit (TCK) for this Specification will test all of the Java SE modules included in an Implementation, and it will require that set to be closed. An Implementation that passes the TCK is considered to fully implement this Specification even if it does not include all of the Java SE modules.

This Specification defines the Licensor Name Space on a module-by-module basis. Provided that an Implementation that fully implements this Specification includes the required Licensor Name Space for each included module then it is not considered to subset the Licensor Name Space.

An Implementation of this Specification may provide a means to create further Implementations. If it does so then any such new Implementation need not include all of the modules present in the original Implementation, but it must satisfy the constraints of the preceding paragraphs.

Relaxing strong encapsulation As an aid to migration, an Implementation may relax the strong encapsulation of the modules that it includes as follows:

Future revisions of this Specification are expected to mandate that all of an Implementation’s modules be strongly encapsulated by default and, eventually, to disallow the above-described relaxation.

Overriding module declarations As a further aid to migration, an Implementation may provide a means establish additional relationships between specific modules, identified by name, regardless of the original declarations of those modules and regardless of whether those modules are included in the Implementation or are part of the application being compiled or run:

None of these capabilities, for any modules, may be operative by default. A future revision of this Specification may disallow these capabilities.

Upgradeable modules This Specification permits the user to replace certain APIs in an Implementation of the Java SE Platform with newer versions, without making any changes to that Implementation.

Two kinds of APIs are subject to replacement. First, there are APIs in the Java SE Platform that correspond to standards maintained outside of the Java Community Process, such as CORBA. Second, there are APIs in the Java SE Platform that evolve with the Platform via the Java Community Process, but which are intended to be usable on their own, i.e., standalone, on versions of the Platform other than the version where they were developed.

Prior to Java SE 9, the Endorsed Standards Override Mechanism allowed the replacement of individual packages in APIs maintained outside of the JCP, but allowed only a complete replacement of APIs evolved via the JCP. Java SE 9 takes advantage of the modular structure of the Platform to allow the replacement of both kinds of APIs, and their implementations, on a uniform module-by-module basis. Specifically, Java SE 9 categorizes each module in an Implementation as either upgradeable or non-upgradeable, and allows an upgradeable module to be replaced by the user without modifying or re-building the Implementation.

An Implementation of the Java SE 9 Platform must provide a means to replace those modules which are categorized as upgradeable, and must not provide a means to replace those modules which are categorized as non-upgradeable. The rules for categorizing a module are as follows:

In order to replace an upgradeable module, the user supplies an alternate version which the Implementation observes in preference to the version included in the Implementation. The alternate version must have the same module name. It will typically export APIs that are newer than those exported by the version in the Implementation, although an Implementation is not required to enforce this property. The alternate version may be provided in the form of a JAR file that defines an automatic module.

(The Reference Implementation provides this capability via the --upgrade-module-path command-line option.)

The specification of an upgradeable Java SE module will indicate that it is upgradeable. If the specification of a Java SE module does not indicate that the module is upgradeable then it is not upgradeable. For reference, the set of upgradeable modules in the Java SE 9 platform is:

java.activation
java.compiler
java.corba
java.transaction
java.xml.bind
java.xml.ws
java.xml.ws.annotation

In Java SE 9, all of the Java SE modules that are upgradeable have been deprecated for removal, except for the java.compiler module.

This Specification does not define a standard means to specify whether an arbitrary library or application module is upgradeable, nor does it define a standard means to ensure the integrity of a set of related library or application modules. The creators of future versions of this Specification are encouraged to consider these requirements.

Configuration files Minor changes to the API specifications of StAX, JAX-WS, and SAAJ were necessary in order to change how their factory methods locate service provider implementations in the modular platform. For StAX, the changes are specified directly in this Umbrella Platform Specification. For JAX-WS and SAAJ, the changes are specified in Maintenance Releases of their Component JSR Specifications.

8
Non-API features removed  

A clean modularization of the Java SE Platform required the removal of a small number of little-used yet problematic non-API features.

Extension Mechanism This mechanism allowed JAR files containing APIs that extended the Java SE Platform to be installed into an Implementation. These APIs were visible to every application that was compiled against or run on that image. This feature was deprecated in a JSR 337 MR and is superseded by upgradeable modules.

Endorsed Standards Override Mechanism This mechanism allowed 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 an Implementation. This feature was deprecated in a JSR 337 MR and is superseded by upgradeable modules.

JMX RMI Connector IIOP support The JMX Remote API defines a standard protocol for connections using RMI. In Java SE 7, the JMX Remote API required support for the IIOP transport, but this support was made optional in Java SE 8 (see JSR 160 MR 3), In Java SE 9, the JMX Remote API no longer supports the IIOP transport.

9
APIs removed  

A clean modularization of the Java SE Platform required the removal of a small number of little-used yet problematic APIs.

Selected PropertyChangeListeners As described in the Java SE 8 Platform Specification (JSR 337), a few methods have a chain of dependencies that ultimately requires the very large java.desktop module. Any application that uses the core logging or JAR-file APIs could only run on a configuration of the Platform that includes the desktop APIs, which is clearly undesirable. These methods have been removed:

AWT Peers The java.awt.peer and java.awt.dnd.peer packages are, despite their names, internal packages. These “peer types” were deprecated in JDK 1.1, released in 1996, when it was determined that they should not be used by applications. These non-standard packages were never included in the Java SE Platform, so per the constraints on Java SE modules they are not exported from the java.desktop module.

An analysis of a large body of Java library and application code revealed some uses of elements of these packages, but the most frequent uses have had supported alternatives for many years:

To remove references to these internal packages from exported SE APIs, the following methods have either been removed or made inaccessible:

Inaccessible Swing types All APIs containing signature references to the internal, inaccessible types JRootPane.DefaultAction, MetalBumps, and MetalFileChooserUI.DirectoryComboBoxRenderer in module java.desktop have been removed or made inaccessible.

The following fields, which were deprecated in Java SE 1.3, referred to instances of the nested package-private class javax.swing.JRootPane.DefaultAction. These fields have been removed:

The following API elements reference the package-private types MetalBumps and MetalFileChooserUI.DirectoryComboBoxRenderer in the javax.swing.plaf.metal package, which were never included in the Java SE Platform and thus are not exported from the java.desktop module. These elements have been removed:

LambdaMetafactory default constructor The LambdaMetaFactory class, introduced in Java SE 8, did not have any instance members and instantiation was never supported; thus, the default constructor was of no value. Further, analysis of a large body of Java library and application code revealed no dependencies. Thus, the element was removed:

10
APIs proposed for removal  

The Enhanced Deprecation feature introduces a means to provide more nuanced information about the status and intended disposition of APIs. It expands the @Deprecated annotation with a boolean forRemoval element which, if true, expresses the intent to remove the API in a future release. In the Java SE Platform Specification, if an API is annotated with forRemoval=true, then the intent is to remove that API in the next major release of the Platform.

In this release we propose, in the next release, to remove the java.corba module, the four modules that define APIs that overlap with the Java EE Platform Specification, and the java.activation, module which was originally included in Java SE 6 as part of JAXB/JAX-WS:

The APIs defined by these modules evolve independently of Java SE or, in the case of java.xml.ws.annotation, defines a small subset of that in Java EE. The inclusion of these APIs in the Platform has long been problematic, so in this release they are annotated as @Deprecated with forRemoval=true so that they can be removed in the next major release.

Since the java.se.ee module simply gathers the content of many of the previously-mentioned modules, it was deprecated in the current release and will be removed in the next release.

In this release we also propose, in the next release, to remove various APIs and API elements that are ill-defined, do not work, do not do anything useful, and in some cases have been superseded by newer APIs which do not have these faults:

Many of these elements have been deprecated for several major releases, in some cases since Java SE 1.2. In this release all of these elements are annotated as @Deprecated with forRemoval=true so that they can be removed in the next major release.

Additional details of the deprecations mentioned here can be found in the Deprecated API list of the API Specification.