PROPOSAL: Extend Scope of Imports to Include Package Annotations

[brucechapman at paradise.net.nz]

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