This Specification defines version nine of the Java Platform, Standard Edition.
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.
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.
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 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.
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.
Revamp the @Deprecated annotation, and provide tools to strengthen the
API life cycle.
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.
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 javac.
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 is 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
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.
Implement the three Deterministic Random Bit Generator (DRBG) mechanisms described in NIST 800-90Ar1.
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.
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.
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.
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:
A configuration corresponding to the full Java SE Platform;
Custom configurations which contain only a specified set of modules, possibly augmented by external library and application modules, and the modules transitively required by all of these modules.
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):
Here is how to read this visualization of the module graph:
If one module depends upon another, and it grants implied readability to that module via a requires transitive directive, then there is a dark-gray edge from the first module to the second.
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 of the 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, other than the CORBA APIs, that do not overlap with Java EE.
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:
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.
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.)
A Java SE module must export its standard packages without qualification.
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.
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:
An Implementation must include the java.base module.
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.
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.
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:
An Implementation may provide a means to invoke its run-time system with one or more packages of one or more of its modules open to code in all unnamed modules, i.e., to code on the class path. If the run-time system is invoked in this way, and if by doing so some invocations of the reflection APIs succeed where otherwise they would have failed, then the first such invocation must cause a warning to be issued on the standard error stream. Later such invocations may also cause warnings to be issued.
An Implementation may, by default, open one or more packages of one or more of its modules to code in all unnamed modules at run time. If it does so then it must issue warnings as described in the previous paragraph. If it does so then it must, further, provide a means to invoke its run-time system without opening any packages of any of its modules.
(The Reference Implementation’s run-time system behaves this way by
default, and because this is the default it can also be invoked without
opening any of its packages via the command-line option
--illegal-access=deny.)
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:
One module can be made to read another module, at compile time or at run time.
(The Reference Implementation provides this capability via the
--add-reads command-line option.)
A package of one module can be opened to another module, at run time.
(The Reference Implementation provides this capability via the
--add-opens command-line option.)
A package of one module can be exported to another module, at compile time or at run time.
(The Reference Implementation provides this capability via the
--add-exports command-line option.)
A package of one module can be opened or exported to every unnamed module, at compile time or at run time.
(The Reference Implementation provides this capability by allowing
the special token ALL-UNNAMED to be used as a target of the
--add-opens and --add-exports command-line
options.)
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:
A Java SE module is upgradeable if, and only if, it defines an
API that is subject to replacement. Only a small number of Java SE
modules fall into this category. Examples are the
java.corba module, which corresponds to a standard
maintained outside of the Java Community Process, and the
java.transaction and java.xml.bind modules,
which are intended to be usable standalone.
A Java SE module is non-upgradeable if it is essential to the
integrity of the Platform. Most Java SE modules fall into this
category, for example java.base, java.xml, and
java.management.
A non-Java SE module is upgradeable unless the Implementation deems otherwise. Custom configurations may include non-Java SE library and application modules which it is convenient to upgrade in an atomic fashion. Creators of such configurations should take care to ensure that qualified exports that target such modules cannot be abused if one or more of those modules is upgraded.
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.
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.
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:
if (component.getPeer() != null) ...
This is the supported alternative, available since JDK 1.1:
if (component.isDisplayable()) ...
if (component.getPeer() instanceof LightweightPeer) ...
Since Java SE 1.2, java.awt.Component.isLightweight has been the supported API:
if (component.isLightweight()) ...
if ((getPanel().getPeer() != null) && (getPanel().getPeer().getColorModel() != null)) ...
This is equivalent to the following code, supported since JDK 1.0:
if (getPanel().getColorModel() != null) ...
This works because the color model of a java.awt.Component object 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
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:
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.
