On 03/15/2013 02:12 PM, mark.reinh...@oracle.com wrote:
2013/3/4 2:58 -0800, joe.da...@oracle.com:
On 02/28/2013 11:31 AM, mark.reinh...@oracle.com wrote:
2013/2/23 5:10 -0800, joe.da...@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
