File Doc Category Size Date Package
StandardJavaFileManager.java API Doc Java SE 6 API 7989 Tue Jun 10 00:27:02 BST 2008 javax.tools

StandardJavaFileManager

public interface StandardJavaFileManager implements JavaFileManager

File manager based on {@linkplain File java.io.File}. A common way to obtain an instance of this class is using {@linkplain JavaCompiler#getStandardFileManager getStandardFileManager}, for example:

JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
{@code DiagnosticCollector} diagnostics =
new {@code DiagnosticCollector()};
StandardJavaFileManager fm = compiler.getStandardFileManager(diagnostics, null, null);

This file manager creates file objects representing regular {@linkplain File files}, {@linkplain java.util.zip.ZipEntry zip file entries}, or entries in similar file system based containers. Any file object returned from a file manager implementing this interface must observe the following behavior:

File names need not be canonical.
For file objects representing regular files
- the method {@linkplain FileObject#delete()} is equivalent to {@linkplain File#delete()},
- the method {@linkplain FileObject#getLastModified()} is equivalent to {@linkplain File#lastModified()},
- the methods {@linkplain FileObject#getCharContent(boolean)}, {@linkplain FileObject#openInputStream()}, and {@linkplain FileObject#openReader(boolean)} must succeed if the following would succeed (ignoring encoding issues):
```
new {@linkplain java.io.FileInputStream#FileInputStream(File) FileInputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))
```
- and the methods {@linkplain FileObject#openOutputStream()}, and {@linkplain FileObject#openWriter()} must succeed if the following would succeed (ignoring encoding issues):
```
new {@linkplain java.io.FileOutputStream#FileOutputStream(File) FileOutputStream}(new {@linkplain File#File(java.net.URI) File}({@linkplain FileObject fileObject}.{@linkplain FileObject#toUri() toUri}()))
```
The {@linkplain java.net.URI URI} returned from {@linkplain FileObject#toUri()}
- must be {@linkplain java.net.URI#isAbsolute() absolute} (have a schema), and
- must have a {@linkplain java.net.URI#normalize() normalized} {@linkplain java.net.URI#getPath() path component} which can be resolved without any process-specific context such as the current directory (file names must be absolute).

According to these rules, the following URIs, for example, are allowed:

file:///C:/Documents%20and%20Settings/UncleBob/BobsApp/Test.java
jar:///C:/Documents%20and%20Settings/UncleBob/lib/vendorA.jar!com/vendora/LibraryClass.class

Whereas these are not (reason in parentheses):

file:BobsApp/Test.java (the file name is relative and depend on the current directory)
jar:lib/vendorA.jar!com/vendora/LibraryClass.class (the first half of the path depends on the current directory, whereas the component after ! is legal)
Test.java (this URI depends on the current directory and does not have a schema)
jar:///C:/Documents%20and%20Settings/UncleBob/BobsApp/../lib/vendorA.jar!com/vendora/LibraryClass.class (the path is not normalized)

author: Peter von der Ahé
since: 1.6

Fields Summary
Constructors Summary
Methods Summary
public java.lang.Iterable getJavaFileObjects(java.io.File files)
Gets file objects representing the given files. Convenience method equivalent to:
getJavaFileObjectsFromFiles({@linkplain java.util.Arrays#asList Arrays.asList}(files))
param
files an array of files
return
a list of file objects
throws
IllegalArgumentException if the array of files includes a directory
throws
NullPointerException if the given array contains null elements
public java.lang.Iterable getJavaFileObjects(java.lang.String names)
Gets file objects representing the given file names. Convenience method equivalent to:
getJavaFileObjectsFromStrings({@linkplain java.util.Arrays#asList Arrays.asList}(names))
param
names a list of file names
return
a list of file objects
throws
IllegalArgumentException if the array of file names includes a directory
throws
NullPointerException if the given array contains null elements
public java.lang.Iterable getJavaFileObjectsFromFiles(java.lang.Iterable files)
Gets file objects representing the given files.
param
files a list of files
return
a list of file objects
throws
IllegalArgumentException if the list of files includes a directory
public java.lang.Iterable getJavaFileObjectsFromStrings(java.lang.Iterable names)
Gets file objects representing the given file names.
param
names a list of file names
return
a list of file objects
throws
IllegalArgumentException if the list of file names includes a directory
public java.lang.Iterable getLocation(Location location)
Gets the path associated with the given location.
param
location a location
return
a list of files or {@code null} if this location has no associated path
see
#setLocation
public boolean isSameFile(javax.tools.FileObject a, javax.tools.FileObject b)
Compares two file objects and return true if they represent the same canonical file, zip file entry, or entry in any file system based container.
param
a a file object
param
b a file object
return
true if the given file objects represent the same canonical file or zip file entry; false otherwise
throws
IllegalArgumentException if either of the arguments were created with another file manager implementation
public void setLocation(Location location, java.lang.Iterable path)
Associates the given path with the given location. Any previous value will be discarded.
param
location a location
param
path a list of files, if {@code null} use the default path for this location
see
#getLocation
throws
IllegalArgumentException if location is an output location and path does not contain exactly one element
throws
IOException if location is an output location and path does not represent an existing directory