8008662: Add @jdk.Supported to JDK-specific/supported API
joe.darcy at oracle.com
Fri Feb 22 02:16:54 UTC 2013
On 02/21/2013 10:46 AM, Alan Bateman wrote:
> Joe Darcy recently added @jdk.Supported  to make it possible to
> identify JDK-specific APIs.
> I'd like to add this to a number of APIs in the com.sun namespace to
> make it obvious these are "supported". Specifically I'm proposing to
> add it to:
To add some more context here, there are various APIs outside of the
Java SE namespaces (java.* and javax.*) that are shipped with the JDK.
Some of these APIs and meant to be called by normal users of the JDK and
evolve under essentially the same general evolution policy  as the SE
API. Call such non-SE APIs in the JDK "supported." One example of such a
supported API is the javac Tree API in com.sun.source.*
JDK 8: http://download.java.net/jdk8/docs/jdk/api/javac/tree/index.html
However, the com.sun.* subpackages are a mix of APIs that are supported
as described above as well as APIs that are not supported. APIs that are
not supported are *not* meant to be called by normal users of the JDK
and can have a very different evolution policy, up to and including
deletion from the JDK in a update release.
The goal of adding the @Supported annotations is to allow these API
categories to be more easily distinguished from each other, including
enabling tools to check that @Supported(value=false) APIs are not
The jdk.Supported annotation can be applied to both types and packages;
it is *not* intended to allow modeling of supported-ness down to only a
subset of methods of a type. In other words, if @jdk.Supported is
applied to something, it is meant to refer to the whole entity, either
all the parts of a type or all the types in a package. To make the
information more prominent and easier to find, I recommend applying the
annotation to both all the types in a package and the package itself,
which is what I've done in the tree API.  In Alan's case below, I
would not apply the annotation to a package if the package had a mix of
supported and unsupported types.
> - Java Debug Interface (com.sun.jdi)
> - Attach API (com.sun.tools.attach)
> - SCTP API (com.sun.nio.sctp)
> - HTTP server API (com.sun.net.httpserver)
> - Management extensions (com.sun.management)
> - JDK-specific API to JAAS (com.sun.security.auth)
> - JDK-specific JGSS API (com.sun.security.jgss)
> The javadoc for all of these is generated as part of the regular JDK
> "docs" build and so shouldn't be controversial. There are a number of
> other candidates in com.sun with murkier status that I've stayed clear
> of for now.
> The webrev with the changes is here:
> In a couple of cases the package description is legacy package.html so
> I've had to move/convert them to package-info.java.
> In all but one case I've added the annotation to the package-info, the
> one exception is com.sun.management where there is at least one type
> that is documented as "not supported". Joe Darcy might have
> suggestions on that.
> Otherwise this is mostly mechanical and the patch file is easier to
> review that the webrev.
>  http://hg.openjdk.java.net/jdk8/tl/langtools/rev/55cca2f38ee6
More information about the core-libs-dev