@Supported design issues (original) (raw)

mark.reinhold at oracle.com mark.reinhold at oracle.com
Tue Mar 19 20:09:01 UTC 2013

2013/3/15 17:16 -0400, joe.darcy at oracle.com:

On 03/15/2013 02:12 PM, mark.reinhold at oracle.com wrote:

...

What I'm trying to understand is, for a JDK API that's @Supported(true) in one or more releases, what's the recommended protocol for removing it? Perhaps something like this? @Supported(true) @Supported(true) @Deprecated @Supported(false) (Time flows downward.) Or does @Supported(false) happen when @Deprecated is applied? Or will usage vary? The general threshold we've been using to apply @Deprecated is that a API must be actively harmful rather than just ill-advised. However, a few methods have been deprecated in Java SE 8 because they are slated for removal in 9 as part of modularization. I would favor a shorter sequence of either @Supported(true) @Supported(false) @Deprecated or even just @Supported(true) @Supported(false) since using the API may not be harmful per se, other than risky in the sense the API is going away in the future.

Agreed -- that's the key distinction: "Harmful" != "going away".

...

Since types have a more concrete existence then packages, I regard the jdk.Supported information on package-info files to have a higher mixture of informative versus normative sentiment compared to the annotation on types. If we're going to go to the trouble of defining an annotation for this, and then sprinkle that annotation throughout our code, shouldn't we give it as precise a meaning as possible? It'd be a shame for @Supported (or whatever it turns out to be) to have no more authoritative value than, say, the @since javadoc tag. The main point I was making here is that package-info information has a less concrete existence than information about types, because, for example, it is possible to configure a build so that multiple package-info files exist for the same package (the jdk docs build gives a warning about this situation for some XML-processing code).

Ah, yes, there's that wrinkle. I still think, though, that we should strive to give these new annotations as precise a semantics as possible, and also use them as precisely as possible.

...

Since any jdk.Supported annotations applied to types are more localized and more specific ("this type is or is not supported / stable / etc.") it is both easier for JDK developers to made incremental changes to the JDK code base and is it also easier for users of those types to see what is going on since any inspection of the types can reveal the annotation value. Agreed, but I was trying to understand how the annotation-based system would be harder to "cirvumvent", at either compile time or run time. It is harder to plead ignorance of the supported status of the API since any inspection of it can reveal the annotation whereas a single change in the javac command line can silence all ct.sym warnings.

Okay. I took the word "cirvumvent" to mean that you had some additional automatic enforcement mechanism in mind.

More information about the core-libs-dev mailing list