This Specification defines version nine of the Java Platform, Standard Edition.
|4||Component JSR Specifications|
|10||APIs proposed for removal|
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 will enable 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.
In addition to these key features this release adds a collection of smaller yet significant features, removes some existing features and APIs, and proposes to remove yet more APIs in the next release.
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 drafts of 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 will be incorporated in time for the Proposed Final Draft of this Specification.
Finally, this Specification includes changes to the Java Native Inteface Specification (JNI) for Java SE 9 in Annex 4. These changes include all corrections, clarifications, and additions for features in this specification.
The Final Release of this Specification is expected to include all of the features listed here, but it is possible for a feature to be dropped. The Expert Group could, for example, determine that a feature is not yet ready for standardization, or too costly to implement.
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.
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 will be 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 expected in separate Maintenance Releases, which are incorporated here by reference:
JSR 067: Java APIs for XML Messaging (SAAJ) JSR 199: Java Compiler API JSR 221: JDBC API JSR 222: Java Architecture for XML Bindings (JAXB) JSR 224: Java API for XML-Based Web Services (JAX-WS) JSR 269: Pluggable Annotation-Processing API JSR 907: Java Transaction API (JTA) JSR 925: Java Beans Activation Framework
Each Component JSR Specification, or revision thereto, is related to one or more features in the detailed list below.
|Core Libraries||Convenience Factory Methods for Collections|
|Enhanced Method Handles|
|Filter Incoming Serialization Data|
|Indify String Concatenation|
|More Concurrency Updates|
|Platform Logging API and Service|
|Process API Updates|
|UTF-8 Property Resource Bundles|
|Use CLDR Locale Data by Default|
|Security||Create PKCS12 Keystores by Default|
|DRBG-Based SecureRandom Implementations|
|Datagram Transport Layer Security (DTLS)|
|OCSP Stapling for TLS|
|TLS Application-Layer Protocol Negotiation Extension|
|Client Libraries||Deprecate the Applet API|
|Platform-Specific Desktop Features|
|TIFF Image I/O|
|Language||Elide Deprecation Warnings on Import Statements|
|Milling Project Coin|
|Platform||Module System (JSR 376)|
|Multi-Release JAR Files|
|New Version-String Scheme|
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.
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.
@Deprecated annotation, and provide tools to strengthen the
API life cycle.
classes of the
java.lang.invoke package to ease common use cases and
enable better compiler optimizations by means of new
combinators and lookup refinement.
Allow incoming streams of object-serialization data to be filtered in order to improve both security and robustness.
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
An interoperable publish-subscribe framework, enhancements to the
CompletableFuture API, and various other improvements.
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 will be used.
Improve the API for controlling and managing operating-system processes.
Define an API to allow Java code to hint that a spin loop is being executed.
Define an efficient standard API for stack walking that allows easy filtering of, and lazy access to, the information in stack traces.
Define a means for applications to specify property files encoded in UTF-8, and extend the ResourceBundle API to load them.
Use locale data from the Unicode Consortium's Common Locale Data Repository (CLDR) by default.
Define a standard means to invoke the equivalents of various
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
Implement the three Deterministic Random Bit Generator (DRBG) mechanisms described in NIST 800-90Ar1.
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.
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.
Define a multi-resolution image API so that images with resolution variants can easily be manipulated and displayed.
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.
Extend the standard set of Image I/O plugins to support the TIFF image format.
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.
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.
Implement the Java Platform Module System, as specified by JSR 376, together with related JDK-specific changes and enhancements.
Extend the JAR file format to allow multiple, Java-release-specific versions of class files to coexist in a single archive.
Define a version-string scheme that easily distinguishes major, minor, and security-update releases, and apply it to the JDK.
This Specification uses the Java Platform Module System, specified by JSR 376, to modularize the Java SE Platform. This will make implementations of the Platform more easily scalable down to small devices, improve security and maintainability, and enable improved application performance.
Goals Divide the Java SE Platform into a set of modules that can be combined at compile time, build time, or run time into a variety of configurations including, but not limited to
A configuration corresponding to the full Java SE Platform
Custom configurations which contain only a specified set of modules and the modules transitively required by those modules.
The definition of the modular structure makes a clear distinction between standard modules, whose specifications are governed by the Java Community Process, and other, non-standard modules. It also distinguishes standard modules that are part of the Java SE Platform Specification, and thereby mandatory in every Platform Implementation, from other standard modules.
Design principles The modular structure implements the following principles:
Standard modules, whose specifications are governed by the JCP, must have names starting with the string “java.”.
If a Platform Implementation contains any non-standard modules then the names of those modules must not start with the string “java.”.
If a 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 module, then the first module must grant implied readability to the second, via requires transitive. (This ensures that method-invocation chaining works in the obvious way.)
A standard module will typically contain API packages defined by its respective Specification; we refer to these as standard API packages. A standard module may also contain some non-standard API packages. If a standard module exports a standard API package then the export may be qualified; if a standard module exports a non-standard API package then the export must be qualified. In either case, if a standard module exports any package with qualification then the export must only target modules in the same Platform Implementation. If a standard module is a Java SE module, i.e., is mandated by this Specification, then it must not export any non-SE API packages, at least not without qualification.
A standard module may depend upon one or more non-standard modules. It must not grant implied readability to any non-standard module. If it is a Java SE module then it must not grant implied readability to any non-SE module.
A non-standard module must not export any standard API packages. A non-standard module may grant implied readability to a standard module.
An important consequence of principles 4 and 5 is that code that depends only upon Java SE modules will depend only upon Java SE types, and thus be portable to all Implementations of the Java SE Platform.
The module graph The modular structure of the Java SE Platform can be visualized as a graph. Each module is a node, and there is a directed edge from one module to another if the first depends upon the second. The full module graph has too many edges to be displayed easily; here is the transitive reduction of the graph, in which redundant edges are omitted (click to enlarge):
Here is a guided tour of the module graph:
If one module depends upon another, and it grants implied readability to that module, then the edge from the first module to the second is solid; otherwise the edge is dashed.
At the very bottom is the java.base module, which contains essential classes such as java.lang.Object and java.lang.String. The base module depends upon no module, and every other module depends upon the base module. Edges to the base module are lighter than other edges.
At the top is the java.se.ee module, which gathers together all of the modules that comprise the Java SE Platform, including modules whose exported packages overlap with the Java EE Platform Specification. This is an example of an aggregator module, which logically gathers the content of other modules by granting implied readability to them, but adds no content of its own. A run-time system configured to contain the java.se.ee module will contain all the API packages of the Java SE Platform. A module is considered part of the Java SE Platform Specification if, and only if, it is a standard module reachable from the java.se.ee module.
The java.se aggregator module gathers together those parts of the Java SE Platform that do not overlap with Java EE.
The Java SE Platform module graph is an entirely new aspect of the Java SE Platform Specification. Its evolution will be governed by the JCP and is subject to the same evolutionary constraints as other APIs. Removing a module or changing it incompatibly, in particular, will require public notice at least one major release in advance.
Conformance Every Implementor of this Specification must implement the java.base module. Every Implementor may, further, implement a set of one or more additional standard SE modules so long as that set is closed, i.e., contains every standard module required by any member of the set. The Technology Compatibility Kit (TCK) for this Specification will be structured to allow testing of arbitrary configurations of SE modules present in a Platform Implementation. A Reference Implementation (RI) will be provided for each module, and for the entire Platform.
If an Implementation of this Specification implements a module then it must be complete, i.e., it must implement every API element of that module. This includes the module’s name, exported API packages, and any dependences that cause SE API packages to be re-exported. If an Implementation implements the entire Platform then it must implement every API element of the Platform. No other forms of Implementation are permitted.
Configuration files Minor changes to the API specifications for StAX, JAX-WS, and SAAJ were necessary in order to change how their factory methods locate service provider implementations. 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.
A clean modularization of the Java SE Platform requires the removal of a small number of little-used yet problematic features.
Extension Mechanism This mechanism allowed JAR files containing APIs that extended the Java SE Platform to be installed into a run-time image. 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 the upgradeable modules requirement of the Java Platform Module System, JSR 376.
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 a run-time image. This feature was deprecated in a JSR 337 MR and is superseded by the upgradeable modules requirement in the Java Platform Module System, JSR 376.
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.
A clean modularization of the Java SE Platform requires 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 All APIs whose signatures refer to types
defined in the internal packages
java.awt.dnd.peer are only accessible within the
A key principle of the modular structure of the Platform, described
above, is that standard modules must not export any non-SE API packages.
internal packages, they were never included in the Java SE Platform and
hence are not exported from the
java.desktop module. These
“peer types” were deprecated in JDK 1.1 (released in 1996) when it was
determined that they should not be used by applications.
Analysis of a large body of Java library and application code revealed the following typical usage patterns, in order of most to least frequently observed:
if (component.getPeer() != null)
This is the supported alternative, available since JDK 1.1:
if (component.getPeer() instanceof LightweightPeer)
Since Java SE 1.2, java.awt.Component.isLightweight has been the supported API:
if ((getPanel().getPeer() != null) && (getPanel().getPeer().getColorModel() != null))
This is equivalent to the following code, possible since JDK 1.0:
if (getPanel().getColorModel() != null)
This works because the color model of the java.awt.Component comes from the peer, if it has one.
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
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
The following API elements reference the package-private types
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:
The Enhanced Deprecation feature introduces a means
to provide more nuanced information about the status and intended
disposition of APIs. It expands the
with a boolean
forRemoval element which, if
expresses the intent to remove the API in the 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.annotations.common, defines a small
subset of that in Java EE. The inclusion of these APIs in SE has long
been problematic, so we propose here to annotate them as
forRemoval=true so that they
can be removed in the next major 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, or have been superseded by newer APIs which do not have these faults:
Many of these elements have already been deprecated for several major
releases, and in some cases since Java SE 1.2. We propose here to
annotate all of these as
forRemoval=true so that they can be removed in the next major
Additional details about the deprecations mentioned here can be found in the Deprecated API list of the Early Access API Specification The Public Review version of this Specification will include a more detailed summary of these deprecations.