@Supported design issues

[mark.reinhold at oracle.com]

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)
>> <gone>
>> 
>> (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
>      <gone>
> 
> or even just
> 
>      @Supported(true)
>      @Supported(false)
>      <gone>
> 
> 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.

- Mark