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](JDK-8046152).


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_](JDK-8046152).


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.