Modify Java 8 final behaviour with Annotations【翻译】

文章来源于博客《Modify Java 8 final behaviour with Annotations》，作者Johan Kragt，我觉得写的很好，所以尝试翻译。
本文主旨是使用Java的Annotation来动态修改AST。

---

为什么我要写这个项目（How I started this project）

不久前我去参加了一场由JDriven的Ties van de Ven 举办的名为“致命的Null（Death To Null）”的会议。会议内容并没过多涉及到null检查和NullPointerExceptions异常，但是更关注于不变性（Immutability ）以及如何让你的软件避免bug和NullPointerExceptions异常。有一句话让我深思（大致意思是）：“Java选了错误的默认方式。Java中所有的东西应该被默认为final，除非开发者显式地注明它是可变的（mutable），而不是在只有当我们需要 不可变变量（immutable variable）的才显式标注为final”。

在对注解（Annotation）了解不多的时候，我以为利用注解就可以很轻松实现它。但是我遇到的第一个困难就是注解不能修改程序源代码，或者从源代码编译出的字节码文件；它们只能产生新的源文件或者验证代码。这使我迅速注意到了名为Lombok的库，该库却实现了这个功能。如果你使用过Lombok来生成getter和setter方法（这些方法并没有在你的源文件中写出），你可能会奇怪你的IDE是从哪里找到这些getter和setter方法的。

我们都知道Java的编译是一个递归过程。首先编译器会将你的源代码解析为一个AST，即抽象语法树。然后注解处理器（annotation processors）将会开始运行，它会基于你的注解来生成额外的代码文件或者做一些额外的验证。编译错误，比如不合法的类或者不合法的方法调用，会在编译的第三阶段进行。然而，如果一个注解处理器生成了新的源文件，那么编译器将会在进行第三步之前重复执行第一步和第二步。

Lombok库，以及我的验证性测试（proof of concept），将会用到一点hack技巧。在这里，并不需要利用注解处理器来生成新的文件，而是直接修改AST。这将可以让处理器在不接触源代码或者字节码的情况下改变代码。

一个更详细的解释在这里。虽然它有点过时，但还是能给你点帮助。

构建一个验证性测试（Building a PoC）

该验证性测试将会创建一个新的maven项目。它有两个子项目，其中一个包含自定义的注解以及注解处理器，另一个则包含一个测试类，它使用了这些注解。

我将创建两个注解，@FinalizeVars是一个类型注解，它告诉处理器，将被该注解标明的类中的所有变量都变为final。@MutableVar则是一个字段和局部变量的注解，表示处理器在处理final时跳过这些量。

虽然可以给@MutableVar添加一些额外功能，比如注解了@MutableVar的变量将会被移除final限定，但是对于像@MutableVar final String t = “test”这样的语句这么做显然没有什么意义。

代码实现（The code）

注解（The annotations）

这些注解是非常简单且标准的。

package nl.johannisk.finalizer.annotation;
 
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.TYPE})
public @interface FinalizeVars {
}

FinalizeVars是类型注解（Types）。

下面这个注解对于实现此功能（即将类中的字段都变为final）来说并不是完全必要的，但是我希望在程序员明确指出要将某些变量保留为可变时，注解处理器也能够处理（原句：“This Annotation is not entirely necessary for the functionality to work, but I didn’t want the annotation processor to change the functionality of the Java Compiler without the programmer explicitly telling it to do something strange.”）：

package nl.johannisk.finalizer.annotation;
 
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
 
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.LOCAL_VARIABLE, ElementType.FIELD})
public @interface MutableVar {
}

MutableVar是一个局部变量和字段的注解。如果局部变量和字段具有该注解，则注解处理器将会跳过这些字段。

注解处理器（The Processor）

在定义注解的那个项目里，按照如下路径建立一个文本文件：resources/META-INF/services/javax.annotation.processing.Processor就可以让编译器使用注解处理器工作。（译注：如果是在命令行中使用javac命令，则可以使用-processor参数后跟处理器的字节码文件来指定处理器，如果没有该参数命令，则有可能javac的版本过低。）

这个文本文件里必须写明带有完整限定的处理器类名，如nl.johannisk.finalizer.processor.FinalizerProcessor

实际的处理器具有两个类。一个是处理器本身，还有一个是“访问者”（或者称为”转换器”），用来遍历和转换AST中的每一个根元素。

处理器定义如下：

package nl.johannisk.finalizer.processor;
 
import com.sun.source.util.Trees;
import com.sun.tools.javac.processing.JavacProcessingEnvironment;
import com.sun.tools.javac.tree.JCTree;
import com.sun.tools.javac.tree.TreeMaker;
 
import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.SupportedAnnotationTypes;
import javax.annotation.processing.SupportedSourceVersion;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import java.util.Set;
 
@SupportedSourceVersion(SourceVersion.RELEASE_8)
@SupportedAnnotationTypes({"nl.johannisk.finalizer.annotation.FinalizeVars",
        "nl.johannisk.finalizer.annotation.MutableVar"})
