javax.tools
介面 JavaCompiler

所有父級介面：

OptionChecker, Tool

public interface JavaCompiler
extends Tool, OptionChecker

從程序中調用 Java™ 程式語言編譯器的介面。

編譯過程中，編譯器可能產生診斷資訊（例如，錯誤訊息）。如果提供了診斷偵聽器，那麼診斷資訊將被提供給該偵聽器。如果沒有提供偵聽器，那麼除非另行指定，否則診斷資訊將被格式化為未指定的格式，並被寫入到預設輸出 System.err。即使提供了診斷偵聽器，某些診斷資訊也可能不適合 Diagnostic，並將被寫入到預設輸出。

編譯器工具具有關聯的標準檔案管理器，此檔案管理器是工具本地的（或內置的）。可以通過調用 getStandardFileManager 獲取該標準檔案管理器。

只要滿足下面方法詳細描述中的任意附加需求，編譯器工具就必須與檔案管理器一起運行。如果沒有提供檔案管理器，則編譯器工具將使用標準檔案管理器，比如 getStandardFileManager 返回的標準檔案管理器。

實作此介面的實例必須符合 Java Language Specification 並遵照 Java Virtual Machine 規範產生類別檔案。Tool 介面中定義了這些規範的版本。 此外，支持 SourceVersion.RELEASE_6 或更高版本的此介面的實例還必須支持註釋處理。

編譯器依賴於兩種服務：診斷偵聽器和檔案管理器。雖然此套件中的大多數類別和介面都定義了編譯器（和一般工具）的 API，但最好不要在應用程序中使用介面 DiagnosticListener、JavaFileManager、FileObject 和 JavaFileObject。應該實作這些介面，用於為編譯器提供自定義服務，從而定義編譯器的 SPI。

此套件中有很多類別和介面，它們被設計用於簡化 SPI 的實作，以自定義編譯器行為：

StandardJavaFileManager

實作此介面的每個編譯器都提供一個標準的檔案管理器，以便在常規檔案上進行操作。StandardJavaFileManager 介面定義了從常規檔案創建檔案物件的其他方法。

標準檔案管理器有兩個用途：

• 自定義編譯器如何讀寫檔案的基本建構塊
• 在多個編譯任務之間共享

重新使用檔案管理器可能會減少掃瞄檔案系統和讀取 jar 檔案的開銷。標準檔案管理器必須與多個順序編譯共同工作，儘管這樣做並不能減少開銷，下例是建議的編碼網要：

Files[] files1 = ...; // input for first compilation task
Files[] files2 = ...; // input for second compilation task

JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
StandardJavaFileManager fileManager = compiler.getStandardFileManager(null, null, null);

Iterable<? extends JavaFileObject> compilationUnits1 =
fileManager.getJavaFileObjectsFromFiles(Arrays.asList(files1));
compiler.getTask(null, fileManager, null, null, null, compilationUnits1).call();

Iterable<? extends JavaFileObject> compilationUnits2 =
fileManager.getJavaFileObjects(files2); // use alternative method
// reuse the same file manager to allow caching of jar files
compiler.getTask(null, fileManager, null, null, null, compilationUnits2).call();

fileManager.close();

DiagnosticCollector

用於將診斷資訊收集在一個列表中，例如：

Iterable<? extends JavaFileObject> compilationUnits = ...;
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
DiagnosticCollector<JavaFileObject> diagnostics = new DiagnosticCollector<JavaFileObject>();
StandardJavaFileManager fileManager = compiler.getStandardFileManager(diagnostics, null, null);
compiler.getTask(null, fileManager, diagnostics, null, null, compilationUnits).call();

for (Diagnostic diagnostic :diagnostics.getDiagnostics())
System.out.format("Error on line %d in %d%n",
diagnostic.getLineNumber()
diagnostic.getSource().toUri());

fileManager.close();

ForwardingJavaFileManager、ForwardingFileObject 和 ForwardingJavaFileObject

子類別化不可用於覆寫標準檔案管理器的行為，因為標準檔案管理器是通過調用編譯器上的方法創建的，而不是通過調用建構子創建的。應該使用轉發（或委託）。允許自定義行為時，這些類別使得將多個調用轉發到給定檔案管理器或檔案物件變得容易。例如，考慮如何將所有的調用記錄到 JavaFileManager.flush()：

