javax.annotation.processing
介面 Filer

public interface Filer

此介面支持通過註釋處理器創建新檔案。以這種方式創建的檔案對於實作此介面的註釋處理工具將是已知的，這比啟用工具來管理它們更好。在對用來編寫檔案內容的 Writer 或 OutputStream 調用 close 方法之後，以這種方式創建的源檔案和類別檔案被認為將由管理它們的工具處理。有三類別檔案要加以區分：源檔案、類別檔案和輔助資源檔案。

新創建的檔案被放置在兩個不同的受支持位置（邏輯檔案系統中的子階層樹）：一個用於新的源檔案，一個用於新的類別檔案。（這可以在工具的命令行上指定，例如，使用 -s 和 -d 之類別的標誌。）新的源檔案和類別檔案的實際位置在工具的特定運行時刻可能是不同的，也可能是相同的。資源檔案可以在其中一個位置上創建。用來讀取和寫入資源的方法採用了一個相對名稱參數。相對名稱是用 '/' 分隔的、非 null、非空(null)的路徑段序列；'.' 和 '..' 都是無效的路徑段。有效的相對名稱必須符合 RFC 3986 的第 3.3 節的“無根路徑”規則。

檔案創建方法帶有可變數量的參數，以允許提供原始元素 作為工具基礎設施的提示，從而更好地管理依賴關係。原始元素是造成註釋處理器試圖創建新檔案的型別或包（表示 package-info 檔案）。例如，如果註釋處理器試圖創建一個源檔案 GeneratedFromUserSource 以回應處理

@Generate
public class UserSource {}
 

那麼 UserSource 的型別元素應該作為創建方法調用的一部分傳入，如下所示：

filer.createSourceFile("GeneratedFromUserSource",
eltUtils.getTypeElement("UserSource"));
 

如果沒有原始元素，則什麼都不需要傳遞。此資訊可以在增量環境中使用，以確定是需要重新運行處理器還是移除產生的檔案。非增量環境可以忽略原始元素資訊。

在每次運行註釋處理工具期間，具有給定路徑名的檔案只能被創建一次。如果該檔案在第一次試圖創建它之前就已經存在，則將刪除原有的內容。在運行期間，任何試圖創建相同檔案的後續嘗試都將拋出 FilerException，試圖針對相同的型別名稱和相同的套件名稱創建類別檔案和源檔案也將如此。工具的初始輸入被認為是由第 0 個 round 創建的；因此，試圖創建一個與那些輸入之一對應的源檔案或類別檔案將導致 FilerException。

通常，處理器不得有意嘗試覆寫不是由某個處理器產生的現有檔案。Filer 可能拒絕嘗試打開與現有型別對應的檔案，如 java.lang.Object。同樣，註釋處理工具的調用者不得有意配置該工具，使得已發現的處理器將嘗試覆寫尚未產生的現有檔案。

處理器可以通過包含 @Generated 註釋來指示產生源檔案或類別檔案。

注意，覆寫檔案的某些效果可通過使用裝飾 樣式網要來實作。類別被設計為其父級類別由註釋處理產生，或者其子類別由註釋處理產生，而不是直接修改該類別。如果產生子類別，則父類別可以被設計為使用處理器而不是公共建構子，這樣只有子類別實例被呈現給父類別的客戶端。

從以下版本開始：

1.6

方法摘要

JavaFileObject	createClassFile(CharSequence name, Element... originatingElements) 創建一個新的類別檔案，並返回一個物件以允許寫入它。
FileObject	createResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName, Element... originatingElements) 創建一個用於寫入操作的新輔助資源檔案，並為它返回一個檔案物件。
JavaFileObject	createSourceFile(CharSequence name, Element... originatingElements) 創建一個新的源檔案，並返回一個物件以允許寫入它。
FileObject	getResource(JavaFileManager.Location location, CharSequence pkg, CharSequence relativeName) 返回一個用於讀取現有資源的物件。

方法詳細資訊

createSourceFile

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

