@Supported design issues

[Joe Darcy]

On 2/22/2013 3:04 PM, mark.reinhold at oracle.com wrote:
> I understand (deeply!) the problem that @Supported is trying to solve.
> Martin has raised a number of good questions about it already.  Here are
> some additional concerns I'd like to see addressed before we use it any
> further in our source code.  (I've been unable to find any earlier
> discussion or code review of this new annotation in the archives, but
> maybe I missed it.)
>
>    - The annotation isn't a simple marker annotation, which is what I
>      expected at first glance; it takes a boolean parameter.  Does this
>      mean that we have to go add "@Supported(false)" to everything that's
>      not supported?  I'd have thought that anything not marked
>      "@Supported(true)" would by implication, well, not be supported.
>      Does it mean that if I mark a package "@Supported(true)" I can use
>      "@Supported(false)" on some of its member types?

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.

We already have types in the JDK whose comments explicitly say "this is 
not part of any supported API" (much of javac).
If there is no explicit opt-in to mark supportedness as well as 
non-supportedness in my estimation that means the status of all the 
unadorned APIs is uncertain: "Perhaps this interesting API was just 
overlooked in being marked supported, I'll go ahead and us it anyway..."


>
>    - Is the "supportedness" of a package inherited by its sub-packages?

No; for at least two reasons. First, annotation inheritance is only 
defined to work for classes along the superclass chain; there is no 
defined inheritance of annotations on methods or from superinterfaces. 
Second, subpackages of a package can have at most a tenuous logical 
relationship to the parent package (and they have no additional 
language-level access). For example, javax.annotation.processing added 
by JSR 269 is not really at all related to javax.annotation added by JSR 
250.

>
>    - The name "Supported" is problematic.  It begs the question,
>      "Supported by whom?"  Maybe the annotation should take URL and
>      phone-number parameters so that you know where to go when you run
>      into a problem?

I would trust that users of a JDK distribution would by default turn to 
the provider of their distribution for support, or barring that, 
stackoverflow.


> A name that captures a more inherent property of
>      the API unit being annotated would avoid this.  Perhaps "@Stable"?


>
>    - I agree with Martin that "supportedness", in the abstract, isn't a
>      binary thing.  If we're going to define an annotation for broad use
>      then we should at least consider a metric with more than two values.
>      I'm not saying we should replicate all the detail of the Solaris
>      stability taxonomy [1], but we should at least discuss whether it's
>      worth doing something along those lines, if simpler.  I think it'd
>      be particularly valuable to be able to distinguish between at least
>      four levels:
>
>        - Supported and stable (i.e., will only evolve compatibly) until
>          we tell you it's going to go away (or change incompatibly), and
>          we'll give you at least one feature-release cycle's notice.
>
>        - Supported in this feature release, but it might go away or
>          change incompatibly in the next, with best-effort notice.
>
>        - Supported in this update release, but evolving rapidly, with
>          changes announced only in release notes.
>
>        - Internal to the JDK, expect to get burned if you use it.

The status quo today and for the last 15 years has been often sloppy 
management of the types in com.sun.* Some of them are 
supported/stable/official/whatever others are not. Which are which is 
not clear. The closest mechanism to documenting this, aside what 
whatever comments might be in the code and the few subsets with 
published javadoc, are whether or not the types ends up in ct.sym 
proto-module system and if it does, whether or not a warning is issued 
when using the type.

The ct.sym file is constructed by passing information from the docs make 
target to a program living in the langtools repo. So today the mechanism 
we have is a very an obscure system that does a poor job of conveying 
this kind of information and is easy to circumvent.

If we go from that obscure system to an explicit boolean-valued 
annotation, that is in my estimation a vast improvement both in clarity 
and usability.

>
>      These are, more or less, the Solaris "Stable", "Evolving",
>      "Unstable", and "Internal" levels, which suggests a single
>      "@Stability" annotation and an enum parameter with the values
>      STABLE, EVOLVING, UNSTABLE, and INTERNAL.

As I indicated earlier in this thread, I agree there are more subtle 
distinctions that can be of interest, but at times the better is the 
enemy of the good and the first approximation of is this type or package 
supported or not is a huge improvement of what we have today even if it 
doesn't cover all the possible gradations.

>
>    - The retention policy of the annotation is RUNTIME.  Is that really
>      what we want?  I'd have expected CLASS.

CLASS is not very helpful (and certainly not a helpful default). A 
CLASS-retention annotation can be reliably used at the compile-time of 
other code. For the use case of Supported, I think it is more helpful to 
allow runtime querying of the property.

>
>    - The annotation is in the top-level "jdk" package.  What's the
>      rationale for this?  I'd have expected it to be defined in
>      "jdk.annotations", so that if and when other JDK-specific
>      annotations arise we have one convenient place to find them,
>      and only them.

There are 81 subtypes of java.lang.annotation.Annotation listed in JDK 8 b77

There are four packages with "annotation" as the last component of their 
name in the main JDK javadoc bundle:

* java.lang.annotation - types supporting the annotations language feature
     + 6 annotation types
     + 1 interface, 2 enum types, 4 throwables

* javax.annotation - JSR 250's " Common Annotations for the Java Platform"
     + 5 annotation types
     + 1 enum

* javax.tools.annotation - defines a single annotation used by javah 
functionality (probably should get a new home)
     + 1 annotation type

* javax.xml.bind.annotation
     + 30 annotation types
     + 1 interface, 6 classes, 3 enum types

That gives a total of 42 annotation types defined in packages ending 
with "annotation" or about half of them. However, I would discount 
java.lang.annotation and javax.xml.bind.annotation as outliers, in which 
case most JDK annotations are *not* in a dedicated package.

I think it is usually not helpful to segregate annotation types into 
dedicated packages, after all we don't have "enums", "interfaces", and 
"classes" packages and there are nearly as many annotations defined 
directly in java.lang (SuppressWarnings, Deprecated, Override, 
SafeVarargs, etc.) as in java.lang.annotation. As one example, the 
annotation types defined in javax.annotation.processing relate directly 
to annotation processing and are thus in the same package as and quite 
at home next to the other types related to annotation processing.


>
> Finally, this annotation is intended for use throughout our code base,
> and will be of interest not just to people working on the JDK but also
> to people using it.  Its syntax, semantics, and intended usage should
> hence be documented in a JEP, which will be much more visible than an
> obscure Javadoc page.

The listed criteria for a JEP are:

>     It requires two or more weeks of engineering effort,
>
>     It makes a significant change to the JDK, or to the processes and 
> infrastructure by which it is developed, or
>
>     It is in high demand by developers or customers.

Perhaps excluding this email thread, the first condition does not hold 
for this work and the second two conditions are debatable. In addition, 
this work is a direct outgrowth of the  pre-modularization work going on 
under

     JEP 162: Prepare for Modularization
     http://openjdk.java.net/jeps/162

Given the apparent heightened  interest in this topic, I trust that if a 
JEP for this is sent in, it will be promptly published in the JEP index.

-Joe