Re: 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 > 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

[Martin Buchholz]

Hi Joe,

On Fri, Feb 22, 2013 at 11:19 AM, Joe Darcy  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

[Joe Darcy]

Hi Martin,

On 2/22/2013 6:06 AM, Martin Buchholz wrote:



On Thu, Feb 21, 2013 at 6:16 PM, Joe Darcy > wrote:



However, the com.sun.* subpackages are a mix of APIs that are
supported as described above as well as APIs that are not supported.


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.* .


Alan has previously replied on the varied supported-ness found in com.sun.*.



In any case, it would be good if there was a single canonical place 
that documented the various levels of support with subtle 
distinctions, including java.* vs. javax.*, endorsed standards, 
com.sun.* vs. sun.* vs. jdk.*, and recommendations for where 
non-Oracle vendor extensions should go.  Is the jdk.Supported 
annotation itself part of Java SE?


No, the jdk.Supported annotation type is part of the JDK (currently 
living in the langtools repo):


http://hg.openjdk.java.net/jdk8/jdk8/langtools/file/56dfafbb9e1a/src/share/classes/jdk/Supported.java

As you can see, the jdk.Supported type itself has a @jdk.Supported 
annotation :-)


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.


 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.


-Joe

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

[Alan Bateman]

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

[Sean Mullan]

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

[Martin Buchholz]

On Thu, Feb 21, 2013 at 6:16 PM, Joe Darcy  wrote:

>
> However, the com.sun.* subpackages are a mix of APIs that are supported as
> described above as well as APIs that are not supported.


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.* .

In any case, it would be good if there was a single canonical place that
documented the various levels of support with subtle distinctions,
including java.* vs. javax.*, endorsed standards, com.sun.* vs. sun.* vs.
jdk.*, and recommendations for where non-Oracle vendor extensions should
go.  Is the jdk.Supported annotation itself part of Java SE?  Should
third-party vendor extensions that are "supported" for public use by the
third-party use jdk.Supported?  What about the X's in hotspot flags and the
java tools command line interfaces?

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

[Chris Hegarty]

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

[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

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

[Mandy Chung]

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

[Lance Andersen - Oracle]

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

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

[Alan Bateman]

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