Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
Thank you Alan, this will clear up a lot of issues surrounding these API's. I skimmed over the changes, paying particular attention to the httpserver and sctp packages. -Chris. On 02/21/2013 06:46 PM, 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: - 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
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
The security related ones look ok to me. --Sean On 02/21/2013 01:46 PM, 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: - 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
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
On 22/02/2013 14:06, Martin Buchholz wrote: I was under the impression that the general rule was that all of com.sun.* fell under the jdk supported umbrella, and the level of support was the distinction between sun.com.* and sun.* . com.sun is a mixed bag. There are lots of com.sun.*.internal that are clearly JDK internal/implementation/stay-away but several useful and documented APIs are in com.sun too (the JDK build generates the javadoc for these). In addition there are several APIs with murkier pasts, transitional APIs for areas that previous had a life as a standalone technology before coming into the JDK. -Alan.
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
Hi Joe, On Fri, Feb 22, 2013 at 11:19 AM, Joe Darcy joe.da...@oracle.com wrote: Should third-party vendor extensions that are supported for public use by the third-party use jdk.Supported? No; as I envision it, the jdk.Supported annotation is only meant to convey supported-ness in the JDK of parts of the JDK. Depends on what you mean by JDK. Suppose the icedtea project added a public supported method usesSystemZlib(). It would be good to provide guidance what package to put this in (org.classpath.* ?) and how to indicate level of support (by the icedtea project). Suppose the IcedTea project decided to officially support sun.misc.Unsafe. Would they do this by adding jdk.Supported annotation to their version of Unsafe.java, even if their upstream chose not to? What about the X's in hotspot flags and the java tools command line interfaces? The policy around command line interfaces is unchanged; the interfaces are mostly stable, but the more X's are in a flags name, the less stable it can be. We all learned this by indoctrination from the local sensei greybeard, but where is it documented for the wider world? Perhaps Supported isn't a binary thing, but needs to capture different levels of support? Solaris has had such support levels. A beta (laba, experimental) support level is very useful for introducing new technology. It's a very hard problem, especially in a 1000 flowers world.
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
Hi Martin, On 2/22/2013 1:40 PM, Martin Buchholz wrote: Hi Joe, On Fri, Feb 22, 2013 at 11:19 AM, Joe Darcy joe.da...@oracle.com mailto:joe.da...@oracle.com wrote: Should third-party vendor extensions that are supported for public use by the third-party use jdk.Supported? No; as I envision it, the jdk.Supported annotation is only meant to convey supported-ness in the JDK of parts of the JDK. Depends on what you mean by JDK. Suppose the icedtea project added a public supported method usesSystemZlib(). It would be good to provide guidance what package to put this in (org.classpath.* ?) and how to indicate level of support (by the icedtea project). Suppose the IcedTea project decided to officially support sun.misc.Unsafe. Would they do this by adding jdk.Supported annotation to their version of Unsafe.java, even if their upstream chose not to? For some definition of JDK, IcedTea is JDK too since they provide a JDK distribution, one at least a little distinct from plain OpenJDK and also distinct from OracleJDK. The long-standing problem I wanted to address was clearly indicating whether or not the upstream code in shared JDK 8 sources was regarded as a public API or not. So I don't think it would necessarily be inappropriate for a hypothetical org.classpath type to use jdk.Supported, but I wasn't really thinking about that use case. What about the X's in hotspot flags and the java tools command line interfaces? The policy around command line interfaces is unchanged; the interfaces are mostly stable, but the more X's are in a flags name, the less stable it can be. We all learned this by indoctrination from the local sensei greybeard, but where is it documented for the wider world? There is some approximation to that guidance in the java man page; options without a X prefix are described as standard and ones with at least one X are described as non-standard. Not all XX options are included in the man page. Perhaps Supported isn't a binary thing, but needs to capture different levels of support? Solaris has had such support levels. A beta (laba, experimental) support level is very useful for introducing new technology. It's a very hard problem, especially in a 1000 flowers world. Yes, I'm vaguely aware that Solaris has had a rich taxonomy in this space and there are, IIRC, dtrace tools to audit if you are calling any sufficient unapproved APIs. However, at least as a first cut, I think a binary supported / not-supported distinction captures at least 80% of the distinction that needs to be made for the purposes of the JDK. Anything more involves much less favorable complexity vs benefit trade-offs. -Joe
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
Well, that was quite a few files to have to go through :-) Looks fine On Feb 21, 2013, at 1:46 PM, 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: - 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 Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037 Oracle Java Engineering 1 Network Drive Burlington, MA 01803 lance.ander...@oracle.com
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
On 2/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. It's nice to be able to mark what is supported vs unsupported in the com.sun namespace since there are a mix of supported and unsupported APIs. [...] The webrev with the changes is here: http://cr.openjdk.java.net/~alanb/8008662/webrev/ Looks good to me. 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. I wasn't aware of the unsupported com.sun.management.OSMBeanFactory class being included in the javadoc. I think that can be fixed and I'll file a bug and hopefully we can clean that up. Mandy 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
Re: 8008662: Add @jdk.Supported to JDK-specific/supported API
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
