Why the annotation processing API ?

[Jonathan Gibbons]

On 05/25/2016 09:32 PM, Stéphane NICOLAS wrote:
> Hi folks,
>
> I know a simple mail like this generally has very minimal value. But 
> still, it's been around 2-3 years now that I work on Android, doing a 
> lot of work around reflection and annotation processing.
>
> I don't like the annotation processing API. I still find every concept 
> hard to remember, and it is always taking time to get immersed into it 
> for a new project.
>
> Thus, I don't understand, very humbly and very honestly, why this API 
> even exists. Why can't we simply use reflection-like APIs ? It would 
> not be that complex to expose an API that looks like reflection 
> (read-only of course, no new instance of classes, to method calls or 
> setting/getting field values, just the discovery part).
>
> I could see over the past years that the newer versions of the JDK are 
> aligning more and more the capacities of the annotation processing API 
> with reflection APIs. Some subtle changes but always in this 
> direction. All you can do with reflection is now possible with 
> annotation processing (read-only still, as stated above).
>
> Does it sound completely stupid to ask that javac annotation processor 
> API for JDK 10 would actually match reflection API ? Reflection API is 
> so simple and it describes OO code in a natural way for all java 
> coders. Methods, classes, fields... much simpler than an element type 
> with a kind that you can cast into I don't know what ! Annotation 
> processing API is not clear. It is obviously overworked, complex, 
> abstract, very scholar and hard to use.
>
> Is there anything that can be done with respect to this problem ?
> I hope I am not saying something completely dumb here, but I have been 
> thinking about this for a very long time now.
>
> S.
>

You are probably conflating two concepts.  There is the "Annotation 
Processing API", javax.annotation.processing, and there is the "Language 
Model API", javax.lang.model.

You can think of the Language Model API as "compile-time reflection".   
It allows you to reflect over declarations without the constraints of 
the classes having to be loaded into class loaders, and it can also work 
on classes that only exist in source form. As such, it can even give 
access to documentation comments contained in the source code.   One 
notable feature is that you can use the Language Model API to reflect 
over different versions of classes than those in the current runtime.  
For example, you can run javac on JDK 9 and use the Language Model API 
to examine the classes for JDK 8, and vice versa.

The Annotation Processing API can be thought of as an API for compiler 
"plugins". It allows you to extend the capabilities of the compiler to 
examine the code being compiled, using the Language Model API, and 
(within some well defined limitations) it allows you to generate 
additional classes to be included in the compilation.

All three APIs, the Annotation Processing API, the Language Model API, 
and the runtime-reflection API (java.lang.reflect) all have their place 
in the Java ecosystem.

-- Jon