| 02ac307c0d3fa53b83666972e0a75bc098500700 |
|
13-Sep-2009 |
Michael Ernst <mernst@cs.washington.edu> |
Handle meta-annotations, read annotations from classfiles.
The four major user-visible changes are:
1. Handle meta-annotations.
Previously, the Annotation File Utilities didn't handle meta-annotations
(annotations that are written on an annotation type declaration); in fact,
AFU simply fabricated retention information. Now, meta-annotations are
handled uniformly with other annotations.
Make AnnotationDef a subclass of AElement, because it can be subtyped.
This introduces recursion in the data structure and requires a number of
changes.
2. Distinguish type annotations from declaration annotations.
Previously, AFU assumed that all annotations were type annotations. Now,
this information is looked up from the meta-annotations.
In AMethod, add returnType field. (Forgetting to add it to prune() was a
source of bugs.) AMethod now only extends AElement, not ATypeElement,
because it can be annotated, but not with type annotations.
3. Read annotations from classfiles.
Previously, AFU created partial information for annotations in an ad hoc
way, and classfile reading did not work. (The focus was on inserting
annotations in class files, not reading annotations from class files.)
Now, classfile reading is operational, and it is often not necessary to
declare annotations in an annotation file. However, if the annotation is
declared in the annotation file, it should be consistent with its
declaration in the class file.
4. Changes to annotation file format.
1. Indicating meta-annotations
annotation visible @Nullable:
becomes
annotation @Nullable: @Retention(value=RUNTIME)
and if it's a type annotation, it should be
annotation @Nullable: @Retention(value=RUNTIME) @java.lang.annotation.Target(value={TYPE_USE})
2. Locations for type and declaration annotations
If p2.B is a declaration annotation on a method, it is written as before:
method foo(Ljava/util/Set;)V: @p2.B
If p2.B is a type annotation on a method return type, it is written in a
new location:
method foo(Ljava/util/Set;)V:
return: @p2.B
Fields should perhaps be treated similarly, but are not (yet).
3. Permit qualified names in several places that only identifiers were
permitted before. This enables use of names that contain periods, such
as inner classes, and also fully-qualified names.
4. Permit two shorthands in annotation uses, as in Java. If there is a
single field named "value", then its name may be omitted: @A(1) instead
of @A(value=1). If an array has only one element, the braces may be
omitted: @A(value=1) instead of @A(value={1}). Naturally, both
shorthands may be combined.
Move changelog to a separate webpage.
Code changes for constructing an annotation:
In Annotations, programmatically build a few useful Annotation and
AnnotationDef objects.
When creating an annotation, sanity-check the field names and values. This
forced many bug fixes and some representation changes. New method
AnnotationFieldType.isValidValue is part of this change.
In AnnotationBuilder, permit passing an AnnotationDef to the constructor.
This is now the preferred usage model, even when when reading from a
classfile, and should perhaps be required, with other uses not supported.
Previously a new AnnotationDef was always inferred from the fields that
were read. AnnotationBuilder can create the AnnotationDef from a
java.lang.annotation.Annotation.
Use a map of all definitions (AnnotationDef) to avoid re-computation or
inconsistencies.
Other code changes:
Code cleanup:
Remove RetentionPolicy.
Eliminate confusing "isVisible" terminology in favor of more standard
"isRuntimeRetention".
Eliminate uses of Annotations.fieldValuesMap, which was only an
optimization (that doesn't seem to help any) and was a source of bugs.
Make explicit the hack where ArrayAnnotationSceneReader extends
AnnotationSceneReader (this hack is not proper behavioral subtyping) by
passing "dummy" from the subclass to the superclass to turn off some
undesired superclass behavior in that case.
Debugging improvements:
Add debugging statements.
ClassAnnotationSceneReader: add tracing
Print classpath if annotation cannot be found on it.
Scene library tests:
Rename files scene-lib/test/annotations/tests/classfile/cases/*.expected to
*_Expected.class; this name permits javap to be run on the file.
Likewise for files *.generated.
Don't delete temp class file if test fails.
Improve error & failure messages.
Improve documentation.
Add helper methods.
Specific changes to AnnotationVerifier and AnnotationRecorder follow.
AnnotationVerifier:
Improve error/failure messages.
Add pretty-printing.
AnnotationRecorder:
Improve field names
fieldArgs1 => fieldArgsName
fieldArgs2 => fieldArgsValue
enumArgs1 => enumArgsName
enumArgs2 =>enumArgsDesc
enumArgs3 =>enumArgsValue
innerAnnotationArgs1 =>innerAnnotationArgsName
innerAnnotationArgs2 =>innerAnnotationArgsDesc
/external/annotation-tools/scene-lib/src/annotations/AnnotationFactory.java
|