8008662: Add @jdk.Supported to JDK-specific/supported API

Joe Darcy 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 [1] 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 [1] 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 7: 
     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. [2] 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.




[2] http://hg.openjdk.java.net/jdk8/tl/langtools/rev/011cf7e0a148

> - 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:
> http://cr.openjdk.java.net/~alanb/8008662/webrev/
> 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.
> -Alan
> [1] http://hg.openjdk.java.net/jdk8/tl/langtools/rev/55cca2f38ee6

More information about the core-libs-dev mailing list