JSR 337: Java SE 8
Proposed Final Draft Specification
Mark Reinhold
2014/1/8 16:23 -0800 [2915c22aa64d]

This Specification defines the eighth version of the Java Platform, Standard Edition, which is currently scheduled for release in March 2014.

Contents
1Summary
2Structure and status
3Definitions
4Component JSR Specifications
5Feature summary
6Feature details
7APIs proposed for removal
8Profiles
9Stripped Implementations
1
Summary 

The primary feature of this release is the addition of lambda expressions and default methods to the Java programming language, together with related API enhancements (JSR 335). This release also includes a new date and time API (JSR 310), the extension of the language to allow annotations on types (JSR 308), and a collection of smaller features.

The original request for this Specification proposed to include a module system, and to use that system to modularize the Platform itself. That feature was, however, deferred to a future release in order to allow sufficient time for the broad evaluation, review, and feedback which such a profound change to the Platform demands. To enable the clean modularization of the Platform in the future, this release takes the opportunity to deprecate a small number of methods whose signatures introduce problematic API dependences, so that they can be removed in that release.

As an interim step toward a fully-modular Platform, this release defines three compact Profiles so that applications that use just part of the Platform can run on resource-constrained devices.

Even the smallest Profile will be too large for some scenarios. When a Platform Implementation is packaged together with an application, this release allows elements of the Implementation to be removed when it is known that the application will never depend upon any removed element.

2
Structure and status 

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 7. 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 8 Editions of The Java Language Specification and The Java Virtual Machine Specification in Annex 3. These drafts include all changes from Component JSR Specifications (JSR 335 and JSR 308), as well as all small features, corrections, and clarifications that are not themselves the subject of a Component JSR 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 too costly to implement.

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 judgement 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 separate new Component JSR Specifications, which are incorporated here by reference:

JSR 308: Annotations on Java Types
JSR 310: Date and Time API
JSR 335: Lambda Expressions

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 003: Java Management Extensions
JSR 114: JDBC Rowsets
JSR 160: JMX Remote API
JSR 173: Streaming API for XML
JSR 199: Java Compiler API
JSR 206: Java API for XML Processing
JSR 221: JDBC 4.0
JSR 269: Pluggable Annotation-Processing API

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

5
Feature summary 
LanguageAccess to Parameter Names at Runtime (JSR 269 MR, 337)
Add Javadoc to javax.tools (JSR 199 MR)
Annotations on Java Types (JSR 308)
Generalized Target-Type Inference (JSR 335)
Lambda Expressions & Virtual Extension Methods (JSR 269 MR, 335)
Repeating Annotations (JSR 269 MR, 337)
Core LibrariesBase64 Encoding & Decoding
Bulk Data Operations for Collections (JSR 335)
Concurrency Updates
Date & Time API (JSR 310)
Enhance Core Libraries with Lambda (JSR 335)
JDBC 4.2 (JSR 114 MR, 221 MR)
Parallel Array Sorting
Statically-Linked JNI Libraries
I18nBCP 47 Locale Matching
Unicode 6.2
NetworkingHTTP URL Permissions
SecurityConfigurable Secure Random-Number Generation
Enhance the Certificate Revocation-Checking API
Limited doPrivileged
NSA Suite B Cryptographic Algorithms
TLS Server Name Indication (SNI) Extension
XMLRestrict Fetching of External XML Resources (JSR 206 MR)
PlatformCompact Profiles (JSR 3 MR, 160 MR, 337)
Prepare for Modularization (JSR 173 MR, 206 MR, 337)
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 337, is included for clarity.

Work on features in the prototype Java SE 8 Reference Implementation, which is the Java Development Kit, version 8 (JDK 8), 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.