創建一個新的源檔案，並返回一個物件以允許寫入它。檔案的名稱和路徑（相對於源檔案的根目錄輸出位置）基於該檔案中宣告的型別。如果宣告的型別不止一個，則應該使用主要頂層型別的名稱（例如，宣告為 public 的那個）。還可以創建源檔案來保存有關某個套件的資訊，包括包註釋。要為指定包創建源檔案，可以用 name 作為套件名稱，後跟 ".package-info"；要為未指定的套件創建源檔案，可以使用 "package-info"。

注意，若要使用特定 charset 來編碼檔案內容，可以從返回物件的 OutputStream 創建具有選定字元集的 OutputStreamWriter。如果將所返回物件中的 Writer 直接用於寫入操作，則其字元集由實作確定。註釋處理工具可以有一個用來指出這一點的 -encoding 標誌或類似選項；否則，它通常將是平臺的預設編碼。

為了避免後續錯誤，源檔案的內容應該與將用於此運行的源版本相容。

參數：

name - 將在此檔案中宣告的主要型別的規範（完全限定）名稱；對於包資訊檔案，則是後跟 ".package-info" 的套件名稱

originatingElements - 與此檔案的創建有因果關聯的型別或包元素，該參數可以省略或者為 null

返回：

寫入新源檔案的 JavaFileObject

拋出：

FilerException - 如果創建了相同的路徑名，創建了相同的型別，或者名稱對於某一型別無效

IOException - 如果無法創建檔案

createClassFile

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

創建一個新的類別檔案，並返回一個物件以允許寫入它。檔案的名稱和路徑（相對於類別檔案的根目錄輸出位置）基於將寫入的型別名稱。還可以創建類別檔案來保存有關某個套件的資訊，包括包註釋。要為指定包創建類別檔案，可以用 name 作為套件名稱，後跟 ".package-info"；為未指定的套件創建類別檔案不受支持。

為了避免後續錯誤，類別檔案的內容應該與將用於此運行的源版本相容。

參數：

name - 將寫入的型別的二進制名稱；對於包資訊檔案，是後跟 ".package-info" 的套件名稱

originatingElements - 與此檔案的創建有因果關聯的型別或包元素，該參數可以省略或者為 null

返回：

寫入新類別檔案的 JavaFileObject

拋出：

FilerException - 如果創建了相同的路徑名，創建了相同的型別，或者名稱對於某一型別無效

IOException - 如果無法創建檔案

createResource

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

創建一個用於寫入操作的新輔助資源檔案，並為它返回一個檔案物件。該檔案可以與新創建的源檔案、新創建的二進制檔案或者其他受支持的位置一起被尋找。位置 CLASS_OUTPUT 和 SOURCE_OUTPUT 必須受支持。資源可以是相對於某個包（該套件是源檔案和類別檔案）指定的，並通過相對路徑名從中取出。從不太嚴格的角度說，新檔案的完全路徑名將是 location、pkg 和 relativeName 的串聯。

通過此方法創建的檔案並不是為了進行註釋處理而註冊的，即使檔案的完全路徑名對應於新的源檔案或類別檔案的完全路徑名也是如此。

參數：

location - 新檔案的位置

pkg - 檔案將相對於其進行指定的套件；如果沒有這樣的套件，則該參數是一個空字元串

relativeName - 檔案的最終路徑名部分

originatingElements - 與此檔案的創建有因果關聯的型別或包元素，該參數可以忽略或者為 null

返回：

寫入新資源的 FileObject

拋出：

IOException - 如果無法創建檔案

FilerException - 如果創建了相同的路徑名

IllegalArgumentException - 如果位置不受支持

IllegalArgumentException - 如果 relativeName 不是相對名稱

getResource

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

返回一個用於讀取現有資源的物件。位置 CLASS_OUTPUT 和 SOURCE_OUTPUT 必須受支持。

參數：

location - 檔案的位置

pkg - 將相對於其進行檔案搜尋的套件；如果沒有這樣的套件，則該參數為一個空字元串

relativeName - 檔案的最終路徑名部分

返回：

讀取檔案的物件

拋出：

FilerException - 如果已經為寫入操作打開相同的路徑名

IOException - 如果無法打開檔案

IllegalArgumentException - 如果位置不受支持

IllegalArgumentException - 如果 relativeName 不是相對名稱