javax.tools
介面 JavaFileManager

所有父級介面：

Closeable, Flushable, OptionChecker

所有已知子介面：

StandardJavaFileManager

所有已知實作類別：

ForwardingJavaFileManager

public interface JavaFileManager
extends Closeable, Flushable, OptionChecker

在 Java™ 程式語言源和類別檔案之上進行操作的工具的檔案管理器。在這裡，檔案 是指常規檔案和其他資料源的抽象。

建構新的 JavaFileObject 時，檔案管理器必須確定創建它們的位置。例如，如果檔案管理器在檔案系統上管理常規檔案，那麼在創建或尋找檔案時，此檔案管理器很可能將當前/工作目錄作為預設位置使用。可以向檔案管理器提供許多關於在何處創建檔案的提示。檔案管理器可以選擇忽略這些提示。

此介面中的某些方法使用類別名稱。這種類別名稱必須以完全限定類別和介面名稱的 Java Virtual Machine 內部形式給定。為了方便起見，'.' 和 '/' 可以互換使用。在 Java Virtual Machine Specification 第四章中定義了內部形式。

討論：這意味著名稱 "java/lang.package-info"、"java/lang/package-info"、"java.lang.package-info" 有效並且相等。比較 Java Language Specification (JLS) 第 13.1 節 "The Form of a Binary" 中定義的二進制名稱。

名稱的大小寫很重要。所有名稱都應該區分大小寫。例如，某些檔案系統的檔案名稱大小寫不敏感 (case-insensitive)、但可區分大小寫 (case-aware)。表示此類別檔案的檔案物件應該通過使用 File.getCanonicalFile() 或類似方法來保存大小寫形式。如果系統不可區分大小寫，那麼檔案物件必須使用其他方法來保存大小寫。

相對名稱：此介面中的某些方法使用相對名稱。相對名稱是指用 '/' 分隔的路徑段的非 null、非空(null)序列。'.' 或 '..' 為無效路徑段。有效的相對名稱必須符合 RFC 3986 的第 3.3 節的“無根路徑”規則。非正式情況下，下式應該為 true：

  URI.create(relativeName).normalize().getPath().equals(relativeName)

此介面中的所有方法都可能拋出 SecurityException。

不要求此介面的物件支持多執行緒存取，也就是說，此介面中的物件是同步的。但是，它必須支持對此物件創建的不同檔案物件的共時存取。

實作注意事項： 此要求使得對 JarOutputStream 的輸出的普通實作將不夠充分。也就是說，不是創建直接返回 JarOutputStream 的 JavaFileObject，而是在關閉前必須快取記憶體內容，然後將內容寫入 JarOutputStream。

除非明確允許，否則只要給定 null 參數，此介面中的所有方法都將拋出 NullPointerException。

從以下版本開始：

1.6

另請參見：

JavaFileObject, FileObject

巢狀類別摘要

static interface

JavaFileManager.Location 檔案物件位置的介面。

方法摘要

void	close() 釋放此檔案管理器直接或間接打開的所有資源。
void	flush() 刷新此檔案管理器直接或間接為輸出打開的所有資源。
ClassLoader	getClassLoader(JavaFileManager.Location location) 獲取可從給定位置載入外掛程式的類別載入器。
FileObject	getFileForInput(JavaFileManager.Location location, String packageName, String relativeName) 獲取輸入的檔案物件，它表示給定位置處指定包中的指定相對名稱。
FileObject	getFileForOutput(JavaFileManager.Location location, String packageName, String relativeName, FileObject sibling) 獲取輸出的檔案物件，它表示給定位置處指定包中的指定相對名稱。
JavaFileObject	getJavaFileForInput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind) 獲取輸入的檔案物件，它表示給定位置處指定型別的指定類別。
JavaFileObject	getJavaFileForOutput(JavaFileManager.Location location, String className, JavaFileObject.Kind kind, FileObject sibling) 獲取輸出的檔案物件，它表示給定位置處指定型別的指定類別。
boolean	handleOption(String current, Iterator<String> remaining) 處理一個選項。
boolean	hasLocation(JavaFileManager.Location location) 確定此檔案管理器是否已知某位置。
String	inferBinaryName(JavaFileManager.Location location, JavaFileObject file) 根據位置推斷檔案物件的二進制名稱。
boolean	isSameFile(FileObject a, FileObject b) 比較兩個檔案物件，如果它們表示相同的底層物件，則返回 true。
Iterable<JavaFileObject>	list(JavaFileManager.Location location, String packageName, Set<JavaFileObject.Kind> kinds, boolean recurse) 列出給定位置處符合給定標準的所有檔案物件。

