Javaコンパイラプラグインの作成
1. 概要
Java 8は、Javacプラグインを作成するためのAPIを提供します。 残念ながら、そのための適切なドキュメントを見つけるのは困難です。
この記事では、*.classファイルにカスタムコードを追加するコンパイラ拡張機能を作成するプロセス全体を示します。
2. セットアップ
まず、プロジェクトの依存関係としてJDKのtools.jarを追加する必要があります。
com.sun
tools
1.8.0
system
${java.home}/../lib/tools.jar
Every compiler extension is a class which implements com.sun.source.util.Plugin interface.この例で作成しましょう:
この例で作成しましょう:
public class SampleJavacPlugin implements Plugin {
@Override
public String getName() {
return "MyPlugin";
}
@Override
public void init(JavacTask task, String... args) {
Context context = ((BasicJavacTask) task).getContext();
Log.instance(context)
.printRawLines(Log.WriterKind.NOTICE, "Hello from " + getName());
}
}
今のところ、コードが正常に取得されてコンパイルに含まれるように、「Hello」を出力しています。
最終目標は、特定のアノテーションでマークされたすべての数値引数にランタイムチェックを追加するプラグインを作成し、引数が条件に一致しない場合は例外をスローすることです。
拡張機能をJavac:it should be exposed through the ServiceLoader framework.で検出できるようにするために必要な手順がもう1つあります
これを実現するには、プラグインの完全修飾クラス名(com.example.javac.SampleJavacPlugin)であるコンテンツを含むcom.sun.source.util.Pluginという名前のファイルを作成し、それをMETA-INF/servicesディレクトリに配置する必要があります。
その後、-Xplugin:MyPluginスイッチでJavacを呼び出すことができます。
example/tutorials$ javac -cp ./core-java/target/classes -Xplugin:MyPlugin ./core-java/src/main/java/com/example/javac/TestClass.java
Hello from MyPlugin
we must always use a String returned from the plugin’s getName() method as a -Xplugin option valueに注意してください。
3. プラグインのライフサイクル
plugin is called by the compiler only once, through the init() method.
後続のイベントの通知を受けるには、コールバックを登録する必要があります。 これらは、ソースファイルごとのすべての処理段階の前後に到着します。
-
PARSE –Abstract Syntax Tree(AST)を構築します
-
ENTER –ソースコードのインポートが解決されます
-
ANALYZE –パーサー出力(AST)のエラーが分析されます
-
GENERATE –ターゲットソースファイルのバイナリを生成します
さらに2つのイベントの種類があります–ANNOTATION_PROCESSINGとANNOTATION_PROCESSING_ROUNDですが、ここではそれらに関心がありません。
たとえば、ソースコード情報に基づいていくつかのチェックを追加することでコンパイルを強化したい場合、PARSE finishedイベントハンドラーでそれを行うのが合理的です。
public void init(JavacTask task, String... args) {
task.addTaskListener(new TaskListener() {
public void started(TaskEvent e) {
}
public void finished(TaskEvent e) {
if (e.getKind() != TaskEvent.Kind.PARSE) {
return;
}
// Perform instrumentation
}
});
}
4. ASTデータの抽出
We can get an AST generated by the Java compiler through the TaskEvent.getCompilationUnit().その詳細は、TreeVisitorインターフェースを介して調べることができます。
accept()メソッドが呼び出されるTree要素のみが、指定された訪問者にイベントをディスパッチすることに注意してください。
たとえば、ClassTree.accept(visitor)を実行すると、visitClass()のみがトリガーされます。たとえば、特定のクラスのすべてのメソッドに対してvisitMethod()もアクティブ化されるとは期待できません。
TreeScannerを使用して、問題を克服できます。
public void finished(TaskEvent e) {
if (e.getKind() != TaskEvent.Kind.PARSE) {
return;
}
e.getCompilationUnit().accept(new TreeScanner() {
@Override
public Void visitClass(ClassTree node, Void aVoid) {
return super.visitClass(node, aVoid);
@Override
public Void visitMethod(MethodTree node, Void aVoid) {
return super.visitMethod(node, aVoid);
}
}, null);
}
この例では、super.visitXxx(node, value)を呼び出して、現在のノードの子を再帰的に処理する必要があります。
5. ASTを変更する
ASTを変更する方法を紹介するために、@Positiveアノテーションでマークされたすべての数値引数のランタイムチェックを挿入します。
これは、メソッドパラメータに適用できる簡単な注釈です。
@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.PARAMETER})
public @interface Positive { }
アノテーションの使用例は次のとおりです。
public void service(@Positive int i) { }
最後に、バイトコードを次のようなソースからコンパイルされたように見せたいと思います。
public void service(@Positive int i) {
if (i <= 0) {
throw new IllegalArgumentException("A non-positive argument ("
+ i + ") is given as a @Positive parameter 'i'");
}
}
これが意味するのは、0以下の@Positiveでマークされたすべての引数に対してIllegalArgumentExceptionがスローされることです。
5.1. インストルメントする場所
インストルメンテーションを適用する必要があるターゲットの場所を見つける方法を見つけましょう。
private static Set TARGET_TYPES = Stream.of(
byte.class, short.class, char.class,
int.class, long.class, float.class, double.class)
.map(Class::getName)
.collect(Collectors.toSet());
簡単にするために、ここではプリミティブな数値タイプのみを追加しました。
次に、パラメータにTARGET_TYPESセットのタイプと@PositiveアノテーションがあるかどうかをチェックするshouldInstrument()メソッドを定義しましょう。
private boolean shouldInstrument(VariableTree parameter) {
return TARGET_TYPES.contains(parameter.getType().toString())
&& parameter.getModifiers().getAnnotations().stream()
.anyMatch(a -> Positive.class.getSimpleName()
.equals(a.getAnnotationType().toString()));
}
次に、SampleJavacPluginクラスのfinished()メソッドを続行し、条件を満たすすべてのパラメーターにチェックを適用します。
public void finished(TaskEvent e) {
if (e.getKind() != TaskEvent.Kind.PARSE) {
return;
}
e.getCompilationUnit().accept(new TreeScanner() {
@Override
public Void visitMethod(MethodTree method, Void v) {
List parametersToInstrument
= method.getParameters().stream()
.filter(SampleJavacPlugin.this::shouldInstrument)
.collect(Collectors.toList());
if (!parametersToInstrument.isEmpty()) {
Collections.reverse(parametersToInstrument);
parametersToInstrument.forEach(p -> addCheck(method, p, context));
}
return super.visitMethod(method, v);
}
}, null);
この例では、複数の引数が@Positive.でマークされている可能性があるため、パラメータリストを逆にしました。すべてのチェックが最初のメソッド命令として追加されるため、正しい順序を確保するためにRTLを処理します。
すべてのチェックは最初のメソッド命令として追加されるため、RTLを処理して正しい順序を確保します。
5.2. インストルメントする方法
問題は、「ASTの読み取り」がpublic API領域にあるのに対し、「nullチェックの追加」などの「ASTの変更」操作はprivateAPIであるということです。
これに対処するには、we’ll create new AST elements through a TreeMaker instance.
まず、Contextインスタンスを取得する必要があります。
@Override
public void init(JavacTask task, String... args) {
Context context = ((BasicJavacTask) task).getContext();
// ...
}
次に、TreeMarker.instance(Context)メソッドを使用してTreeMarkerオブジェクトを取得できます。
これで、新しいAST要素を作成できます。たとえば、TreeMaker.If()の呼び出しによってif式を作成できます。
private static JCTree.JCIf createCheck(VariableTree parameter, Context context) {
TreeMaker factory = TreeMaker.instance(context);
Names symbolsTable = Names.instance(context);
return factory.at(((JCTree) parameter).pos)
.If(factory.Parens(createIfCondition(factory, symbolsTable, parameter)),
createIfBlock(factory, symbolsTable, parameter),
null);
}
チェックから例外がスローされたときに、正しいスタックトレース行を表示することに注意してください。 そのため、factory.at(((JCTree) parameter).pos)を使用して新しい要素を作成する前に、ASTファクトリの位置を調整します。
createIfCondition()メソッドは、「parameterId <0」if条件を作成します。
private static JCTree.JCBinary createIfCondition(TreeMaker factory,
Names symbolsTable, VariableTree parameter) {
Name parameterId = symbolsTable.fromString(parameter.getName().toString());
return factory.Binary(JCTree.Tag.LE,
factory.Ident(parameterId),
factory.Literal(TypeTag.INT, 0));
}
次に、createIfBlock()メソッドは、IllegalArgumentException:を返すブロックを作成します
private static JCTree.JCBlock createIfBlock(TreeMaker factory,
Names symbolsTable, VariableTree parameter) {
String parameterName = parameter.getName().toString();
Name parameterId = symbolsTable.fromString(parameterName);
String errorMessagePrefix = String.format(
"Argument '%s' of type %s is marked by @%s but got '",
parameterName, parameter.getType(), Positive.class.getSimpleName());
String errorMessageSuffix = "' for it";
return factory.Block(0, com.sun.tools.javac.util.List.of(
factory.Throw(
factory.NewClass(null, nil(),
factory.Ident(symbolsTable.fromString(
IllegalArgumentException.class.getSimpleName())),
com.sun.tools.javac.util.List.of(factory.Binary(JCTree.Tag.PLUS,
factory.Binary(JCTree.Tag.PLUS,
factory.Literal(TypeTag.CLASS, errorMessagePrefix),
factory.Ident(parameterId)),
factory.Literal(TypeTag.CLASS, errorMessageSuffix))), null))));
}
新しいAST要素を作成できるようになったので、パーサーによって準備されたASTにそれらを挿入する必要があります。 これは、public API要素をprivateAPIタイプにキャストすることで実現できます。
private void addCheck(MethodTree method, VariableTree parameter, Context context) {
JCTree.JCIf check = createCheck(parameter, context);
JCTree.JCBlock body = (JCTree.JCBlock) method.getBody();
body.stats = body.stats.prepend(check);
}
6. プラグインのテスト
プラグインをテストできる必要があります。 それは以下を含みます:
-
テストソースをコンパイルする
-
コンパイルされたバイナリを実行し、それらが期待どおりに動作することを確認します
このために、いくつかの補助クラスを導入する必要があります。
SimpleSourceFileは、指定されたソースファイルのテキストをJavacに公開します。
public class SimpleSourceFile extends SimpleJavaFileObject {
private String content;
public SimpleSourceFile(String qualifiedClassName, String testSource) {
super(URI.create(String.format(
"file://%s%s", qualifiedClassName.replaceAll("\\.", "/"),
Kind.SOURCE.extension)), Kind.SOURCE);
content = testSource;
}
@Override
public CharSequence getCharContent(boolean ignoreEncodingErrors) {
return content;
}
}
SimpleClassFileは、コンパイル結果をバイト配列として保持します。
public class SimpleClassFile extends SimpleJavaFileObject {
private ByteArrayOutputStream out;
public SimpleClassFile(URI uri) {
super(uri, Kind.CLASS);
}
@Override
public OutputStream openOutputStream() throws IOException {
return out = new ByteArrayOutputStream();
}
public byte[] getCompiledBinaries() {
return out.toByteArray();
}
// getters
}
SimpleFileManagerは、コンパイラがバイトコードホルダーを使用することを保証します。
public class SimpleFileManager
extends ForwardingJavaFileManager {
private List compiled = new ArrayList<>();
// standard constructors/getters
@Override
public JavaFileObject getJavaFileForOutput(Location location,
String className, JavaFileObject.Kind kind, FileObject sibling) {
SimpleClassFile result = new SimpleClassFile(
URI.create("string://" + className));
compiled.add(result);
return result;
}
public List getCompiled() {
return compiled;
}
}
最後に、これらはすべてメモリ内コンパイルにバインドされています。
public class TestCompiler {
public byte[] compile(String qualifiedClassName, String testSource) {
StringWriter output = new StringWriter();
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
SimpleFileManager fileManager = new SimpleFileManager(
compiler.getStandardFileManager(null, null, null));
List compilationUnits
= singletonList(new SimpleSourceFile(qualifiedClassName, testSource));
List arguments = new ArrayList<>();
arguments.addAll(asList("-classpath", System.getProperty("java.class.path"),
"-Xplugin:" + SampleJavacPlugin.NAME));
JavaCompiler.CompilationTask task
= compiler.getTask(output, fileManager, null, arguments, null,
compilationUnits);
task.call();
return fileManager.getCompiled().iterator().next().getCompiledBinaries();
}
}
その後、バイナリを実行するだけです。
public class TestRunner {
public Object run(byte[] byteCode, String qualifiedClassName, String methodName,
Class>[] argumentTypes, Object... args) throws Throwable {
ClassLoader classLoader = new ClassLoader() {
@Override
protected Class> findClass(String name) throws ClassNotFoundException {
return defineClass(name, byteCode, 0, byteCode.length);
}
};
Class> clazz;
try {
clazz = classLoader.loadClass(qualifiedClassName);
} catch (ClassNotFoundException e) {
throw new RuntimeException("Can't load compiled test class", e);
}
Method method;
try {
method = clazz.getMethod(methodName, argumentTypes);
} catch (NoSuchMethodException e) {
throw new RuntimeException(
"Can't find the 'main()' method in the compiled test class", e);
}
try {
return method.invoke(null, args);
} catch (InvocationTargetException e) {
throw e.getCause();
}
}
}
テストは次のようになります。
public class SampleJavacPluginTest {
private static final String CLASS_TEMPLATE
= "package com.example.javac;\n\n" +
"public class Test {\n" +
" public static %1$s service(@Positive %1$s i) {\n" +
" return i;\n" +
" }\n" +
"}\n" +
"";
private TestCompiler compiler = new TestCompiler();
private TestRunner runner = new TestRunner();
@Test(expected = IllegalArgumentException.class)
public void givenInt_whenNegative_thenThrowsException() throws Throwable {
compileAndRun(double.class,-1);
}
private Object compileAndRun(Class> argumentType, Object argument)
throws Throwable {
String qualifiedClassName = "com.example.javac.Test";
byte[] byteCode = compiler.compile(qualifiedClassName,
String.format(CLASS_TEMPLATE, argumentType.getName()));
return runner.run(byteCode, qualifiedClassName,
"service", new Class[] {argumentType}, argument);
}
}
ここでは、@Positive.で注釈が付けられたパラメーターを持つservice()メソッドを使用してTestクラスをコンパイルしています。次に、次のdouble値を設定してTestクラスを実行しています。メソッドパラメータの場合は-1。
プラグインを使用してコンパイラーを実行した結果、テストは負のパラメーターに対してIllegalArgumentExceptionをスローします。
7. 結論
この記事では、Javaコンパイラプラグインを作成、テスト、実行する完全なプロセスを示しました。
例の完全なソースコードはover on GitHubにあります。