@Supported design issues (original) (raw)
mark.reinhold at oracle.com mark.reinhold at oracle.com
Fri Feb 22 23:04:26 UTC 2013
- Previous message: 8008662: Add @jdk.Supported to JDK-specific/supported API
- Next message: @Supported design issues
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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?
Is the "supportedness" of a package inherited by its sub-packages?
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? 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.
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.
The retention policy of the annotation is RUNTIME. Is that really what we want? I'd have expected CLASS.
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.
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.
- Mark
[1] http://docs.oracle.com/cd/E19082-01/819-3620/chp-stab-1/index.html
- Previous message: 8008662: Add @jdk.Supported to JDK-specific/supported API
- Next message: @Supported design issues
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]