從介面 javax.tools.OptionChecker 繼承的方法

isSupportedOption

方法詳細資訊

getClassLoader

ClassLoader getClassLoader(JavaFileManager.Location location)

獲取可從給定位置載入外掛程式的類別載入器。例如，要載入註釋處理器，編譯器將請求 ANNOTATION_PROCESSOR_PATH 位置的類別載入器。

參數：

location - 位置

返回：

給定位置的類別載入器；如果不能從給定位置載入外掛程式或位置未知，則返回 null

拋出：

SecurityException - 如果在當前安全上下文中不能創建類別載入器

IllegalStateException - 如果已經調用了 close() 並且不能重新打開此檔案管理器

list

Iterable<JavaFileObject> list(JavaFileManager.Location location,
                              String packageName,
                              Set<JavaFileObject.Kind> kinds,
                              boolean recurse)
                              throws IOException

列出給定位置處符合給定標準的所有檔案物件。如果 recurse 為 true，則列出“子包”中的檔案物件。

註：即使給定位置對於此檔案管理器是未知的，此方法也不會返回 null。未知位置也不會導致異常。

參數：

location - 位置

packageName - 套件名稱

kinds - 只返回這些型別的物件

recurse - 如果為 true，則包含“子包”

返回：

符合給定標準的檔案物件的 Iterable

拋出：

IOException - 如果發生 I/O 錯誤，或者已經調用了 close() 並且無法重新打開此檔案管理器

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

inferBinaryName

String inferBinaryName(JavaFileManager.Location location,
                       JavaFileObject file)

根據位置推斷檔案物件的二進制名稱。返回的二進制名稱可能不是有效的 JLS 二進制名稱。

參數：

location - 位置

file - 檔案物件

返回：

二進制名稱；如果在給定位置沒有找到檔案物件，則返回 null

拋出：

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

isSameFile

boolean isSameFile(FileObject a,
                   FileObject b)

比較兩個檔案物件，如果它們表示相同的底層物件，則返回 true。

參數：

a - 檔案物件

b - 檔案物件

返回：

如果給定的檔案物件表示相同的底層物件，則返回 true

拋出：

IllegalArgumentException - 如果其中一個參數是用另一個檔案管理器創建的，並且此檔案管理器不支持外部檔案物件

handleOption

boolean handleOption(String current,
                     Iterator<String> remaining)

處理一個選項。如果 current 是此檔案管理器的一個選項，則它將通過 remaining 獲得該選項的所有參數並返回 true，否則返回 false。

參數：

current - 當前選項

remaining - 剩餘選項

返回：

如果由此檔案管理器處理此選項，則返回 true，否則返回 false

拋出：

IllegalArgumentException - 如果錯誤地使用了此檔案管理器的選項

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

hasLocation

boolean hasLocation(JavaFileManager.Location location)

確定此檔案管理器是否已知某位置。

參數：

location - 位置

返回：

如果已知該位置，則返回 true

getJavaFileForInput

JavaFileObject getJavaFileForInput(JavaFileManager.Location location,
                                   String className,
                                   JavaFileObject.Kind kind)
                                   throws IOException

獲取輸入的檔案物件，它表示給定位置處指定型別的指定類別。

參數：

location - 位置

className - 類別的名稱

kind - 檔案的型別，必須是 SOURCE 或 CLASS

返回：

一個檔案物件；如果檔案不存在，則可能返回 null

拋出：

IllegalArgumentException - 如果位置對於此檔案管理器未知並且該檔案管理器不支持未知位置，或者型別無效

IOException - 如果發生 I/O 錯誤，或者已經調用了 close() 並且無法重新打開此檔案管理器

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

getJavaFileForOutput

JavaFileObject getJavaFileForOutput(JavaFileManager.Location location,
                                    String className,
                                    JavaFileObject.Kind kind,
                                    FileObject sibling)
                                    throws IOException

獲取輸出的檔案物件，它表示給定位置處指定型別的指定類別。

此檔案管理器可以將 sibling 視為對放置輸出位置的提示（可選）。沒有指定此提示的確切語義。除非提供了類別檔案輸出目錄，否則 Sun 的編譯器（例如 javac）將把類別檔案放到與原始源檔案相同的目錄下。要實作此行為，調用此方法時 javac 可以提供原始源檔案作為 sibling。

