Java编译器API

本文是我们名为“ 高级Java ”的学院课程的一部分。

本课程旨在帮助您最有效地使用Java。它讨论了高级主题，包括对象创建，并发，序列化，反射等。它将指导您完成Java掌握的过程！在这里查看！

1.简介

在本部分的教程中，我们将对Java编译器API进行10000英尺的观察。该API提供了对Java编译器本身的编程访问，并允许开发人员从应用程序代码中即时从源文件编译Java类。

更有趣的是，我们还将遍历Java编译器树API，该API提供对Java语法分析器功能的访问。通过使用此API，Java开发人员可以直接插入语法分析阶段并对正在编译的Java源代码进行后期分析。它是一个非常强大的API，许多静态代码分析工具都大量使用它。

Java Compiler API还支持注释处理（有关更多详细信息，请参阅本教程的第5部分 ， 如何和何时使用Enums和Annotations ，更多内容将在本教程的第14部分 ， Annotation Processors中提供 ），并且分为三个不同的包，如下表所示。

包	描述
javax.annotation.processing	注释处理。
javax.lang.model	注释处理和Compiler Tree API中使用的语言模型（包括Java语言元素，类型和实用程序类）。
javax.tools	Java编译器API本身。

另一方面，Java编译器树API托管在com.sun.source package下，并且遵循Java标准库的命名约定，被认为是非标准的（专有的或内部的）。通常，这些API没有得到很好的文档记录或支持，并且可能随时更改。而且，它们与特定的JDK / JRE版本相关联，并且可能会限制使用它们的应用程序的可移植性。

2. Java编译器API

我们的探索将从Java Compiler API开始，该文件已被很好地记录且易于使用。 Java Compiler API的入口点是ToolProvider类，该类允许获取系统中可用的Java编译器实例（官方文档是熟悉典型用法场景的一个很好的起点）。例如：

final JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();        
for( final SourceVersion version: compiler.getSourceVersions() ) {System.out.println( version );
}

此小代码段获取Java编译器实例，并在控制台上打印出受支持的Java源版本的列表。对于Java 7编译器，输出如下所示：

RELEASE_3
RELEASE_4
RELEASE_5
RELEASE_6
RELEASE_7

它对应于多个公知的Java版本方案：1.3，1.4，5，6和7。对于Java 8编译器，受支持的版本列表看起来更长：

RELEASE_3
RELEASE_4
RELEASE_5
RELEASE_6
RELEASE_7
RELEASE_8

一旦Java编译器实例可用，就可以将其用于对Java源文件集执行不同的编译任务。但是在此之前，应准备好一组编译单元和诊断收集器（以收集所有遇到的编译错误）。为了进行试验，我们将编译存储在SampleClass.java源文件中的这个简单Java类：

public class SampleClass {public static void main(String[] args) {System.out.println( "SampleClass has been compiled!" );}
}

创建此源文件后，让我们实例化诊断收集器并配置要编译的源文件列表（仅包含SampleClass.java ）。

final DiagnosticCollector< JavaFileObject > diagnostics = new DiagnosticCollector<>();
final StandardJavaFileManager manager = compiler.getStandardFileManager( diagnostics, null, null );final File file = new File( CompilerExample.class.getResource("/SampleClass.java").toURI() );final Iterable< ? extends JavaFileObject > sources = manager.getJavaFileObjectsFromFiles( Arrays.asList( file ) );

准备工作完成后，最后一步基本上是调用Java编译器任务，将诊断收集器和源文件列表传递给它，例如：

final CompilationTask task = compiler.getTask( null, manager, diagnostics, null, null, sources );            
task.call();

基本上就是这样。编译任务完成后，应该在target / classes文件夹中提供SampleClass.class 。我们可以运行它以确保编译已成功执行：

java -cp target/classes SampleClass

以下输出将显示在控制台上，确认源文件已正确编译为字节码：

SampleClass has been compiled!

如果在编译过程中遇到任何错误，它们将通过诊断收集器变为可用（默认情况下，任何其他编译器输出也将被打印到System.err ）。为了说明这一点，让我们尝试编译示例Java源文件，该文件有意包含一些错误（ SampleClassWithErrors.java ）：

private class SampleClassWithErrors {public static void main(String[] args) {System.out.println( "SampleClass has been compiled!" );}
}

编译过程应该失败，并且可以从诊断收集器中检索错误消息（包括行号和源文件名），例如：

for( final Diagnostic< ? extends JavaFileObject > diagnostic: diagnostics.getDiagnostics() ) {System.out.format("%s, line %d in %s", diagnostic.getMessage( null ),diagnostic.getLineNumber(),diagnostic.getSource().getName() );
}