public class FinalizerProcessor extends AbstractProcessor {
    private Trees trees;
    private TreeMaker treeMaker;
 
    @Override
    public void init(final ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
        final JavacProcessingEnvironment javacProcessingEnvironment =
                (JavacProcessingEnvironment) processingEnvironment;
        this.trees = Trees.instance(processingEnvironment);
        this.treeMaker =
                TreeMaker.instance(javacProcessingEnvironment.getContext());
    }
    @Override
    public boolean process(final Set annotations,
                           final RoundEnvironment roundEnvironment) {
        if (!roundEnvironment.processingOver()) {
            processRootElements(roundEnvironment.getRootElements());
        }
        return false;
    }
 
    private void processRootElements(final Set rootElements) {
        rootElements.forEach(this::processRootElement);
    }
 
    private void processRootElement(final Element element) {
        JCTree tree = (JCTree) trees.getTree(element);
        tree.accept(new FinalizerTranslator(treeMaker));
    }
}

处理器需要继承AbstractProcessor类，并且起码要重写process方法。

因为还需要用到AST树，所以我还重写了init方法。该方法先调用父类的init方法，然后将treeMaker初始化为访问器。同时还将AST树保存在tree字段中，以便process使用。（译注：com.sun.tools.javac.processingJavacProcessingEnvironment、com.sun.tools.javac.treeTreeMaker是在%JAVA_HOME%/lib/tools.jar中定义的，请导入该包。com.sun.source.util.Trees则在标准库中定义。Trees用于解析Java AST树，而TreeMaker: 用于生成Java AST节点。）

process方法首先检查是否已经处理完毕，如果没有（即第一次运行）则获得所有根元素并且用访问者（visitor）访问。访问者会判断当前访问的根元素是否需要被处理，然后一个新的访问者(FinalizerTranslator) 将会被创建。

package nl.johannisk.finalizer.processor;
 
import com.sun.tools.javac.code.Flags;
import com.sun.tools.javac.tree.TreeMaker;
import com.sun.tools.javac.tree.TreeTranslator;
import com.sun.tools.javac.tree.JCTree;
 
public class FinalizerTranslator extends TreeTranslator {
 
    private final TreeMaker treeMaker;
    private boolean shouldVisitVarDefinitions = false;
 
    public FinalizerTranslator(final TreeMaker treeMaker) {
        this.treeMaker = treeMaker;
    }
 
    @Override
    public void visitClassDef(final JCTree.JCClassDecl classDeclaration) {
        if (isFinalizeVarsAnnotation(classDeclaration.getModifiers())) {
            shouldVisitVarDefinitions = true;
        }
        super.visitClassDef(classDeclaration);
    }
 
    @Override
    public void visitVarDef(final JCTree.JCVariableDecl variableDeclaration) {
        super.visitVarDef(variableDeclaration);
        JCTree.JCModifiers modifiers = variableDeclaration.getModifiers();
        if (shouldBeMadeFinal(variableDeclaration, modifiers)) {
            variableDeclaration.mods = treeMaker.Modifiers(variableDeclaration.mods.flags | Flags.FINAL);
        }
        this.result = variableDeclaration;
    }
 
    private boolean shouldBeMadeFinal(final JCTree.JCVariableDecl variableDeclaration, final JCTree.JCModifiers modifiers) {
        return  !isMutableVarAnnotation(modifiers) &&
                !isVolatile(variableDeclaration.getModifiers()) &&
                shouldVisitVarDefinitions;
    }
 
    private boolean isMutableVarAnnotation(final JCTree.JCModifiers modifiers) {
        return modifiers.toString().contains("@MutableVar()");
    }
 
    private boolean isFinalizeVarsAnnotation(final JCTree.JCModifiers modifiers) {
        return modifiers.toString().contains("@FinalizeVars()");
    }
 
    private boolean isVolatile(final JCTree.JCModifiers modifiers) {
        return (modifiers.flags & Flags.VOLATILE) > 0;
    }
}

FinalizerTranslator即为访问者。因为注解将会被用于类和变量声明，所以对于这些元素的visit方法将被重写。

首先，visitClassDef将会访问类的定义内容，因为这些注解被用于类。如果一个类被FinalizeVars注解，那么visitVarDefinition将会被设为true。否则，（如果一个类没有注解FinalizeVars）该类中的变量声明将不会被后续处理。

接下来，visitVarDef会访问所有变量定义。注意这将会访问到类中所有的变量定义，而不仅仅是被注解的那些。

如果（变量）被注解（@MutableVar）、且没有被volatile修饰（因为它与final不兼容），同时（这些变量所在的）类被@FinalizeVars注解，那么treeMaker将基于原来（变量的）修饰符创建一个新的修饰符，将final修饰符加入。

调试（Debugging）

原文及翻译略：-)

---

外部参考

• The Hacker's Guide to Javac
• Javac Hack 指南（中译）
• 【Java进阶】利用APT优雅的实现统一日志格式
• Class AbstractProcessor
• Class Trees
• Class TreePath
• Java Code Examples for com.sun.tools.javac.tree.JCTree