I am confused about what exactly is incremental environment in the context of annotation processing in Java. An example is highly appreciated.
The following is a quote from the Javadoc of Filer:
The file creation methods take a variable number of arguments to allow the originating elements to be provided as hints to the tool infrastructure to better manage dependencies. The originating elements are the types or packages (representing package-info files) which caused an annotation processor to attempt to create a new file. For example, if an annotation processor tries to create a source file, GeneratedFromUserSource, in response to processing
@Generate public class UserSource {}the type element for UserSource should be passed as part of the creation method call as in:
filer.createSourceFile("GeneratedFromUserSource", eltUtils.getTypeElement("UserSource"));If there are no originating elements, none need to be passed. This information may be used in an incremental environment to determine the need to rerun processors or remove generated files. Non-incremental environments may ignore the originating element information.
I understand, for example, in the above example, if @Generated is removed, the next time compilation is run the previously generated GeneratedFromUserSource will be removed. (Supposedly, apparently, some implementations like com.sun.tools.javac.processing.JavacFiler ignore originating elements altogether.) Does this make it incremental? I do not have any example in mind for a need to rerun the processor.
To make matters a bit more confusing, I have stumbled upon this question and apparently, there are three types of processors:
- dynamic, 2. isolating, 3. aggregation
and incremental processors need to be registered in a different place in META-INF than non-incremental ones. I am currently using @AutoService which I think does not support this registration.
Since (mostly) overwriting is not allowed in Filer, I would appreciate a clarification on what makes a processor incremental.