com.sun.tools.javac.processing

Class JavacFiler

java.lang.Object

com.sun.tools.javac.processing.JavacFiler

All Implemented Interfaces:

Closeable, AutoCloseable, Filer

public class JavacFiler
extends Object
implements Filer, Closeable

The FilerImplementation class must maintain a number of constraints. First, multiple attempts to open the same path within the same invocation of the tool results in an IOException being thrown. For example, trying to open the same source file twice:

 createSourceFile("foo.Bar")
 ...
 createSourceFile("foo.Bar")
 

is disallowed as is opening a text file that happens to have the same name as a source file:

 createSourceFile("foo.Bar")
 ...
 createTextFile(SOURCE_TREE, "foo", new File("Bar"), null)
 

Additionally, creating a source file that corresponds to an already created class file (or vice versa) also results in an IOException since each type can only be created once. However, if the Filer is used to create a text file named *.java that happens to correspond to an existing class file, a warning is *not* generated. Similarly, a warning is not generated for a binary file named *.class and an existing source file.

The reason for this difference is that source files and class files are registered with the tool and can get passed on as declarations to the next round of processing. Files that are just named *.java and *.class are not processed in that manner; although having extra source files and class files on the source path and class path can alter the behavior of the tool and any final compile.

This is NOT part of any supported API. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.

Method Summary

Modifier and Type	Method and Description
void	close()
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 pkg, 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.
void	displayState() Debugging function to display internal state.
Map<String,JavaFileObject>	getGeneratedClasses()
Set<JavaFileObject>	getGeneratedSourceFileObjects()
Set<String>	getGeneratedSourceNames()
FileObject	getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) Returns an object for reading an existing resource.
boolean	newFiles()
void	newRound(Context context) Update internal state for a new round.
String	toString()
void	warnIfUnclosedFiles()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

createSourceFile

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

Description copied from interface: Filer

Creates a new source file and returns an object to allow writing to it. The file's name and path (relative to the root output location for source files) are based on the type to be declared in that file. If more than one type is being declared, the name of the principal top-level type (the public one, for example) should be used. 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 name be the package's name followed by ".package-info"; to create a source file for an unnamed package, use "package-info".

Note that to use a particular charset to encode the contents of the file, an 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.

Specified by:

createSourceFile in interface Filer

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

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

Description copied from interface: Filer

Creates a new class file, and returns an object to allow writing to it. The file's name and path (relative to the root output location for class files) are based on the name of the type being written. 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 name be the package's name followed by ".package-info"; creating a class file for an unnamed package is not supported.

To avoid subsequent errors, the contents of the class file should be compatible with the source version being used for this run.

Specified by:

createClassFile in interface Filer

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

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

Description copied from interface: Filer

Creates a new auxiliary resource file for writing and returns a file object for it. The file may be located along with the newly created source files, newly created binary files, or other supported location. The locations CLASS_OUTPUT and SOURCE_OUTPUT must be supported. The resource may be named relative to some 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, pkg, and relativeName.

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.

Specified by:

createResource in interface Filer

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

getResource

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

Description copied from interface: Filer

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

Specified by:

getResource in interface Filer

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

newFiles

public boolean newFiles()

getGeneratedSourceNames

public Set<String> getGeneratedSourceNames()

getGeneratedSourceFileObjects

public Set<JavaFileObject> getGeneratedSourceFileObjects()

getGeneratedClasses

public Map<String,JavaFileObject> getGeneratedClasses()

warnIfUnclosedFiles

public void warnIfUnclosedFiles()

newRound

public void newRound(Context context)

Update internal state for a new round.

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

displayState

public void displayState()

Debugging function to display internal state.

toString

public String toString()

Overrides:

toString in class Object