8008662: Add @jdk.Supported to JDK-specific/supported API
joe.darcy at oracle.com
Fri Feb 22 22:09:18 UTC 2013
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
> 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.
More information about the core-libs-dev