JavaCompiler --JDK6 API的简介

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。