JavaTM Platform
Standard Ed. 6

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,但最好不要在应用程序中使用接口 DiagnosticListenerJavaFileManagerFileObjectJavaFileObject。应该实现这些接口,用于为编译器提供自定义服务,从而定义编译器的 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();
ForwardingJavaFileManagerForwardingFileObjectForwardingJavaFileObject
子类化不可用于重写标准文件管理器的行为,因为标准文件管理器是通过调用编译器上的方法创建的,而不是通过调用构造方法创建的。应该使用转发(或委托)。允许自定义行为时,这些类使得将多个调用转发到给定文件管理器或文件对象变得容易。例如,考虑如何将所有的调用记录到 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)
为此工具获取一个标准文件管理器实现的新实例。文件管理器将使用给定的诊断侦听器来生成所有非致命诊断信息。将用适当的异常来指示致命错误。

如果调用 flushclose 后访问标准文件管理器,则它将被自动重新打开。标准文件管理器必须与其他工具一起使用。

参数:
diagnosticListener - 用于非致命诊断信息的诊断侦听器;如果为 null,则使用编译器的默认方法来报告诊断信息
locale - 格式化诊断信息时要应用的语言环境;如果为 null,则使用默认语言环境
charset - 用于解码字节的字符集;如果为 null,则使用平台默认的字符集
返回:
标准文件管理器

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策