PROPOSAL: Extend Scope of Imports to Include Package Annotations

[Joseph D. Darcy]

Hi Bruce.

I've discussed your proposal with Alex and we agree this is a fine 
change to incorporate under JLS  maintenance.

Thanks for sending this in,

-Joe

brucechapman at paradise.net.nz wrote:
> html version at http://docs.google.com/Doc?id=dcvp3mkv_3fc5hqngp
>
> Extend Scope of Imports to Include Package Annotations
>
> AUTHOR(S): Bruce Chapman
>
> OVERVIEW
>
> FEATURE SUMMARY:
> JLS3 says Import statements do not apply to package statements and therefore by
> implication they do not apply to annotations on package statements. However
> JDK6's javac does use import statements to resolve types in package annotations,
> for which a Bug has been accepted. This proposal is to change the language
> specification to be consistent with the compiler in order to yield a more
> pragmatic solution than fixing the bug in the compiler.
>
>
> MAJOR ADVANTAGE: 
>
> Annotations on packages will no longer need to fully qualify type names for
> annotation types, and for any class literals used as annotation values.
>
> MAJOR DISADVANTAGE:
> With millions of developers someone somewhere might find this counterproductive.
> I cannot imagine how.
>
>
> ALTERNATIVES:
>
> The alternative to changing the language spec is to fix the bug, which may well
> be a breaking change for anyone who has inadvertently or knowingly taken
> advantage of the bug.
>
> EXAMPLES
> SIMPLE EXAMPLE:
>
>     @Generated("something") package a.b;
>
>     import java.lang.annotations.Generated;
>
> is currently illegal and must be written as
>
>     @java.lang.annotations.Generated("something") package a.b;
>
> ADVANCED EXAMPLE:
>
>
> Currently this is illegal
>
>     @Deprecated package my.package;
>
> because the implicit import of java.lang.Deprecated is out of scope of the
> package statement's annotation. This change would bring all imports into scope
> and make the example legal (regardless of any arguments for or against
> annotating a package as deprecated - it's just an example)
>
> DETAILS
> SPECIFICATION: 
>
>
> JLS Section 7.5 needs additions (in bold)
>
>     The scope of a type imported by a single-type-import declaration (§7.5.1) or
> a type-import-on-demand declaration (§7.5.2) is all the class and interface type
> declarations (§7.6) in the compilation unit in which the import declaration
> appears, as well as any annotations on the compilation unit's package statement
> if present.
>
> and
>
>     The scope of the entities(s) it introduces specifically does not include the
> package statement's PackageName, other import declarations in the current
> compilation unit, or other compilation units in the same package.
>
> COMPILATION:
>
> JDK 6 already implements this feature (unless bug 6470991 has been fixed).
> Implementation is just a JLS change. If the bug has been fixed, implementation
> involves reversing the changes that fixed the bug.
>
> TESTING:
>
> Check that annotations are resolved using import statements.
>
> Check both annotation types and class literals used in annotation element values.
>
> Check both implicit imports from java.lang as well as single-type-import and
> type-import-on-demand imports.
>
> Check that an import correctly shadows a type with the same simple name in the
> same package.
>
> LIBRARY SUPPORT: 
>
> No library support required.
>
> REFLECTIVE APIS:
>
> No change
>
> OTHER CHANGES: 
> none
> MIGRATION:
> Tools can apply their existing import statement management logic to annotations
> on package statements.
>
> COMPATIBILITY
> BREAKING CHANGES:
>
> It is possible to contrive a breaking change where a single-type-import
> declaration d in a compilation unit c of package p that imports a type named n
> shadows the declaration of a top level annotation type named n declared in
> another compilation unit of p and c's package declaration has an annotation
> using the type n. Prior to this change n should mean p.n and after this change
> will refer to the type in d. However the the bug means that it will already be
> refering to the type in d.
>
>
> Due to the bug this theoretical situation can be discounted as no worse than the
> converse situation caused by fixing the bug.
>
> EXISTING PROGRAMS: 
>
> This is a compile time name resolution issue and will not affect exisitng source
> or class files except as noted under breaking changes.
>
>
> REFERENCES
> EXISTING BUGS: 
>
> Bug 6470991 This documents how the compiler differs from the JLS, and behaves
> according to this proposal.
>
> URL FOR PROTOTYPE (optional):
>
> Due to the bug, the existing JDK can be used as a prototype.
> http://java.sun.com/javase/downloads
>
>
>