參數：

location - 位置

className - 類別的名稱

kind - 檔案的型別，必須是 SOURCE 或 CLASS

sibling - 用作位置提示的檔案物件，可以為 null

返回：

輸出的檔案物件

拋出：

IllegalArgumentException - 如果 sibling 對於此檔案管理器是未知的，或者位置對於此檔案管理器是未知的並且該檔案管理器不支持未知位置，或者型別無效

IOException - 如果發生 I/O 錯誤，或者已經調用了 close() 並且無法重新打開此檔案管理器

IllegalStateException - 已經調用了 close() 並且無法重新打開此檔案管理器

getFileForInput

FileObject getFileForInput(JavaFileManager.Location location,
                           String packageName,
                           String relativeName)
                           throws IOException

獲取輸入的檔案物件，它表示給定位置處指定包中的指定相對名稱。

如果返回的物件表示源或類別檔案，則它必須是 JavaFileObject 的一個實例。

非嚴格意義上來講，在位置、套件名稱和相對名稱的串聯中尋找此方法返回的檔案物件。例如，要在 SOURCE_PATH 位置處的 "com.sun.tools.javac" 套件中尋找屬性檔案 "resources/compiler.properties"，將調用此方法，如下：

getFileForInput(SOURCE_PATH, "com.sun.tools.javac", "resources/compiler.properties");

如果在 Windows 上執行該調用，其中 SOURCE_PATH 設置為 "C:\Documents and Settings\UncleBob\src\share\classes"，那麼有效的結果將是表示檔案 "C:\Documents and Settings\UncleBob\src\share\classes\com\sun\tools\javac\resources\compiler.properties" 的檔案物件。

參數：

location - 位置

packageName - 套件名稱

relativeName - 相對名稱

返回：

檔案物件；如果檔案不存在，則可能返回 null

拋出：

IllegalArgumentException - 如果位置對於此檔案管理器是未知的並且該檔案管理器不支持未知位置，或者 relativeName 無效

IOException - 如果發生 I/O 錯誤，或者已經調用了 close() 並且無法重新打開此檔案管理器

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

getFileForOutput

FileObject getFileForOutput(JavaFileManager.Location location,
                            String packageName,
                            String relativeName,
                            FileObject sibling)
                            throws IOException

獲取輸出的檔案物件，它表示給定位置處指定包中的指定相對名稱。

此檔案管理器可能將 sibling 視為對放置輸出位置的提示（可選）。沒有指定此提示的確切語義。除非提供了類別檔案輸出目錄，否則 Sun 的編譯器（例如 javac）將把類別檔案放到與原始源檔案相同的目錄下。要實作此行為，調用此方法時 javac 可以提供原始源檔案作為 sibling。

如果返回的物件表示源或類別檔案，則它必須是 JavaFileObject 的一個實例。

非正式情況下，在位置、套件名稱和相對名稱的串聯或 sibling 參數的同級元素中尋找此方法返回的檔案物件。有關範例，請參閱 getFileForInput。

參數：

location - 位置

packageName - 套件名稱

relativeName - 相對名稱

sibling - 用作位置提示的檔案物件；可以為 null

返回：

檔案物件

拋出：

IllegalArgumentException - 如果 sibling 對於此檔案管理器是未知的，或者位置對於此檔案管理器是未知的並且該檔案管理器不支持未知位置，或者 relativeName 無效

IOException - 如果發生 I/O 錯誤，或者已經調用了 close() 並且無法重新打開此檔案管理器

IllegalStateException - 如果已經調用了 close() 並且無法重新打開此檔案管理器

flush

void flush()
           throws IOException

刷新此檔案管理器直接或間接為輸出打開的所有資源。刷新已關閉的檔案管理器沒有任何效果。

指定者：

介面 Flushable 中的 flush

拋出：

IOException - 如果發生 I/O 錯誤

另請參見：

close()

close

void close()
           throws IOException

釋放此檔案管理器直接或間接打開的所有資源。這會使得此檔案管理器無效，除非明確允許，否則對此物件上的方法或通過此物件獲取的所有物件進行後續調用都將導致不確定的結果。但是，關閉已經關閉的檔案管理器沒有任何效果。

指定者：

介面 Closeable 中的 close

拋出：

IOException - 如果發生 I/O 錯誤

另請參見：

flush()