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

[Joe Darcy]

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: 
http://docs.oracle.com/javase/7/docs/jdk/api/javac/tree/index.html
     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 
referenced.

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.

Cheers,

-Joe

[1] 
http://cr.openjdk.java.net/~darcy/OpenJdkDevGuide/OpenJdkDevelopersGuide.v0.777.html#general_evolution_policy

[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