@Supported design issues

[Joe Darcy]

On 03/15/2013 02:12 PM, mark.reinhold at oracle.com wrote:
> 2013/3/4 2:58 -0800, joe.darcy at oracle.com:
>> On 02/28/2013 11:31 AM, mark.reinhold at oracle.com wrote:
>>> 2013/2/23 5:10 -0800, joe.darcy at oracle.com:
>>>> Having Supported take a boolean value both allows the explicit statement
>>>> that an item is not supported as well as providing a possible transition
>>>> path from Supported(true) to Supported(false) to removed.
>>> Okay.  In that scenario what's the role of the existing @Deprecated
>>> annotation?
>> @Deprecated generally applies to all clients of an API. I don't think
>> people tend to associate potential removal of an API with deprecation
>> because we haven't (yet) removed any deprecated Java SE APIs from the
>> platform since to date we have placed a higher value on preserving
>> binary compatibility.
> I'm continually surprised by developers I meet at conferences who
> (sometimes angrily) demand that deprecated APIs be removed, so I think
> the reality is a mixed bag -- not that it matters a great deal either
> way.
>
> 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.

Using deprecation for the apt API was appropriate since that was the 
only documentation convention and warning-producing mechanism in place 
at the time. Deprecating the listener methods in pack200 in Java SE 8 is 
appropriate since they are Java SE API elements and not (JDK - Java SE) 
API elements.

However, if we have a sufficiently rich supported/stable annotation, we 
might not need to combine usage of that annotation with @Deprecated.


[snip]

>
>>> ...
>>>
>>> I'm still wondering whether marking a package "@Supported(true)" means
>>> that I can use "@Supported(false)" on some of its member types.  That
>>> would be convenient for cases such as the JMX OSMBeanFactory class that
>>> Alan mentioned.
>> If a package has a mixture of supported and non-supported types, I would
>> say it should either *not* have a @jdk.Supported annotation itself, or
>> if the types in the package were predominately one value or another,
>> then the package annotation should match the prevailing value of the types.
>>
>> 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).


>
>>>> ...
>>> What I don't understand is how doing all this with an annotation would
>>> be any harder to circumvent than what we have today.  Are you proposing
>>> to do something stronger than issue a compiler warning when people try
>>> to use an unsupported API?
>> The ct.sym mechanism we have today is compile-time only and the
>> mechanism and all its warnings can be circumvented by adding a single
>> option to javac; the option is described on stackoverflow, amongst other
>> places. Therefore, it is fairly easy for someone to claim "but I didn't
>> know" in regards to the status of a JDK-specific API.
> Well, sure.
>
>> 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.

Cheers,

-Joe