com.sun.tools.javac.processing
Class JavacFiler

java.lang.Object
  extended by com.sun.tools.javac.processing.JavacFiler
All Implemented Interfaces:
java.io.Closeable, Filer

public class JavacFiler
extends java.lang.Object
implements Filer, java.io.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 API supported by Sun Microsystems. 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.


Nested Class Summary
private  class JavacFiler.FilerInputFileObject
          Wrap a JavaFileObject to manage reading by the Filer.
private  class JavacFiler.FilerInputJavaFileObject
           
private  class JavacFiler.FilerOutputFileObject
          Wrap a JavaFileObject to manage writing by the Filer.
private  class JavacFiler.FilerOutputJavaFileObject
           
private  class JavacFiler.FilerOutputStream
          Wrap a OutputStream returned from the JavaFileManager to properly register source or class files when they are closed.
private  class JavacFiler.FilerWriter
          Wrap a Writer returned from the JavaFileManager to properly register source or class files when they are closed.
 
Field Summary
private  java.util.Set<java.lang.String> aggregateGeneratedClassNames
          Names of all created class files.
private  java.util.Set<java.lang.String> aggregateGeneratedSourceNames
          Names of all created source files.
private static java.lang.String ALREADY_OPENED
           
(package private)  Context context
           
(package private)  JavaFileManager fileManager
           
private  java.util.Set<FileObject> fileObjectHistory
          Logical names of all created files.
private  java.util.Map<java.lang.String,JavaFileObject> generatedClasses
          Names and class files of the class files closed in this round.
private  java.util.Set<JavaFileObject> generatedSourceFileObjects
          JavaFileObjects for source files closed in this round.
private  java.util.Set<java.lang.String> generatedSourceNames
          Names of source files closed in this round.
(package private)  boolean lastRound
           
private  boolean lint
           
(package private)  Log log
           
private static java.lang.String NOT_FOR_READING
           
private static java.lang.String NOT_FOR_WRITING
           
private  java.util.Set<java.lang.String> openTypeNames
          Names of types that have had files created but not closed.
 
Constructor Summary
JavacFiler(Context context)
           
 
Method Summary
private  void checkFileReopening(FileObject fileObject, boolean addToHistory)
          Check to see if the file has already been opened; if so, throw an exception, otherwise add it to the set of files.
private  void checkName(java.lang.String name)
           
private  void checkName(java.lang.String name, boolean allowUnnamedPackageInfo)
           
private  void checkNameAndExistence(java.lang.String typename, boolean allowUnnamedPackageInfo)
           
private  void clearRoundState()
           
 void close()
           
private  void closeFileObject(java.lang.String typeName, FileObject fileObject)
          Upon close, register files opened by create{Source, Class}File for annotation processing.
 JavaFileObject createClassFile(java.lang.CharSequence name, Element... originatingElements)
          Creates a new class file, and returns an object to allow writing to it.
 FileObject createResource(JavaFileManager.Location location, java.lang.CharSequence pkg, java.lang.CharSequence relativeName, Element... originatingElements)
          Creates a new auxiliary resource file for writing and returns a file object for it.
 JavaFileObject createSourceFile(java.lang.CharSequence name, Element... originatingElements)
          Creates a new source file and returns an object to allow writing to it.
private  JavaFileObject createSourceOrClassFile(boolean isSourceFile, java.lang.String name)
           
 void displayState()
          Debugging function to display internal state.
 java.util.Map<java.lang.String,JavaFileObject> getGeneratedClasses()
           
 java.util.Set<JavaFileObject> getGeneratedSourceFileObjects()
           
 java.util.Set<java.lang.String> getGeneratedSourceNames()
           
 FileObject getResource(JavaFileManager.Location location, java.lang.CharSequence pkg, java.lang.CharSequence relativeName)
          Returns an object for reading an existing resource.
private  boolean isPackageInfo(java.lang.String name, boolean allowUnnamedPackageInfo)
           
private  void locationCheck(JavaFileManager.Location location)
           
 boolean newFiles()
           
 void newRound(Context context, boolean lastRound)
          Update internal state for a new round.
 java.lang.String toString()
           
 void warnIfUnclosedFiles()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ALREADY_OPENED

private static final java.lang.String ALREADY_OPENED
See Also:
Constant Field Values

NOT_FOR_READING

