public interface Filer
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) or modules (representing
module-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
the type element for@Generate public class UserSource {}
UserSource
should be passed as part of
the creation method call as in:
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.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 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 a javax.annotation.Generated
annotation if the
environment is configured so that that type is accessible.
Modifier and Type | Method | Description |
---|---|---|
JavaFileObject |
createClassFile(CharSequence name,
Element... originatingElements) |
Creates a new class file, and returns an object to allow
writing to it.
|
FileObject |
createResource(JavaFileManager.Location location,
CharSequence moduleAndPkg,
CharSequence relativeName,
Element... originatingElements) |
Creates a new auxiliary resource file for writing and returns a
file object for it.
|
JavaFileObject |
createSourceFile(CharSequence name,
Element... originatingElements) |
Creates a new source file and returns an object to allow
writing to it.
|
FileObject |
getResource(JavaFileManager.Location location,
CharSequence moduleAndPkg,
CharSequence relativeName) |
Returns an object for reading an existing resource.
|
JavaFileObject createSourceFile(CharSequence name, Element... originatingElements) throws IOException
A source file can also be created to hold information about
a package, including package annotations. To create a source
file for a named package, have the name
argument be the
package's name followed by ".package-info"
; to create a
source file for an unnamed package, use "package-info"
.
The optional module name is prefixed to the type name or
package name and separated using a "/
" character. For
example, to create a source file for type a.B
in module
foo
, use a name
argument of "foo/a.B"
.
If no explicit module prefix is given and modules are supported
in the environment, a suitable module is inferred. If a suitable
module cannot be inferred FilerException
is thrown.
An implementation may use information about the configuration of
the annotation processing tool as part of the inference.
Creating a source file in or for an unnamed package in a named module is not supported.
OutputStreamWriter
with the chosen charset can
be created from the OutputStream
from the returned
object. If the Writer
from the returned object is
directly used for writing, its charset is determined by the
implementation. An annotation processing tool may have an
-encoding
flag or analogous option for specifying this;
otherwise, it will typically be the platform's default
encoding.
To avoid subsequent errors, the contents of the source file should be compatible with the source version being used for this run.
Elements.getPackageElement(package-of(name))
returns a package, the module that owns the returned package is used
as the target module. A separate option may be used to provide the target
module if it cannot be determined using the above rules.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 fileoriginatingElements
- type or package or module elements causally
associated with the creation of this file, may be elided or
null
JavaFileObject
to write the new source fileFilerException
- if the same pathname has already been
created, the same type has already been created, the name is
otherwise not valid for the entity requested to being created,
if the target module cannot be determined, if the target
module is not writable, or a module is specified when the environment
doesn't support modules.IOException
- if the file cannot be createdJavaFileObject createClassFile(CharSequence name, Element... originatingElements) throws IOException
A class file can also be created to hold information about a
package, including package annotations. To create a class file
for a named package, have the name
argument be the
package's name followed by ".package-info"
; creating a
class file for an unnamed package is not supported.
The optional module name is prefixed to the type name or
package name and separated using a "/
" character. For
example, to create a class file for type a.B
in module
foo
, use a name
argument of "foo/a.B"
.
If no explicit module prefix is given and modules are supported
in the environment, a suitable module is inferred. If a suitable
module cannot be inferred FilerException
is thrown.
An implementation may use information about the configuration of
the annotation processing tool as part of the inference.
Creating a class file in or for an unnamed package in a named module is not supported.
Elements.getPackageElement(package-of(name))
returns a package, the module that owns the returned package is used
as the target module. A separate option may be used to provide the target
module if it cannot be determined using the above rules.name
- binary name of the type being written or a package name followed by
".package-info"
for a package information fileoriginatingElements
- type or package or module elements causally
associated with the creation of this file, may be elided or
null
JavaFileObject
to write the new class fileFilerException
- if the same pathname has already been
created, the same type has already been created, the name is
not valid for a type, if the target module cannot be determined,
if the target module is not writable, or a module is specified when
the environment doesn't support modules.IOException
- if the file cannot be createdFileObject createResource(JavaFileManager.Location location, CharSequence moduleAndPkg, CharSequence relativeName, Element... originatingElements) throws IOException
CLASS_OUTPUT
and SOURCE_OUTPUT
must be
supported. The resource may be named relative to some module
and/or package (as are source and class files), and from there
by a relative pathname. In a loose sense, the full pathname of
the new file will be the concatenation of location
,
moduleAndPkg
, and relativeName
.
If moduleAndPkg
contains a "/
" character, the
prefix before the "/
" character is the module name and
the suffix after the "/
" character is the package
name. The package suffix may be empty. If moduleAndPkg
does not contain a "/
" character, the entire argument
is interpreted as a package name.
If the given location is neither a module oriented location, nor an output location containing multiple modules, and the explicit
module prefix is given, FilerException
is thrown.
If the given location is either a module oriented location,
or an output location containing multiple modules, and no explicit
modules prefix is given, a suitable module is
inferred. If a suitable module cannot be inferred FilerException
is thrown. An implementation may use information
about the configuration of the annotation processing tool
as part of the inference.
Files created via this method are not registered for annotation processing, even if the full pathname of the file would correspond to the full pathname of a new source file or new class file.
Elements.getPackageElement(package-of(name))
returns a package, the module that owns the returned package is used
as the target module. A separate option may be used to provide the target
module if it cannot be determined using the above rules.location
- location of the new filemoduleAndPkg
- module and/or package relative to which the file
should be named, or the empty string if nonerelativeName
- final pathname components of the fileoriginatingElements
- type or package or module elements causally
associated with the creation of this file, may be elided or
null
FileObject
to write the new resourceIOException
- if the file cannot be createdFilerException
- if the same pathname has already been
created, if the target module cannot be determined,
or if the target module is not writable, or if an explicit
target module is specified and the location does not support it.IllegalArgumentException
- for an unsupported locationIllegalArgumentException
- if moduleAndPkg
is ill-formedIllegalArgumentException
- if relativeName
is not relativeFileObject getResource(JavaFileManager.Location location, CharSequence moduleAndPkg, CharSequence relativeName) throws IOException
CLASS_OUTPUT
and SOURCE_OUTPUT
must
be supported.
If moduleAndPkg
contains a "/
" character, the
prefix before the "/
" character is the module name and
the suffix after the "/
" character is the package
name. The package suffix may be empty; however, if a module
name is present, it must be nonempty. If moduleAndPkg
does not contain a "/
" character, the entire argument
is interpreted as a package name.
If the given location is neither a module oriented location, nor an output location containing multiple modules, and the explicit
module prefix is given, FilerException
is thrown.
If the given location is either a module oriented location,
or an output location containing multiple modules, and no explicit
modules prefix is given, a suitable module is
inferred. If a suitable module cannot be inferred FilerException
is thrown. An implementation may use information
about the configuration of the annotation processing tool
as part of the inference.
Elements.getPackageElement(package-of(name))
returns a package, the module that owns the returned package is used
as the source module. A separate option may be used to provide the target
module if it cannot be determined using the above rules.location
- location of the filemoduleAndPkg
- module and/or package relative to which the file
should be searched for, or the empty string if nonerelativeName
- final pathname components of the fileFilerException
- if the same pathname has already been
opened for writing, if the source module cannot be determined,
or if the target module is not writable, or if an explicit target
module is specified and the location does not support it.IOException
- if the file cannot be openedIllegalArgumentException
- for an unsupported locationIllegalArgumentException
- if moduleAndPkg
is ill-formedIllegalArgumentException
- if relativeName
is not relative Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2017, Oracle and/or its affiliates. 500 Oracle Parkway
Redwood Shores, CA 94065 USA. All rights reserved.
DRAFT 9-internal+0-adhoc.mlchung.jdk9-jdeps