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

hg: jdk8/tl/jdk: 8006182: cleanup to use java.util.Base64 in java security component, providers, and regression tests

[chris . hegarty]

Changeset: 9078c34437ab
Author:msheppar
Date:  2013-02-21 20:01 +
URL:   http://hg.openjdk.java.net/jdk8/tl/jdk/rev/9078c34437ab

8006182: cleanup to use java.util.Base64 in java security component, providers, 
and regression tests
Summary: Refactored code to use java.util.Base64 Mime Encoder and Decoder as a 
replacement for sun.misc.BASE64Encoder and sun.misc.BASE64Decoder
Reviewed-by: vinnie, chegar, sherman

! src/share/classes/sun/security/pkcs10/PKCS10.java
! src/share/classes/sun/security/provider/X509Factory.java
! src/share/classes/sun/security/tools/jarsigner/Main.java
! src/share/classes/sun/security/tools/keytool/Main.java
! src/share/classes/sun/security/util/ManifestEntryVerifier.java
! src/share/classes/sun/security/util/SignatureFileVerifier.java
! src/share/classes/sun/security/x509/X509CertImpl.java
! src/share/classes/sun/tools/jar/Manifest.java
! src/share/classes/sun/tools/jar/SignatureFile.java
! test/javax/security/auth/kerberos/KerberosTixDateTest.java
! test/sun/security/krb5/auto/HttpNegotiateServer.java
! 
test/sun/security/ssl/com/sun/net/ssl/internal/ssl/SSLContextImpl/MD2InTrustAnchor.java
! 
test/sun/security/ssl/com/sun/net/ssl/internal/ssl/SSLContextImpl/TrustTrustedCert.java
! 
test/sun/security/ssl/com/sun/net/ssl/internal/ssl/X509TrustManagerImpl/BasicConstraints.java
! 
test/sun/security/ssl/com/sun/net/ssl/internal/ssl/X509TrustManagerImpl/SelfIssuedCert.java
! 
test/sun/security/ssl/com/sun/net/ssl/internal/www/protocol/https/HttpsClient/ProxyTunnelServer.java
! test/sun/security/ssl/javax/net/ssl/ServerName/SSLSocketSNISensitive.java
! test/sun/security/ssl/javax/net/ssl/TLSv12/DisabledShortRSAKeys.java
! test/sun/security/ssl/javax/net/ssl/TLSv12/ShortRSAKey512.java
! 
test/sun/security/ssl/sun/net/www/protocol/https/HttpsURLConnection/ProxyTunnelServer.java

hg: jdk8/tl/langtools: 8008337: Write test to check for compiler error when static method in interface is called via super()

[maurizio . cimadamore]

Changeset: 8e82e4f225e4
Author:mcimadamore
Date:  2013-02-22 13:31 +
URL:   http://hg.openjdk.java.net/jdk8/tl/langtools/rev/8e82e4f225e4

8008337: Write test to check for compiler error when static method in interface 
is called via super()
Reviewed-by: mcimadamore
Contributed-by: sonali.g...@oracle.com

+ test/tools/javac/lambda/StaticMethodNegTest.java
+ test/tools/javac/lambda/StaticMethodNegTest.out

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?

hg: jdk8/tl/jdk: 8008290: (profiles) Startup regression due to additional checking of JAR file manifests

[alan . bateman]

Changeset: 63fe6a9820b6
Author:alanb
Date:  2013-02-22 14:04 +
URL:   http://hg.openjdk.java.net/jdk8/tl/jdk/rev/63fe6a9820b6

8008290: (profiles) Startup regression due to additional checking of JAR file 
manifests
Reviewed-by: lancea, chegar, iris, mchung, sherman

! src/share/classes/java/util/jar/JarFile.java
! src/share/classes/java/util/jar/JavaUtilJarAccessImpl.java
! src/share/classes/sun/misc/JavaUtilJarAccess.java
! src/share/classes/sun/misc/URLClassPath.java

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

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

hg: jdk8/tl/jdk: 2 new changesets

[lance . andersen]

Changeset: 9f9dac5a9e74
Author:lancea
Date:  2013-02-22 09:29 -0500
URL:   http://hg.openjdk.java.net/jdk8/tl/jdk/rev/9f9dac5a9e74

8008716: address typo in CallableStatement javadocs
Reviewed-by: chegar

! src/share/classes/java/sql/CallableStatement.java

Changeset: 8d8a35ac7d40
Author:lancea
Date:  2013-02-22 09:58 -0500
URL:   http://hg.openjdk.java.net/jdk8/tl/jdk/rev/8d8a35ac7d40

Merge

hg: jdk8/tl/langtools: 8008708: Regression: separate compilation causes crash in wildcards inference logic

[maurizio . cimadamore]

Changeset: 94e67bed460d
Author:mcimadamore
Date:  2013-02-22 18:19 +
URL:   http://hg.openjdk.java.net/jdk8/tl/langtools/rev/94e67bed460d

8008708: Regression: separate compilation causes crash in wildcards inference 
logic
Summary: Invalid use of WildcardType.bound in Types.removeWildcards
Reviewed-by: jjg

! src/share/classes/com/sun/tools/javac/code/Types.java
+ test/tools/javac/lambda/separate/Foo.java
+ test/tools/javac/lambda/separate/Test.java

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

[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 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