2013/3/15 17:16 -0400, joe.da...@oracle.com:
> On 03/15/2013 02:12 PM, mark.reinh...@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