private static final java.lang.String NOT_FOR_READING
See Also:
Constant Field Values

NOT_FOR_WRITING

private static final java.lang.String NOT_FOR_WRITING
See Also:
Constant Field Values

fileManager

JavaFileManager fileManager

log

Log log

context

Context context

lastRound

boolean lastRound

lint

private final boolean lint

fileObjectHistory

private final java.util.Set<FileObject> fileObjectHistory
Logical names of all created files. This set must be synchronized.


openTypeNames

private final java.util.Set<java.lang.String> openTypeNames
Names of types that have had files created but not closed.


generatedSourceNames

private java.util.Set<java.lang.String> generatedSourceNames
Names of source files closed in this round. This set must be synchronized. Its iterators should preserve insertion order.


generatedClasses

private final java.util.Map<java.lang.String,JavaFileObject> generatedClasses
Names and class files of the class files closed in this round. This set must be synchronized. Its iterators should preserve insertion order.


generatedSourceFileObjects

private java.util.Set<JavaFileObject> generatedSourceFileObjects
JavaFileObjects for source files closed in this round. This set must be synchronized. Its iterators should preserve insertion order.


aggregateGeneratedSourceNames

private final java.util.Set<java.lang.String> aggregateGeneratedSourceNames
Names of all created source files. Its iterators should preserve insertion order.


aggregateGeneratedClassNames

private final java.util.Set<java.lang.String> aggregateGeneratedClassNames
Names of all created class files. Its iterators should preserve insertion order.

Constructor Detail

JavacFiler

JavacFiler(Context context)
Method Detail

createSourceFile

public JavaFileObject createSourceFile(java.lang.CharSequence name,
                                       Element... originatingElements)
                                throws java.io.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
java.io.IOException - if the file cannot be created

createClassFile

public JavaFileObject createClassFile(java.lang.CharSequence name,
                                      Element... originatingElements)
                               throws java.io.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
java.io.IOException - if the file cannot be created

createSourceOrClassFile

private JavaFileObject createSourceOrClassFile(boolean isSourceFile,
                                               java.lang.String name)
                                        throws java.io.IOException
Throws:
java.io.IOException

createResource

public FileObject createResource(JavaFileManager.Location location,
                                 java.lang.CharSequence pkg,
                                 java.lang.CharSequence relativeName,
                                 Element... originatingElements)
                          throws java.io.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:
java.io.IOException - if the file cannot be created
FilerException - if the same pathname has already been created

locationCheck

private void locationCheck(JavaFileManager.Location location)

getResource

public FileObject getResource(JavaFileManager.Location location,
                              java.lang.CharSequence pkg,
                              java.lang.CharSequence relativeName)
                       throws java.io.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
java.io.IOException - if the file cannot be opened

checkName

private void checkName(java.lang.String name)
                throws FilerException
Throws:
FilerException

checkName

private void checkName(java.lang.String name,
                       boolean allowUnnamedPackageInfo)
                throws FilerException
Throws:
FilerException

isPackageInfo

private boolean isPackageInfo(java.lang.String name,
                              boolean allowUnnamedPackageInfo)

checkNameAndExistence

private void checkNameAndExistence(java.lang.String typename,
                                   boolean allowUnnamedPackageInfo)
                            throws FilerException
Throws:
FilerException

checkFileReopening

private void checkFileReopening(FileObject fileObject,
                                boolean addToHistory)
                         throws FilerException
Check to see if the file has already been opened; if so, throw an exception, otherwise add it to the set of files.

Throws:
FilerException

newFiles

public boolean newFiles()

getGeneratedSourceNames

public java.util.Set<java.lang.String> getGeneratedSourceNames()

getGeneratedSourceFileObjects

public java.util.Set<JavaFileObject> getGeneratedSourceFileObjects()

getGeneratedClasses

public java.util.Map<java.lang.String,JavaFileObject> getGeneratedClasses()

warnIfUnclosedFiles

public void warnIfUnclosedFiles()

newRound

public void newRound(Context context,
                     boolean lastRound)
Update internal state for a new round.


close

public void close()
Specified by:
close in interface java.io.Closeable

clearRoundState

private void clearRoundState()

displayState

public void displayState()
Debugging function to display internal state.


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

closeFileObject

private void closeFileObject(java.lang.String typeName,
                             FileObject fileObject)
Upon close, register files opened by create{Source, Class}File for annotation processing.