JDK 8 code review request for JDK-8025913 - Rename jdk.Supported to jdk.Exported

[Joe Darcy]

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.reinhold at oracle.com wrote:
>> 2013/10/3 16:43 -0700, joe.darcy at 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
>