25 - 注解处理器

注解（annotation）是 Java 5 引入的，用来为类、方法、字段、参数等 Java 结构提供额外信息的机制

• 举个例子

package java.lang;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

• @Override注解本身被另外两个元注解（即作用在注解上的注解）所标注
• @Target用来限定目标注解所能标注的 Java 结构，这里@Override便只能被用来标注方法
• @Retention则用来限定当前注解生命周期。注解共有三种不同的生命周期
  • SOURCE：只出现在源代码中
  • CLASS：只出现在源代码和字节码中
  • RUNTIME：出现在源代码、字节码和运行过程中

注解处理器

Java 的注解机制允许开发人员自定义注解。这些自定义注解同样可以为 Java 编译器添加编译规则。不过，这种功能需要由开发人员提供，并且以插件的形式接入 Java 编译器中，这些插件我们称之为注解处理器（annotation processor）

• 注解处理器的原理

  
  
  java编译器工作流程

1. 将源文件解析为抽象语法树
2. 调用已注册的注解处理器
3. 生成字节码

• 如果在第 2 步调用注解处理器过程中生成了新的源文件，那么编译器将重复第 1、2 步，解析并且处理新生成的源文件。每次重复我们称之为一轮（Round）
• 第一轮解析、处理的是输入至编译器中的已有源文件
• 如果注解处理器生成了新的源文件，则开始第二轮、第三轮，解析并且处理这些新生成的源文件
• 当注解处理器不再生成新的源文件，编译进入最后一轮，并最终进入生成字节码的第 3 步

自定义

package foo;

import java.lang.annotation.*;

@Target({ ElementType.TYPE, ElementType.FIELD })
@Retention(RetentionPolicy.SOURCE)
public @interface CheckGetter {
}

• 一个处理@CheckGetter注解的处理器。它将遍历被标注的类中的实例字段，并检查有没有相应的getter方法

public interface Processor {

  void init(ProcessingEnvironment processingEnv);
  
  Set getSupportedAnnotationTypes();
  
  SourceVersion getSupportedSourceVersion();
  
  boolean process(Set annotations, RoundEnvironment roundEnv);
  
  ...
}

• 所有的注解处理器类都需要实现接口Processor。该接口主要有四个重要方法。其中，init方法用来存放注解处理器的初始化代码。
• Java 编译器中，注解处理器的实例是通过反射 API 生成的。也正是因为使用反射 API，每个注解处理器类都需要定义一个无参数构造器
• getSupportedAnnotationTypes方法将返回注解处理器所支持的注解类型，这些注解类型只需用字符串形式表示
• getSupportedSourceVersion方法将返回该处理器所支持的 Java 版本，通常，这个版本需要与你的 Java 编译器版本保持一致；而process方法则是最为关键的注解处理方法
• 注解处理器实现

package bar;

import java.util.Set;

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.*;
import javax.lang.model.util.ElementFilter;
import javax.tools.Diagnostic.Kind;

import foo.CheckGetter;

@SupportedAnnotationTypes("foo.CheckGetter")
@SupportedSourceVersion(SourceVersion.RELEASE_10)
public class CheckGetterProcessor extends AbstractProcessor {

  @Override
  public boolean process(Set annotations, RoundEnvironment roundEnv) {
    // TODO: annotated ElementKind.FIELD
    for (TypeElement annotatedClass : ElementFilter.typesIn(roundEnv.getElementsAnnotatedWith(CheckGetter.class))) {
      for (VariableElement field : ElementFilter.fieldsIn(annotatedClass.getEnclosedElements())) {
        if (!containsGetter(annotatedClass, field.getSimpleName().toString())) {
          processingEnv.getMessager().printMessage(Kind.ERROR,
              String.format("getter not found for '%s.%s'.", annotatedClass.getSimpleName(), field.getSimpleName()));
        }
      }
    }
    return true;
  }

  private static boolean containsGetter(TypeElement typeElement, String name) {
    String getter = "get" + name.substring(0, 1).toUpperCase() + name.substring(1).toLowerCase();
    for (ExecutableElement executableElement : ElementFilter.methodsIn(typeElement.getEnclosedElements())) {
      if (!executableElement.getModifiers().contains(Modifier.STATIC)
          && executableElement.getSimpleName().toString().equals(getter)
          && executableElement.getParameters().isEmpty()) {
        return true;
      }
    }
    return false;
  }
}

• 在将该注解处理器编译成 class 文件后，我们便可以将其注册为 Java 编译器的插件，并用来处理其他源代码
  1. 第一种是直接使用 javac 命令的-processor参数

  $ javac -cp /CLASSPATH/TO/CheckGetterProcessor -processor 
  bar.CheckGetterProcessor Foo.java
  error: Class 'Foo' is annotated as @CheckGetter, but field 'a' is without getter
  1 error
  

  2. 第二种则是将注解处理器编译生成的 class 文件压缩入 jar 包中，并在 jar 包的配置文件中记录该注解处理器的包名及类名，即bar.CheckGetterProcessor

  （具体路径及配置文件名为`META- INF/services/javax.annotation.processing.Processor`）
  

  • 当启动 Java 编译器时，它会寻找 classpath 路径上的 jar 包是否包含上述配置文件，并自动注册其中记录的注解处理器

  $ javac -cp /PATH/TO/CheckGetterProcessor.jar Foo.java
  error: Class 'Foo' is annotated as @CheckGetter, but field 'a' is without getter
  1 error
  

  3. 还可以在 IDE 中配置注解处理器

利用注解处理器生成源代码

• 注解处理器可以用来修改已有源代码或者生成源代码
• 注解处理器并不能真正地修改已有源代码。这里指的是修改由 Java 源代码生成的抽象语法树，在其中修改已有树节点或者插入新的树节点，从而使生成的字节码发生变化。
• 可以参考[Project Lombok]，用注解处理器来生成源代码则比较常用