在SampleClassWithErrors.java源文件上调用编译任务将在控制台上打印出以下示例错误描述：

modifier private not allowed here, line 1 in SampleClassWithErrors.java

最后但并非最不重要的一点是，为了正确完成Java Compiler API的使用，请不要忘记关闭文件管理器：

manager.close();

甚至更好的是，始终使用try-with-resources构造（本教程的第8部分“ 如何以及何时使用Exceptions”已经介绍过）：

try( final StandardJavaFileManager manager = compiler.getStandardFileManager( diagnostics, null, null ) ) {// Implementation here            
}

简而言之，这些是Java Compiler API的典型使用场景。在处理更复杂的示例时，有一些细微但非常重要的细节，可以极大地加快编译过程。要了解更多信息，请参考官方文档。

3.注释处理器

幸运的是，编译过程不仅限于编译。 Java Compiler支持注释处理器，可以将其视为编译器插件。顾名思义，注释处理器可以对正在编译的代码执行加法处理（通常由注释驱动）。

在本教程的第14部分“ 注释处理器”中 ，我们将更全面地介绍注释处理器。目前，请参阅官方文档以获取更多详细信息。

4.元素扫描仪

有时，在编译过程中，有必要对所有语言元素（类，方法/构造函数，字段，参数，变量等）进行浅层分析。为此，Java编译器API提供了元素扫描器的概念。元素扫描器是围绕访问者模式构建的，基本上需要实现单个扫描器（和访问者）。为了简化实现，请提供一组基类。

我们将要开发的示例非常简单，足以展示元素扫描仪用法的基本概念，并将计算所有编译单元中的所有类，方法和字段。基本的扫描器/访问者实现扩展了ElementScanner7类，并且仅覆盖其感兴趣的方法：

public class CountClassesMethodsFieldsScanner extends ElementScanner7< Void, Void > {private int numberOfClasses;private int numberOfMethods;private int numberOfFields;public Void visitType( final TypeElement type, final Void p ) {++numberOfClasses;return super.visitType( type, p );}public Void visitExecutable( final ExecutableElement executable, final Void p ) {++numberOfMethods;return super.visitExecutable( executable, p );}public Void visitVariable( final VariableElement variable, final Void p ) {if ( variable.getEnclosingElement().getKind() == ElementKind.CLASS ) {++numberOfFields;}return super.visitVariable( variable, p );}
}

关于元素扫描器的快速说明： ElementScannerX类家族对应于特定的Java版本。例如， ElementScanner8对应于Java 8 ， ElementScanner7对应于Java 7 ， ElementScanner6对应于Java 6 ，依此类推。所有这些类的确有一个visitXxx方法族，其中包括：

方法	描述
visitPackage	访问包元素。
visitType	访问类型元素。
visitVariable	访问变量元素。
visitExecutable	访问可执行元素。
visitTypeParameter	访问类型参数元素。

在编译过程中调用扫描器（和访问者）的一种方法是使用注释处理器。让我们通过扩展AbstractProcessor类来定义一个（请注意，注释处理器也与特定的Java版本紧密相关，在我们的示例中为Java 7 ）：

@SupportedSourceVersion( SourceVersion.RELEASE_7 )
@SupportedAnnotationTypes( "*" )
public class CountElementsProcessor extends AbstractProcessor {private final CountClassesMethodsFieldsScanner scanner;public CountElementsProcessor( final CountClassesMethodsFieldsScanner scanner ) {this.scanner = scanner;}public boolean process( final Set< ? extends TypeElement > types, final RoundEnvironment environment ) {if( !environment.processingOver() ) {for( final Element element: environment.getRootElements() ) {scanner.scan( element );}}return true;}
}

基本上，注释处理器只是将所有艰苦的工作委托给我们之前定义的扫描程序实现（在本教程的第14部分“ 注释处理器”中 ，我们将提供更全面的注释处理器示例）。

SampleClassToParse.java文件是示例，我们将在其中编译和计算所有类，方法/构造函数和字段：

