Hello,
Following up on the earlier feedback, please review the patch below with
proposed clarifications to jdk.Exported.
Thanks,
-Joe
diff -r 7af634b1fc5b src/share/classes/jdk/Exported.java
--- a/src/share/classes/jdk/Exported.java Thu Oct 17 19:10:19 2013 -0700
+++ b/src/share/classes/jdk/Exported.java Thu Oct 17 22:44:07 2013 -0700
@@ -38,7 +38,25 @@
* com.sun.*} are official parts of the JDK meant to be generally
* usable while other portions of {@code com.sun.*} are not. This
* annotation type allows those portions to be easily and
- * programmaticly distinguished.
+ * programmatically distinguished.
+ *
+ * <p>If a top-level type has an <code>@Exported</code> annotation,
+ * any nested member types with the top-level type should have an
+ * <code>@Exported</code> annotation with the same value.
+ *
+ * Likewise, if a package has an <code>@Exported</code> annotation,
+ * top-level types within that package should also have an
+ * <code>@Exported</code> annotation.
+ *
+ * Sometimes a top-level type may have a different
+ * <code>@Exported</code> value than its package.
+ *
+ * <p>If in one release a type or package is
+ * <code>@Exported(true)</code>, in a subsequent major release a type
+ * or package can transition to <code>@Exported(false)</code>.
+ *
+ * <p>If a type or package is <code>@Exported(false)</code> in a
+ * release, it may be removed in a subsequent major release.
*
* @since 1.8
*/
On 10/08/2013 05:57 PM, Joe Darcy wrote:
On 10/04/2013 10:30 AM, mark.reinh...@oracle.com wrote:
2013/10/3 16:43 -0700, joe.da...@oracle.com:
Per previous discussions on the mailing list, we've decided to rename
the annotation type "jdk.Supported" to "jdk.Exported".
...
Looks good to me.
One question, though: Is it intended that one use of this annotation
can be overridden by another at a deeper lexical level? For example:
@Supported
public class X {
@Supported(false)
public static class Y {
}
}
I would say that is most likely a logical error to have inconsistent
exported-ness on a top-level and its nested types, but it is an
extra-linguistic correctness issue for the semantics we want to impose
on this annotation.
Conceivably, such an inconsistency could arise if for some reason a
nested type was slated for removal in the future but the containing
type was not.
Equivalently, imagine @Supported in a package-info.java file and
@Supported(false) on a type within that package.
At the package level, I'd say the package-info file should have the
prevailing exported-ness of the types in that package, but sometimes
there are a few bad types and the rest should stay.
If so then it'd be helpful to mention this possibility in the
specification.
I'll add some guidance on these points.
Thanks,
-Joe