Language
Access to Parameter Names at Runtime
Provide a mechanism to easily and reliably retrieve the parameter names of methods and constructors at runtime via core reflection.
Add Javadoc to javax.tools
Extend the javax.tools API to provide access to javadoc.
Annotations on Java Types
Extend the set of annotatable locations in the syntax of the Java programming language to include names which indicate the use of a type as well as (per Java SE 5.0) the declaration of a type.
Generalized Target-Type Inference
Smoothly expand the scope of method type-inference to support (i) inference in method context and (ii) inference in chained calls.
Lambda Expressions & Virtual Extension Methods
Add lambda expressions (closures) and supporting features, including method references, enhanced type inference, and virtual extension methods, to the Java programming language and platform.
Repeating Annotations
Change the Java programming language to allow multiple application of annotations with the same type to a single program element.
Core Libraries
Base64 Encoding & Decoding
Define a standard API for Base64 encoding and decoding.
Bulk Data Operations for Collections
Add functionality to the Java Collections Framework for bulk operations upon data. This is commonly referenced as “filter/map/reduce for Java.” The bulk data operations include both serial (on the calling thread) and parallel (using many threads) versions of the operations. Operations upon data are generally expressed as lambda functions.
Concurrency Updates
Scalable updatable variables, cache-oriented enhancements to the ConcurrentHashMap API, ForkJoinPool improvements, and additional Lock and Future classes.
Date & Time API
Define a new date, time, and calendar API for the Java SE platform.
Enhance Core Libraries with Lambda
Enhance the Java core library APIs using the new lambda language feature to improve the usability and convenience of the library.
JDBC 4.2
Minor enhancements to JDBC to improve usability and portability
Parallel Array Sorting
Add additional utility methods to java.util.Arrays that use the JSR 166 Fork/Join parallelism common pool to provide sorting of arrays in parallel.
Statically-Linked JNI Libraries
Enhance the JNI specification to support statically linked native libraries.
I18n
BCP 47 Locale Matching
Define APIs so that applications that use BCP 47 language tags (see RFC 5646) can match them to a user’s language preferences in a way that conforms to RFC 4647.
Unicode 6.2
Extend existing platform APIs to support version 6.2 of the Unicode Standard.
Networking
HTTP URL Permissions
Define a new type of network permission which grants access in terms of URLs rather than low-level IP addresses.
Security
Configurable Secure Random-Number Generation
Enhance the API for secure random-number generation so that it can be configured to operate within specified quality and responsiveness constraints.
Enhance the Certificate Revocation-Checking API
Improve the certificate revocation-checking API to support best-effort checking, end-entity certificate checking, and mechanism-specific options and parameters.
Limited doPrivileged
Enable code to assert a subset of its privileges without otherwise preventing the full access-control stack walk to check for other permissions.
NSA Suite B Cryptographic Algorithms
Provide implementations of the cryptographic algorithms required by NSA Suite B.
TLS Server Name Indication (SNI) Extension
Add support for the TLS Server Name Indication (SNI) Extension to allow more flexible secure virtual hosting and virtual-machine infrastructure based on SSL/TLS protocols.
XML
Restrict Fetching of External XML Resources
Enhance the JAXP APIs to add the ability to restrict the set of network protocols that may be used to fetch external resources.
Platform
Compact Profiles
Define a few subset Profiles of the Java SE Platform Specification so that applications that do not require the entire Platform can be deployed and run on small devices.
Prepare for Modularization
Undertake changes to smooth the eventual transition to modules in a future release, provide new tools to help developers prepare for the modular platform, and deprecate certain APIs that are a significant impediment to modularization.
7
APIs proposed for removal 

Exploratory work toward the modular Java SE Platform in Project Jigsaw has identified a small number of problematic API dependences that will be a significant impediment to the clean modularization of the Platform in a future release.

The methods at which these dependences originate are:

The difficulty with these methods is that they require the modules that contain the java.util.logging and java.util.jar packages to depend upon the module that contains the java.beans package, which in turn depends upon the (very large) module that contains the java.awt package. Thus any application that uses the core logging or JAR-file APIs could only run on a configuration of the Platform that includes the AWT APIs, which is clearly undesirable.

An automated analysis of a large corpus of Java library and application code, including the entire content of Maven Central as of September 2012, suggests that these methods are hardly ever used. Following the process for removing APIs established in Java SE 6, the above methods will be deprecated in Java SE 8 and proposed for removal from the Platform in a future release.

8
Profiles 