public class SampleClassToParse {private String str;private static class InnerClass {     private int number;public void method() {int i = 0;try {// Some implementation here} catch( final Throwable ex ) {// Some implementation here}}}public static void main( String[] args ) {System.out.println( "SampleClassToParse has been compiled!" );}
}

编译过程看起来与我们在Java Compiler API部分中所看到的完全一样。唯一的区别是，编译任务应配置有注释处理器实例。为了说明这一点，让我们看一下下面的代码片段：

final CountClassesMethodsFieldsScanner scanner = new CountClassesMethodsFieldsScanner();
final CountElementsProcessor processor = new CountElementsProcessor( scanner );final CompilationTask task = compiler.getTask( null, manager, diagnostics, null, null, sources );
task.setProcessors( Arrays.asList( processor ) );
task.call();System.out.format( "Classes %d, methods/constructors %d, fields %d",scanner.getNumberOfClasses(),scanner.getNumberOfMethods(), scanner.getNumberOfFields() );

针对SampleClassToParse.java源文件执行编译任务将在控制台中输出以下消息：

Classes 2, methods/constructors 4, fields 2

这很有意义：声明了两个类， SampleClassToParse和InnerClass 。 SampleClassToParse类具有default constructor （隐式定义），方法main和字段str 。反过来， InnerClass类也具有default constructor （隐式定义），方法method和字段number 。

这个例子很幼稚，但是它的目的不是展示花哨的东西，而是介绍基本概念（教程的第14部分 ， 注释处理器 ，将包括更完整的例子）。

5. Java编译器树API

元素扫描仪非常有用，但是它们提供的访问权限非常有限。有时需要将Java源文件解析为抽象语法树（或AST ）并执行更深入的分析。 Java编译器树API是我们实现它所需要的工具。 Java编译器树API与Java编译器API紧密合作，并使用javax.lang.model包。

Java编译器树API的用法与“元素扫描器”部分中的元素扫描器非常相似，并且是按照相同的模式构建的。让我们重用Element Scanners部分中的示例源文件SampleClassToParse.java ，并计算所有编译单元中存在多少空try/catch块。为此，我们必须通过扩展TreePathScanner基类来定义树路径扫描器（和访问者），类似于元素扫描器（和访问者）。

public class EmptyTryBlockScanner extends TreePathScanner< Object, Trees > {private int numberOfEmptyTryBlocks;@Overridepublic Object visitTry(final TryTree tree, Trees trees) {if( tree.getBlock().getStatements().isEmpty() ){++numberOfEmptyTryBlocks;}return super.visitTry( tree, trees );}public int getNumberOfEmptyTryBlocks() {return numberOfEmptyTryBlocks;}
}

与元素扫描器相比， visitXxx方法的数量要丰富visitXxx （大约50种方法），并且涵盖所有Java语言语法构造。与元素扫描器一样，调用树路径扫描器的方法之一也是通过定义专用注释处理器，例如：

@SupportedSourceVersion( SourceVersion.RELEASE_7 )
@SupportedAnnotationTypes( "*" )
public class EmptyTryBlockProcessor extends AbstractProcessor {private final EmptyTryBlockScanner scanner;private Trees trees;public EmptyTryBlockProcessor( final EmptyTryBlockScanner scanner ) {this.scanner = scanner;}@Overridepublic synchronized void init( final ProcessingEnvironment processingEnvironment ) {super.init( processingEnvironment );trees = Trees.instance( processingEnvironment );}public boolean process( final Set< ? extends TypeElement > types, final RoundEnvironment environment ) {if( !environment.processingOver() ) {for( final Element element: environment.getRootElements() ) {scanner.scan( trees.getPath( element ), trees );}}return true;}
}

初始化过程变得有点复杂，因为我们必须获取Trees类的实例并将每个元素转换为树路径表示形式。此时，编译步骤应该看起来非常熟悉并且足够清晰。为了使它更具趣味性，让我们针对到目前为止我们已经尝试过的所有源文件运行它： SampleClassToParse.java和SampleClass.java 。

final EmptyTryBlockScanner scanner = new EmptyTryBlockScanner();
final EmptyTryBlockProcessor processor = new EmptyTryBlockProcessor( scanner );final Iterable<? extends JavaFileObject> sources = manager.getJavaFileObjectsFromFiles( Arrays.asList( new File(CompilerExample.class.getResource("/SampleClassToParse.java").toURI()),new File(CompilerExample.class.getResource("/SampleClass.java").toURI())) 
);final CompilationTask task = compiler.getTask( null, manager, diagnostics, null, null, sources );
task.setProcessors( Arrays.asList( processor ) );
task.call();System.out.format( "Empty try/catch blocks: %d", scanner.getNumberOfEmptyTryBlocks() );

一旦针对多个源文件运行，上面的代码段将在控制台中打印以下输出：

Empty try/catch blocks: 1

Java编译器树API可能看起来有点低级，的确如此。另外，作为内部API，它没有受支持的文档。但是，它提供了对抽象语法树的完全访问权限，当您需要执行深入的源代码分析和后处理时，它可以节省生命。

6.接下来

在本教程的这一部分中，我们研究了从Java应用程序内部对Java Compiler API的编程访问。我们还挖掘了更深层次，更动人的注释处理器和未发现的Java编译器树API，该API提供了对正在编译的Java源文件（编译单元）的抽象语法树的完整访问。在本教程的下一部分中，我们将以同样的方式继续，并进一步注解注释处理器及其适用性。