Java SE 16 ( JSR 391)
Specification — DRAFT 30
Iris Clark & Brian Goetz
2020/12/30 00:00 -0800 [de5e839867c0]

This Specification defines version 16 of the Java Platform, Standard Edition (“Java SE 16”). The Reference Implementation of this Specification is the Java Development Kit, version 16 (“JDK 16”).

Contents
1Summary
2Structure
3Definitions
4Component JSR Specifications
5Features
6Modules
7APIs removed
8APIs proposed for removal
Annexes
A1Complete API Specification
A2API Specification differences
A3Java Language & Virtual Machine Specifications
A4JAR File Specification
A5Java AWT Native Interface (JAWT) Specification & Guide
A6Java Debug Wire Protocol (JDWP)
A7Java Native Interface (JNI) Specification
A8Java Object Serialization Specification
A9Java Remote Method Invocation (RMI) Specification
A10Java Security Standard Algorithm Names
A11JVM Tool Interface (JVM TI)
1
Summary  

This release continues the evolution of the Platform to ensure the broadest possible success of the core Java technology. It standardizes record classes and pattern matching for instanceof in the Java language, and previews sealed classes. It adds support for Unix-domain sockets in the API, and prepares for future enhancements to the Java programming model by refining the notion of value-based classes. In addition, and in contrast to earlier releases, it requires strong encapsulation of an Implementation’s modules by default.

2
Structure  

This document directly specifies API features, enhancements, clarifications, and bug fixes. It also specifies features by reference to other Specifications which are revised in Maintenance Releases of existing JSRs. The specifications of these changes are contained in two accompanying documents: Annex 1 is the complete Java SE 16 API Specification and Annex 2 is an annotated API specification showing the exact differences relative to Java SE 15. Informative background for these changes may be found in the list of approved Compatibility & Specification Review (CSR) requests for this release.

This Specification includes the Java SE 16 Editions of The Java Language Specification and The Java Virtual Machine Specification in Annex 3. The Java SE 16 Editions contain all corrections and clarifications made since the Java SE 15 Editions, as well as additions for new features. Annex 3 also presents changes to The Java Language Specification and The Java Virtual Machine Specification in connection with preview features in Java SE 16.

This Specification includes the Java SE 16 versions of additional narrative specifications in Annexes 4 — 11. The Java SE 16 versions contain all corrections and clarifications made since the Java SE 15 versions, as well as additions for new features. The Java Object Serialization Specification in Annex 8 contains the most significant changes which were made in connection with Records a final, permanent feature added in Java SE 16.

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  

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 199: Java Compiler API
JSR 269: Pluggable Annotation-Processing API

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

5
Features  

Work on features in the Java SE 16 Reference Implementation is organized in terms of JDK Enhancement Proposals (JEPs). Each feature description gives a link to the corresponding JEP document as a convenience, but that document is not a normative part of this Specification. Some features are included in the Java SE 16 Reference Implementation on a preview basis, to gain exposure before achieving permanent status in a later release of the Java SE Platform.

Language
Pattern Matching for instanceof

Enhance the Java programming language with pattern matching for the instanceof operator. Pattern matching allows common logic in a program, namely the conditional extraction of components from objects, to be expressed more concisely and safely.

Records

Enhance the Java programming language with records, which are classes that act as transparent carriers for immutable data. Records can be thought of as nominal tuples.

Sealed Classes (Second Preview)

Enhance the Java programming language with sealed classes and interfaces. Sealed classes and interfaces restrict which other classes or interfaces may extend or implement them.

Libraries
Strongly Encapsulate JDK Internals by Default

Strongly encapsulate all internal elements of the JDK by default, except for critical internal APIs such as sun.misc.Unsafe. Allow end users to choose the relaxed strong encapsulation that has been the default since JDK 9.

Unix-Domain Socket Channels

Add Unix-domain (AF_UNIX) socket support to the socket channel and server-socket channel APIs in the java.nio.channels package. Extend the inherited channel mechanism to support Unix-domain socket channels and server socket channels.

Warnings for Value-Based Classes

Designate the primitive wrapper classes as value-based and deprecate their constructors for removal, prompting new deprecation warnings. Provide warnings about improper attempts to synchronize on instances of any value-based classes in the Java Platform.

Preview features A preview language or VM feature is a new feature of the Java SE Platform that is fully specified, fully implemented, and yet impermanent. This Specification incorporates the Java SE 12 Platform Specification (JSR 386), subsection Preview features by reference.

6
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 21 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.base
java.compiler
java.datatransfer
java.desktop
java.instrument
java.logging
java.management
java.management.rmi
java.naming
java.net.http
java.prefs
java.rmi
java.scripting
java.se (aggregator)
java.security.jgss
java.security.sasl
java.sql
java.sql.rowset
java.transaction.xa
java.xml
java.xml.crypto

Compared to Java SE 15, this Specification does not add or remove any modules.

The module graph 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 directed acyclic graph, in which redundant edges are omitted (click to enlarge):

java.se Spec Module Graph

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

A module is a Java SE module — that is, considered part of the Java SE Platform Specification — if and only if it is a standard module reachable from the java.se module.

Relaxing strong encapsulation As an aid to migration, 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.

(The Reference Implementation provides this capability via the command-line option --illegal-access=permit.)

An Implementation must not, by default, relax the strong encapsulation of any of its modules. That is, its run-time system must not customarily behave as if various packages in the Implementation’s modules are open when they are not open according to their module declarations. A package, or an entire module, is open to code in all unnamed modules if and only if:

A future revision of this Specification is expected to disallow relaxed strong encapsulation entirely.

This section may be compared to the corresponding section that appeared in Java SE 9 through 15.

Incorporated subsections This Specification incorporates the following subsections by reference from Java SE 9 Platform Specification (JSR 379), “Modules”:

7
APIs removed  

The following API was removed from the Java SE Platform by this Platform Specification. The number in parentheses indicates the Java SE Platform Specification which first proposed its removal.

Constructor

8
APIs proposed for removal  

The following APIs were proposed for removal from the Java SE Platform by the Platform Specifications for Java SE 9, Java SE 10, Java SE 13, Java SE 14, and Java SE 15. They are not removed in this release of the Java SE Platform. They continue to be eligible for removal in a future release.

Packages 

Classes 

Exceptions  

Methods 

The following APIs are proposed for removal from the Java SE Platform by this Platform Specification. They are annotated as @Deprecated with forRemoval=true, following the convention established by Enhanced Deprecation. This makes them eligible for removal in a future release.

Methods   

Constructors   

Additional details about deprecations, including potential alternatives, may be found in the Deprecated API list of the API Specification. Migration away from deprecated APIs is strongly encouraged.