There are two distinguished locations (subtrees within the file system) where newly created files are placed: one for new source files, and one for new class files. (These might be specified on a tool's command line, for example, using flags such as -s and -d.) Auxiliary files may be created in either location.
During each run of an annotation processing tool, a file with a given pathname may be created only once. If that file already exists before the first attempt to create it, the old contents will be deleted. Any subsequent attempt to create the same file during a run will fail. @author Joseph D. Darcy @author Scott Seligman @version 1.2 05/11/17 @since 1.5
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 {@code package-info} files) which caused an annotation processor toattempt to create a new file. For example, if an annotation processor tries to create a source file, {@code GeneratedFromUserSource}, in response to processing
@Generate public class UserSource {} filer.createSourceFile("GeneratedFromUserSource", eltUtils.getTypeElement("UserSource")); During each run of an annotation processing tool, a file with a given pathname may be created only once. If that file already exists before the first attempt to create it, the old contents will be deleted. Any subsequent attempt to create the same file during a run will throw a {@link FilerException}, as will attempting to create both a class file and source file for the same type name or same package name. The {@linkplain Processor initial inputs} tothe tool are considered to be created by the zeroth round; therefore, attempting to create a source or class file corresponding to one of those inputs will result in a {@link FilerException}.
In general, processors must not knowingly attempt to overwrite existing files that were not generated by some processor. A {@code Filer} may reject attempts to open a file corresponding to anexisting type, like {@code java.lang.Object}. Likewise, the invoker of the annotation processing tool must not knowingly configure the tool such that the discovered processors will attempt to overwrite existing files that were not generated.
Processors can indicate a source or class file is generated by including an {@link javax.annotation.Generated @Generated}annotation.
Note that some of the effect of overwriting a file can be achieved by using a decorator-style pattern. Instead of modifying a class directly, the class is designed so that either its superclass is generated by annotation processing or subclasses of the class are generated by annotation processing. If the subclasses are generated, the parent class may be designed to use factories instead of public constructors so that only subclass instances would be presented to clients of the parent class. @author Joseph D. Darcy @author Scott Seligman @author Peter von der Ahé @since 1.6
| |
| |
| |