Javaコンパイラプラグインの作成

1概要

Java 8は、 Javac プラグインを作成するためのAPIを提供します。残念ながら、それに関する適切な文書を見つけるのは困難です。

この記事では、 ** 。class ファイルにカスタムコードを追加するコンパイラ拡張機能を作成するプロセス全体について説明します。

2セットアップ

まず、プロジェクトの依存関係としてJDKの tools.jar を追加する必要があります。

<dependency>
    <groupId>com.sun</groupId>
    <artifactId>tools</artifactId>
    <version>1.8.0</version>
    <scope>system</scope>
    <systemPath>${java.home}/../lib/tools.jar</systemPath>
</dependency>
  • すべてのコンパイラ拡張機能は com.sun.source.util.Plugin インタフェースを実装するクラスです。

この例で作成しましょう。

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());
    }
}

現時点では、コードが正しく取得され、コンパイルに含まれるように、「こんにちは」と表示しています。

  • 最終目標は、与えられた注釈でマークされたすべての数値引数に対して実行時チェックを追加するプラグインを作成し、その引数が条件と一致しない場合は例外をスローすることです。**

__Javacがこのエクステンションを発見できるようにするにはもう1つ必要なステップがあります。

これを実現するには、プラグインの完全修飾クラス名( com.baeldung.javac.SampleJavacPlugin )であるcontentを持つ com.sun.source.util.Plugin という名前のファイルを作成し、それを META-INF/services ディレクトリに配置する必要があります。 。

その後、 -Xplugin:MyPlugin スイッチを使用して Javac を呼び出すことができます。

baeldung/tutorials$ javac -cp ./core-java/target/classes -Xplugin:MyPlugin ./core-java/src/main/java/com/baeldung/javac/TestClass.java
Hello from MyPlugin
  • プラグインの getName()メソッドから返された String -Xplugin__オプションの値として** 常に使用しなければならないことに注意してください。

3プラグインライフサイクル

  • プラグインは、 init() メソッドを通して、コンパイラによって一度だけ呼び出されます。

後続のイベントの通知を受けるには、コールバックを登録する必要があります。

これらは、ソースファイルごとにすべての処理段階の前後に到着します。

  • PARSE - 抽象構文ツリー (AST)を構築します。

  • ENTER - ソースコードのインポートは解決されました

  • ANALYZE - パーサー出力(AST)のエラーが分析されます

  • GENERATE - ターゲットソースファイル用のバイナリを生成する

ANNOTATION PROCESSING ANNOTATION PROCESSING ROUND__の2種類のイベントがありますが、ここではそれらには関心がありません。

たとえば、ソースコード情報に基づいてチェックを追加してコンパイルを強化したい場合は、 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データの抽出

  • TaskEvent.getCompilationUnit() を介して、Javaコンパイラによって生成されたASTを取得することができます。** その詳細は、 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<Void, Void>() {
        @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'");
    }
}
  • これが意味するのは、 @ Positive でマークされたすべての引数に対して IllegalArgumentException がスローされることを意味します。

** 5.1. どこで計測するか

インスツルメンテーションを適用する必要がある場所を特定する方法を見つけましょう。

private static Set<String> 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<Void, Void>() {
        @Override
        public Void visitMethod(MethodTree method, Void v) {
            List<VariableTree> 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);

この例では、複数の引数が[email protected]でマークされている可能性があるため、パラメーターリストを逆にしています。

すべてのチェックが最初のメソッド命令として追加されるので、正しい順序を保証するためにそれらをRTLで処理します。

5.2. 計測方法

問題は、 "read AST"が public API領域にあるのに対し、 "add null-checks"のような "modify AST"操作は private API であることです。

これに対処するために、 TreeMaker インスタンスを介して新しいAST要素を作成します。

まず、 Context インスタンスを取得する必要があります。

@Override
public void init(JavacTask task, String... args) {
    Context context = ((BasicJavacTask) task).getContext();
   //...
}

それから、 TreeMarker.instance(Context) メソッドを通して TreeMarker オブジェクトを取得できます。

これで、新しいAST要素を作成できます。たとえば、 if 式は TreeMaker.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 A _PI 要素を private_ API型にキャストすることでこれを実現できます。

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<StandardJavaFileManager> {

    private List<SimpleClassFile> 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<SimpleClassFile> 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<SimpleSourceFile> compilationUnits
          = singletonList(new SimpleSourceFile(qualifiedClassName, testSource));
        List<String> 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.baeldung.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.baeldung.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 クラスをコンパイルしています。次に、methodパラメータにdoubleの値として-1を設定して Test__クラスを実行します。

このプラグインを使用してコンパイラを実行した結果、テストでは負のパラメータに対して IllegalArgumentException がスローされます。

7. 結論

この記事では、Java Compilerプラグインの作成、テスト、および実行の全プロセスについて説明しました。

例の完全なソースコードはhttps://github.com/eugenp/tutorials/tree/master/core-java-sun[over on GitHub]にあります。