This Specification introduces the concept of a Java SE Profile, which is a well-defined subset of the Java SE Platform. Profiles allow applications that use just part of the Platform to run on resource-constrained devices. An application that, e.g., does not use the Swing/AWT/2D graphics stack can achieve considerable space savings by running on a Profile that does not include an implementation of those APIs.

This feature is intended to enable the migration of applications currently built on the Java ME Connected Device Configuration (CDC) to appropriate Profiles of the Java SE Platform. It can thus be seen as part of the long-term effort to converge CDC with the Java SE Platform, and is included in this Specification in light of the deferral of a full module system to a future release.

A Java SE Profile is not a Profile Specification as defined in the Java Community Process. This Specification does not define rules by which separate JSR Specifications can define Profile Specifications based upon this Specification.

Constraints A Profile is subject to five constraints:

  1. A Profile must implement the entire Java Virtual Machine Specification that is part of this Specification. The Virtual Machine itself is not subject to subsetting.

  2. A Profile must implement the entire Java Language Specification that is part of this Specification. The language itself is not subject to subsetting.

  3. A Profile must be specified as a list of packages. The content of a package in a Profile must be identical to the content of the package of the same name in the complete Java SE Platform, unless explicitly specified otherwise.

  4. A Profile may be specified as being larger than some other Profile, in which case the larger Profile must contain all of the packages specified in the smaller Profile.

  5. The smallest Profile must be specified to contain all of the packages containing the classes and interfaces mentioned in normative text in the Java Language Specification.

The complete Java SE Platform is not itself considered a Profile.

Content This Specification defines three Profiles: compact1, compact2, and compact3. compact3 is larger than compact2, and compact2 is larger than compact1. The packages added in each Profile are as follows:

compact1compact2compact3
java.iojava.rmijava.lang.instrument
java.langjava.rmi.activationjava.lang.management
java.lang.annotationjava.rmi.dgcjava.security.acl
java.lang.invokejava.rmi.registryjava.util.prefs
java.lang.refjava.rmi.serverjavax.annotation.processing
java.lang.reflectjava.sqljavax.lang.model
java.mathjavax.rmi.ssljavax.lang.model.element
java.netjavax.sqljavax.lang.model.type
java.niojavax.transactionjavax.lang.model.util
java.nio.channelsjavax.transaction.xajavax.management
java.nio.channels.spijavax.xmljavax.management.loading
java.nio.charsetjavax.xml.datatypejavax.management.modelmbean
java.nio.charset.spijavax.xml.namespacejavax.management.monitor
java.nio.filejavax.xml.parsersjavax.management.openmbean
java.nio.file.attributejavax.xml.streamjavax.management.relation
java.nio.file.spijavax.xml.stream.eventsjavax.management.remote
java.securityjavax.xml.stream.utiljavax.management.remote.rmi
java.security.certjavax.xml.transformjavax.management.timer
java.security.interfacesjavax.xml.transform.domjavax.naming
java.security.specjavax.xml.transform.saxjavax.naming.directory
java.textjavax.xml.transform.staxjavax.naming.event
java.text.spijavax.xml.transform.streamjavax.naming.ldap
java.timejavax.xml.validationjavax.naming.spi
java.time.chronojavax.xml.xpathjavax.security.auth.kerberos
java.time.formatorg.w3c.domjavax.security.sasl
java.time.temporalorg.w3c.dom.bootstrapjavax.sql.rowset
java.time.zoneorg.w3c.dom.eventsjavax.sql.rowset.serial
java.utilorg.w3c.dom.lsjavax.sql.rowset.spi
java.util.concurrentorg.xml.saxjavax.tools
java.util.concurrent.atomicorg.xml.sax.extjavax.xml.crypto
java.util.concurrent.locksorg.xml.sax.helpersjavax.xml.crypto.dom
java.util.functionjavax.xml.crypto.dsig
java.util.jarjavax.xml.crypto.dsig.dom
java.util.loggingjavax.xml.crypto.dsig.keyinfo
java.util.regexjavax.xml.crypto.dsig.spec
java.util.spiorg.ietf.jgss
java.util.stream
java.util.zip
javax.crypto
javax.crypto.interfaces
javax.crypto.spec
javax.net
javax.net.ssl
javax.script
javax.security.auth
javax.security.auth.callback
javax.security.auth.login
javax.security.auth.spi
javax.security.auth.x500
javax.security.cert

