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

[Joe Darcy]

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.darcy at oracle.com 
> <mailto:joe.darcy at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/net-dev/attachments/20130222/1b9c8c9c/attachment.html