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
