JEP 179: Document JDK API Support and Stability

Summary

There is a long-standing shortcoming in the JDK in terms of clearly specifying the support and stability usage contract for com.sun.* types and other types shipped with the JDK that are outside of the Java SE specification. These contracts and potential evolution policies should be clearly captured both in the source code of the types and in the resulting class files. This information can be modeled with JDK-specific annotation types.

Goals

The primary goals of this proposal are to capture the results of the pre-modularization investigations around the status of these APIs and to make that information clearer to the maintainers of the JDK and developers using the JDK.

Marking an API as usable by certain parties, but not generally usable, could also be helpful.

Non-Goals

The expected implementation mechanism to store the API status information is one or more annotation types with supporting types for modeling, such as enums. These types are intended for use in the JDK. If they are useful outside of the JDK that is a happy outcome, but, for instance, designing a very general-purpose classification scheme with very fine gradations of stability levels is out of scope for this effort.

Motivation

In addition to implementing Java SE APIs, the JDK code base contains sources for, and JDK distributions ship with, other APIs outside of the Java SE specification and in different namespaces. Some of those JDK APIs enjoy a similar general evolution policy as Java SE APIs; the APIs are usable for general development, supported by the JDK provider, stable, and evolve in a largely compatible fashion. Other APIs included in the JDK are intended only for use in the JDK implementation itself and should not be relied on by third parties. The com.sun.* namespace used by the JDK includes a mixture of these "supported" and "not-supported" APIs. This JEP proposes to record information about supported-ness and related properties of interest in the sources of the types and packages in question. Recording this information will make the status of the API clearer and more explicit, including in generated javadoc, and also allow tooling to programmatically check for inappropriate usage. The recording of this information should be addressed by a small incremental effort over and above the modularity preparation already being done for JDK 8 in JEP 162.

Description

The annotations and supporting types used to document the status the APIs of interest will reside in the jdk.* namespace. In other words, these types will be part of the JDK and not part of Java SE. Besides new types added in jdk.* itself, the annotations are expected to mostly be used on types in the legacy com.sun.* namespace. Some exploration and experimentation is expected before the final set of API distinctions is determined. The initial jdk.Supported annotation type, which was already pushed into JDK 8 to allow trial usage, allows a boolean supported/not-supported classification. Other possible classifications of interest include JRE vs JDK, supported outside of the JDK only for certain users/groups, and stability/evolution policy gradations.

In following the don't-repeat-yourself principle, ultimately the JDK build should be modified to construct the ct.sym proto-module system information from annotations on sources rather than obscurely relying on the docs makefile, but such a build refactoring is not a strictly necessary part of this effort.

Risks and Assumptions

If the annotations of this feature are initially designed to only capture a yes/no value of some sort as a boolean and in the future having more classifications is deemed necessary, it may be awkward to evolve the initial type(s) to model the new scheme. Therefore, care should be taken in JDK 8 to determine a durable set of distinctions.

Dependences

This feature builds on the investigations conducted for JEP 162, Prepare for Modularization.

Impact

• Other JDK components: The concepts used for the annotations of this proposal may help formalize policies in other parts of the JDK, but the effort is focused on helping to manage the non-Java SE APIs.

• Compatibility: The feature will allow compatibility policies to be better documented and enforced.

• Documentation: The new annotations will be @Documented and thus be included as part of any generated javadoc bundles.

• TCK: Since this proposal is outside of Java SE, there is no TCK impact.