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

[Paul Sandoz]

On Oct 9, 2013, at 2:57 AM, Joe Darcy <joe.darcy at oracle.com> 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.
> 

Yes. It is possible to use a style where the top-level type name acts as a namespace for nested member types.

In that case in addition to the following change in your latest email (and below):

> +  * Sometimes a top-level type may have a different
> +  * <code>@Exported</code> value than its package.


should it also be stated for root and nested?

Paul.

> 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
>   */