JEP 179: Document JDK API Support and Stability
|Author||Joseph D. Darcy|
|Status||Closed / Delivered|
|Discussion||core dash libs dash dev at openjdk dot java dot net|
|Reviewed by||Alan Bateman|
|Endorsed by||Mark Reinhold|
|Depends||JEP 162: Prepare for Modularization|
There is a long-standing shortcoming in the JDK in terms of clearly
specifying the support and stability usage contract for
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
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.
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.
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
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
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.
This feature builds on the investigations conducted for JEP 162, Prepare for Modularization.
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
@Documentedand thus be included as part of any generated javadoc bundles.
TCK: Since this proposal is outside of Java SE, there is no TCK impact.