final Logger logger = ...;
Iterable<? extends JavaFileObject> compilationUnits = ...;
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
StandardJavaFileManager stdFileManager = compiler.getStandardFileManager(null, null, null);
JavaFileManager fileManager = new ForwardingJavaFileManager(stdFileManager) {
public void flush() {
logger.entering(StandardJavaFileManager.class.getName(), "flush");
super.flush();
logger.exiting(StandardJavaFileManager.class.getName(), "flush");
           }
       };
compiler.getTask(null, fileManager, null, null, null, compilationUnits).call();

SimpleJavaFileObject

此類別提供基本檔案物件實作，該實作可用作創建檔案物件的建構塊。例如，下例顯示了如何定義表示存儲在字元串中的源程式碼的檔案物件：

       /**
* A file object used to represent source coming from a string.
*/
public class JavaSourceFromString extends SimpleJavaFileObject {
           /**
* The source code of this "file".
*/
final String code;

           /**
* Constructs a new JavaSourceFromString.
* @param name the name of the compilation unit represented by this file object
* @param code the source code for the compilation unit represented by this file object
*/
JavaSourceFromString(String name, String code) {
super(URI.create("string:///" + name.replace('.','/') + Kind.SOURCE.extension),
Kind.SOURCE);
this.code = code;
           }

@Override
public CharSequence getCharContent(boolean ignoreEncodingErrors) {
return code;
           }
       }

從以下版本開始：

1.6

另請參見：

DiagnosticListener, Diagnostic, JavaFileManager

巢狀類別摘要

static interface

JavaCompiler.CompilationTask 表示編譯任務的 future 的介面。

方法摘要

StandardJavaFileManager	getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener, Locale locale, Charset charset) 為此工具獲取一個標準檔案管理器實作的新實例。
JavaCompiler.CompilationTask	getTask(Writer out, JavaFileManager fileManager, DiagnosticListener<? super JavaFileObject> diagnosticListener, Iterable<String> options, Iterable<String> classes, Iterable<? extends JavaFileObject> compilationUnits) 使用給定元件和參數創建編譯任務的 future。

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

getSourceVersions, run

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

isSupportedOption

方法詳細資訊

getTask

JavaCompiler.CompilationTask getTask(Writer out,
                                     JavaFileManager fileManager,
                                     DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                     Iterable<String> options,
                                     Iterable<String> classes,
                                     Iterable<? extends JavaFileObject> compilationUnits)

使用給定元件和參數創建編譯任務的 future。該編譯可能沒有完成，正如 CompilationTask 介面中所述。

如果提供了檔案管理器，則它必須能夠處理 StandardLocation 中定義的所有位置。

參數：

out - 用於來自編譯器的其他輸出的 Writer；如果為 null，則使用 System.err

fileManager - 檔案管理器；如果為 null，則使用編譯器的標準檔案管理器

diagnosticListener - 診斷偵聽器；如果為 null，則使用編譯器的預設方法報告診斷資訊

options - 編譯器選項；null 表示沒有選項

classes - 類別名稱（用於註釋處理），null 表示沒有類別名稱

compilationUnits - 要編譯的編譯單元；null 表示沒有編譯單元

返回：

表示編譯的物件

拋出：

RuntimeException - 如果在使用者提供的元件中發生不可恢復的錯誤。cause 為使用者程式碼中的錯誤。

IllegalArgumentException - 如果給定的任一編譯單元具有不同於 source 的型別

getStandardFileManager

StandardJavaFileManager getStandardFileManager(DiagnosticListener<? super JavaFileObject> diagnosticListener,
                                               Locale locale,
                                               Charset charset)

為此工具獲取一個標準檔案管理器實作的新實例。檔案管理器將使用給定的診斷偵聽器來產生所有非致命診斷資訊。將用適當的異常來指示致命錯誤。

如果調用 flush 或 close 後存取標準檔案管理器，則它將被自動重新打開。標準檔案管理器必須與其他工具一起使用。

參數：

diagnosticListener - 用於非致命診斷資訊的診斷偵聽器；如果為 null，則使用編譯器的預設方法來報告診斷資訊

locale - 格式化診斷資訊時要應用的語言環境；如果為 null，則使用預設語言環境。

charset - 用於解碼位元組的字元集；如果為 null，則使用平臺預設的字元集

返回：

標準檔案管理器