Annotations for language features

[Joe Darcy]

Adam Malter wrote:
> Joe - I apologize then, I read the tweaking of JSR 269 to be further 
> towards a new api than an evolution of the current. I did not mean to
>  spread mis-information.
> 
> I will admit I am a bit gun shy about this issue, having to support a
>  com.sun.apt Processor, JSR 269 processor and Eclipse PlugIn (using
> the eclipse ast) to enable some of the neat 'features' we want for
> our implementation developers.
> 
> Everything seems to work a bit differently depending on where and how
>  you compile. It's this lesson though that I wish to convey when I 
> express fear about core features enabled by code parsing and 
> generating in the JDK.

Going slightly off-topic for the Project Coin list, one achievements of
the JSR 269 API was that it was retrofitted without too much pain on two
distinct long-lived compiler code bases and that the API was workable in
both a batch and incremental setting.

In Eclipse, the annotation processors are run on a per-file basis while
in javac the round can encompass multiple files.  This difference
in behavior is allowed by the specification and a few API elements in
JSR 269 were specifically added for the incremental/IDE setting:

1) Processor.getCompletions
2) The originatingElements arguments to the methods in the Filer

The originating elements are passed in so the IDE can know what 
processors should be re-run to get a consistent set of build artifacts.

To work well in either setting, the annotation processor author is 
expected to have some discipline in writing the processor:

"To be robust when running in different tool implementations, an 
annotation processor should have the following properties:

    1. The result of processing a given input is not a function of the 
presence or absence of other inputs (orthogonality).
    2. Processing the same input produces the same output (consistency).
    3. Processing input A followed by processing input B is equivalent 
to processing B then A (commutativity)
    4. Processing an input does not rely on the presence of the output 
of other annotation processors (independence) "
http://java.sun.com/javase/6/docs/api/javax/annotation/processing/Processor.html

The JSR 269 expert group discussed the utility of having, say, an 
incremental Filer that would help provide infrastructure for incremental 
updates, but such facilities were not included as part of the reference 
implementation.  I believe Bruce Chapman has made some progress in 
coding up this functionality.

-Joe