编译时注解处理器AnnotationProcessor的使用

前言

在前面写的EventBus的源码解析的文章中提到了编译时注解的概念,在编译期EventBusAnnotationProcessor会生成一个MyEventIndex的java类文件,并把带有@subscribe的方法信息保存在该方法中,并在注册的时候获取订阅方法信息,那么编译器注解是如何工作的?下面就给大家讲讲究竟这是个什么东西吧。

什么是注解?

从JDK5开始,Java增加了注解,注解是代理里特殊的标记,这些标记可以在编译、类加载、运行时被读取,并执行相应的处理。通过使用注解,开发人员可以在不改变原有逻辑的情况下,在源文件中嵌入一些补充信息。代码分析工具,开发工具和部署工具可以通过这些补充信息进行验证,处理或者进行部署。

注解的分类

(1)标注注解

  • @Overrride:对覆盖超类中的方法进行标记,如果被标记的方 法并没有实际覆盖超类中的方法,则编译器会发出警告。
  • @Deprecate:提示开发者该方法已经废弃,不推荐使用。
  • @SupperWarnings:选择性地取消特定代码中的警告。

(2)元注解
用来标注其它注解而创建的新注解,元注解的类型有以下几种:

  • @Target:注解所修饰的对象范围
  • @Inherited:表示注解可以被继承
  • @Documented:表示这个注解应该被JavaDoc工具记录
  • @Rentation:用来声明注解的保留策略
  • @Repeable:JDK8新增,允许一个注解在同一声明类型(类,属性或方法)上多次使用。

其中@Target注解的取值是一个ElementType类型的枚举,其中有一下几种取值,对应不同的对象范围。

  • ElementType.TYPE:能修饰类,接口或者枚举类型。
  • ElementType.FIELD:能修饰成员变量
  • ElementType. METHOD:能修饰方法
  • ElementType. PARAMETER:能修饰参数
  • ElementType. CONSTRUCTOR:能修饰构造方法
  • ElementType.LOCAL_VARIABLE:能修饰局部变量
  • ElementType. ANNOTATION_TYPE:能修饰注解
  • ElementType. PACKAGE:能修饰包
  • ElementType.TYPE_PARAMETER:能修饰参数声明
  • ElementType.TYPE_USE:使用类型

其中@Retention注解有3种类型,分别表示不同级别的保留策略。

  • RetentionPolicy.CLASS:源码级注解,注解信息只会保留在Java源码中,源码在编译后,注解信息将会被丢弃,不会保留在.class文件中。

  • RetentionPolicy.CLASS:编译时注解。注解信息会保留在.java源码以及.class中。当运行java程序时,JVM会丢弃该注解信息,不会保留在JVM中,许多注解类框架,如EventBus,ButterKnife他们都是使用编译时注解信息开发的,针对编译时注解我们采用AbstractProcessor来处理注解信息。

  • RetentionPolicy.RUNTIME:运行注解。当运行Java程序时,JVM也会保留该注解信息,可以通过反射获取该注解信息。

AnnotationProcessor的使用

(1)新建annotations库

  • 新建一个Java Lib库annotations,其gradle配置文件如下:
apply plugin: 'java'

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
}

sourceCompatibility = "1.7"
targetCompatibility = "1.7"

  • 定义一个注解BindView注解,其源码如下:
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.CLASS)
public @interface BindView {
    int value() default 0;
}

(2)新建processor 库

  • 新建一个processor java lib库,并引用上面定义的annotations库
apply plugin: 'java'

dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    compile project(path: ':annotations')
}

sourceCompatibility = "1.7"
targetCompatibility = "1.7"
  • 定义一个ButterKnifeProcessor类继承AbstractProcessor类
package com.mtime.processor;

import com.mtime.annotations.BindView;

import java.io.BufferedWriter;
import java.io.IOException;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.Set;

import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.Messager;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.RoundEnvironment;
import javax.annotation.processing.SupportedAnnotationTypes;

import javax.annotation.processing.SupportedSourceVersion;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.tools.Diagnostic;

@SupportedSourceVersion(SourceVersion.RELEASE_7)
@SupportedAnnotationTypes("com.mtime.annotations.BindView")

public class ButterKnifeProcessor extends AbstractProcessor {
    private Messager mMessage;

    @Override
    public synchronized void init(ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
        mMessage = processingEnvironment.getMessager();

    }


    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
        for(Element element : roundEnvironment.getElementsAnnotatedWith(BindView.class)){
            if(element.getKind() == ElementKind.FIELD){
                mMessage.printMessage(Diagnostic.Kind.NOTE,"printMessage : " + element.toString());

            }
        }
        return true;
    }


    @Override
    public Set<String> getSupportedAnnotationTypes() {
        return super.getSupportedAnnotationTypes();
    }


    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

}

ButterKnifeProcessor 注解处理器中所有方法介绍如下:

  • init():会自动被注解处理工具调用,并传入ProcessingEnviroment参数,通过该参数可以获取到很多有用的工具类:** Elements , Types , Filer **等等

  • process(Set<? extends TypeElement> annoations, RoundEnvironment roundEnv):Annotation Processor扫描出的结果会存储进roundEnv中,可以在这里获取到注解内容,编写你的操作逻辑。注意,process()函数中不能直接进行异常抛出,否则的话,运行Annotation Processor的进程会异常崩溃,然后弹出一大堆让人捉摸不清的堆栈调用日志显示.

  • getSupportedAnnotationTypes(): 该函数用于指定该自定义注解处理器(Annotation Processor)是注册给哪些注解的(Annotation),注解(Annotation)指定必须是完整的路径。

  • getSupportedSourceVersion():用于指定你的java版本,一般返回:SourceVersion.latestSupported()

  • 注解处理器的注册过程

为了能使用注解处理器,需要用一个服务器文件来注册它,现在我们就来创建这个服务器文件,首先在processor库的main目录下新建resources资源文件夹,接下来在resources文件夹下新建META-INF/services目录文件夹。最后在META-INF/ services中创建javax.annotation.processing.Processor文件,文件的内容是我们上面定义的com.mtime.processor.ButterKnifeProcessor类的完整路径。

processor的注册.png

(3) 主项目中调用

  • 我们在主项目中引用annotations和processor两个库,并在gradle配置文件中添加‘annotationProcessorOptions.includeCompileClasspath = true’的配置,如果不添加该配置,编译时将会报错。
 android {
    compileSdkVersion 26
  defaultConfig {
        applicationId "com.mtime.myprocessor"
  minSdkVersion 15
  targetSdkVersion 26
  versionCode 1
  versionName "1.0"
  testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
  javaCompileOptions{
            annotationProcessorOptions.includeCompileClasspath = true
  }
    }
  • 在Activity中模拟使用BindView注解,如下所示:
public class MainActivity extends Activity {
    @BindView(R.id.tv_text)
    TextView textView;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }
}

最后我们可以看看gradle打印出的日志信息下:

日志信息.png

也就是说我们获取到了包含@BindView注解的field textView,那么我们就可以通过反射的方式对其进行初始化,这也是butterKnife框架的开发原理。EventBus其原理也是一样的,在编译的时候就把注解信息给保存下来,这就省了我们在代码中寻找注解的开销,这也是注解类框架非常流行的原因,使用很小的开销,就可以方便我们不用地去写一些重复性的代码。
github地址:https://github.com/Fredlxy/AnnotationProcessorDemo.git

推荐阅读更多精彩内容