Interface Filer

public interface Filer

This interface supports the creation of new files by an annotation processor. Files created in this way will be known to the annotation processing tool implementing this interface, better enabling the tool to manage them. Source and class files so created will be considered for processing by the tool in a subsequent round of processing after the close method has been called on the Writer or OutputStream used to write the contents of the file. Three kinds of files are distinguished: source files, class files, and auxiliary resource files.

There are two distinguished supported locations (subtrees within the logical 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.) The actual locations for new source files and new class files may or may not be distinct on a particular run of the tool. Resource files may be created in either location. The methods for reading and writing resources take a relative name argument. A relative name is a non-null, non-empty sequence of path segments separated by '/'; '.' and '..' are invalid path segments. A valid relative name must match the "path-rootless" rule of RFC 3986, section 3.3.

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.

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 FilerException, as will attempting to create both a class file and source file for the same type name or same package name. The initial inputs to the 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 FilerException.

In general, processors must not knowingly attempt to overwrite existing files that were not generated by some processor. A Filer may reject attempts to open a file corresponding to an existing type, like 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 @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.

Methods

createSourceFile

JavaFileObject createSourceFile(CharSequence name,
                                Element... originatingElements)
                         throws IOException

Parameters:

name - canonical (fully qualified) name of the principal type being declared in this file or a package name followed by ".package-info" for a package information file

originatingElements - type or package elements causally associated with the creation of this file, may be elided or null

Returns:

a JavaFileObject to write the new source file

Throws:

FilerException - if the same pathname has already been created, the same type has already been created, or the name is not valid for a type

IOException - if the file cannot be created

createClassFile

JavaFileObject createClassFile(CharSequence name,
                               Element... originatingElements)
                        throws IOException

Parameters:

name - binary name of the type being written or a package name followed by ".package-info" for a package information file

originatingElements - type or package elements causally associated with the creation of this file, may be elided or null

Returns:

a JavaFileObject to write the new class file

Throws:

FilerException - if the same pathname has already been created, the same type has already been created, or the name is not valid for a type

IOException - if the file cannot be created

createResource

FileObject createResource(JavaFileManager.Location location,
                          CharSequence pkg,
                          CharSequence relativeName,
                          Element... originatingElements)
                   throws IOException

Parameters:

location - location of the new file

pkg - package relative to which the file should be named, or the empty string if none

relativeName - final pathname components of the file

originatingElements - type or package elements causally associated with the creation of this file, may be elided or null

Returns:

a FileObject to write the new resource

Throws:

IOException - if the file cannot be created

FilerException - if the same pathname has already been created

IllegalArgumentException - for an unsupported location

IllegalArgumentException - if relativeName is not relative

getResource

FileObject getResource(JavaFileManager.Location location,
                       CharSequence pkg,
                       CharSequence relativeName)
                throws IOException

Returns an object for reading an existing resource. The locations CLASS_OUTPUT and SOURCE_OUTPUT must be supported.

Parameters:

location - location of the file

pkg - package relative to which the file should be searched, or the empty string if none

relativeName - final pathname components of the file

Returns:

an object to read the file

Throws:

FilerException - if the same pathname has already been opened for writing

IOException - if the file cannot be opened

IllegalArgumentException - for an unsupported location

IllegalArgumentException - if relativeName is not relative