The content of each package in these Profiles is identical to the content of the package of the same name in the complete Java SE Platform, except that the problematic APIs proposed for removal in a future release are not present in any of the Profiles, for the same reasons.

The above lists include new packages defined in the Component JSR Specifications. The Profile membership of each class, interface, and package will also be specified in the complete Javadoc API specification.

It is expected that the modular Platform to be defined in a future release will include modules corresponding almost exactly to the Profiles defined here, so that applications that use Profiles can easily be migrated to use modules. It is further expected that these Profiles will be deprecated at that time, so that they can be removed in an even later release.

Rationale The content of each Profile is motivated as follows:

Conformance Implementors of this Specification are free to implement zero, one, or more Profiles. They are also free to implement one or more Profiles without implementing the entire Platform. The Technology Compatibility Kit (TCK) for this Specification will be structured so as to allow the conformance of an Implementation of any Profile, or of the entire Platform, to be tested. A Reference Implementation (RI) will be provided for each Profile, and for the entire Platform.

If an Implementation of this Specification implements a Profile then it must be complete, i.e., it must implement every API element of that Profile. If an Implementation implements the entire Platform then it must implement every API element of the Platform. No other forms of Implementation are permitted, except as defined in the next section.

9
Stripped Implementations 

Past releases of the Java SE Platform required Implementations to be complete in all circumstances. That is, removing elements of an Implementation after the Implementation is validated against the TCK was not permitted. This constraint has been a key to the long-term success of the Platform because it has helped to ensure the portability of Java library and application code to different Implementations.

As a consequence of this constraint, an application that was packaged together with an Implementation was required to include the entire Implementation even if it used only a small part of the Platform. This limited the Platform’s utility in scenarios where space is at an extreme premium.

This Specification therefore permits an Implementation that is packaged together with all of the Java library and application code that will ever run upon it to omit, partially or entirely, elements that are never, under any circumstances, depended upon by that code. The process that creates such an Implementation is called stripping, and the resulting Implementation is said to be Stripped.

The elements subject to removal by the stripping process may be Java code, in the form of packages, classes, interfaces, fields, or methods. They may also be other kinds of implementation elements, in the form of static data files or native-code procedures, objects, or libraries.

Constraints A Stripped Implementation must satisfy the following constraints:

  1. The Implementation provided as input to the stripping process must conform to the Specification. It may implement additional JSR Specifications, in which case stripping may also apply to those components unless explicitly prohibited by their respective Specifications. The input Implementation need not include elements defined as optional by the relevant Specifications.

  2. A Stripped Implementation, once created, cannot be changed. No further elements may be added or removed.

  3. The Java library and application code provided as input to the stripping process may be transformed by that process, but after the process is complete the code cannot be changed. No further code in any form may be added or removed.

  4. A Stripped Implementation is forever bound to the Java library and application code provided as input to the same invocation of the stripping process. A Stripped Implementation may not be used to execute any other library or application code. Elements of a Stripped Implementation may not in any way be referenced by any other library or application code.

  5. The stripping process must preserve the functionality and behavior of the input Implementation and of the input Java library and application code. An element, whether optional or not, that is present in the input Implementation and is used by the input library or application code must also be present in the Stripped Implementation. The library and application code packaged together with a Stripped Implementation must behave identically to the input library and application code running on the input Implementation.

Implementation This Specification neither mandates nor forbids any particular means of creating Stripped Implementations, so long as the above constraints are satisfied. At a high level, a Stripped Implementation can be created in two steps:

  1. Analyze the combined Implementation, library, and application code to identify elements that are never used, either directly or indirectly.

  2. Remove the unused elements from the combined code and package all of the remaining code into a single binary image.

A precise answer for the first step cannot, in general, be computed automatically since it is equivalent to solving the Halting Problem. Practical tools for creating Stripped Implementations therefore usually rely upon a combination of heuristics, manual analysis, and automatic analysis to compute an approximate answer. It is highly recommended that the binary image created in the second step be fully tested, with the goal of achieving 100% coverage of the remaining library and application code, in order to ensure that all required elements of the Implementation are present.