annotationProcessor实战,了解ButterKinfe过程

注解的简介

简介

Annotations, a form of metadata, provide data about a program that is not part of the program itself. Annotations have no direct effect on the operation of the code they annotate.

注释是元数据的一种形式,为程序的元素(类、方法、变量)提供一些说明,但是不会对程序本身造成影响。

  • Annotation 类似一种修饰符,用于修饰包、类型、构造方法、方法、成语变量、参数的声明语句。
  • Annotation 是一个接口。通过反射来访问annotation信息。根据获取的信息来决定如何使用注解信息来做一些事情。
  • Annotation 不会对程序造成影响。
  • Java预言解析器在工作的时候默认是忽略这些annotation,所以在JVM中"不起作用",只有通过配套的工具才能对这些注解进行访问和处理。

Annotation的使用

  • Annotation的声明需要通过@interface这个关键字。会继承Annotation接口。
  • Annotation的方法必须声明为无参数、无异常。方法名代表成员变量名,方法的返回值代表了成员变量的类型。而且返回值类型必须为基本数据类型、Class类型、枚举类型、String类型、Annotation类型或者由前面任意一种类型组成的一维数组。方法后面可以使用default和一个默认数值来声明一个成员变量的默认值,null不能作为成员变量的默认值。
  • 注解中如果只有一个默认属性,可以直接使用value()函数,一个属性也没有的则表示该Annotation为Mark Annotation。
    例如:
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Test {
    String value();
}

直接使用@Test("demo"),等同于@Test(value="demo")
添加默认值:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestDefault {
    public String description() default "demo";
}

Annotation的作用

很多使用作为一种辅助途径,应用在软件框架或工具中。这些工具类可以根据不同的Annotation心采取不同的处理,具有"让编译器进行编译检查的功能"

具体可分为以下三种作用:

  1. 标记,告诉编译器一些信息(RetentionPolicy.SOURCE)
  2. 运行时动态处理,如通过反射的信息获取注解信息进行操作(RetentionPolicy.RUNTIME)
  3. 编译时动态处理,如生成代码或XML(RetentionPolicy.CLASS)

分类

标准的Annotation
从1.5开始就自带三张标准的Annotation类型:

  • Override
    它是一种marker类型的Annotation,用来标注方法,说明被它标注的方法是重载了父类中的方法。如果我们使用了该注解到一个没有覆盖父类方法的方法时,编译器就会提示一个编译错误的警告。
  • Deprecated
    它也是一种marker类型的Annotation。当方法或者变量使用该注解时,编译器就会提示该方法已经废弃。
  • SuppressWarnings
    它不是marker类型的Annotation。用户告诉编译器不要再对该类、方法或者成员变量进行警告提示。
    元Annotation
    元Annotation是指用来定义Annotation的Annotation
  • @Retention
    保留时间,可为RetentionPolicy.SOURCE(源码时)、RetentionPolicy.CLASS(编译时)、RetentionPolicy.RUNTIME(运行时),默认为CLASS。如果值为RetentionPolicy.SOURCE那大多都是Mark Annotation,例如:Override、Deprecated。SOURCE表示仅存在于源码中,在class文件中不会包含。CLASS表示会在class文件中存在,但是运行时无法获取。RUNTIME表示会在class文件中存在,并且在运行时可以通过反射获取。
  • @Target
    用来标记可进行修饰哪些元素,例如ElementType.TYPE、ElementType.METHOD、ElementType.CONSTRUCTOR、ElementType.FIELD、ElementType.PARAMETER等,如果未指定则默认为可修饰所有。
  • @Inherited
    子类是否可以继承父类中的该注解。它所标注的Annotation将具有继承性。
  • @Documented
    是否会保存到javadoc文档中。

自定义Annotation

在Android的获取控件中都需要findViewById()来获取,通过注解的来获取到Id的值进行绑定例如:

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ViewInject{
    int viewId();
}

注解声明完后,可以定义一些控件来使用:

@ViewInject(viewId = R.id.test)
    private TextView test;

Annotation解析

  • 当Java源代码被编译时,编译器的一个插件annotation处理器则会处理这些annotation。
    处理器可以产生报告信息,或者创建附加的Java源文件或资源。
    如果annotation本身被加上了RententionPolicy的运行时类,
    则Java编译器则会将annotation的元数据存储到class文件中。然后Java虚拟机或其他的程序可以查找这些元数据并做相应的处理。
  • 除了annotation处理器可以处理annotation外,我们也可以使用反射来处理annotation。Java SE 5有一个名为AnnotatedElement的接口,
    Java的反射对象类Class,Constructor,Field,Method以及Package都实现了这个接口。
    这个接口用来表示当前运行在Java虚拟机中的被加上了annotation的程序元素。
    通过这个接口可以使用反射读取annotation。AnnotatedElement接口可以访问被加上RUNTIME标记的annotation,
    相应的方法有getAnnotation,getAnnotations,isAnnotationPresent。
    由于Annotation类型被编译和存储在二进制文件中就像class一样,
    所以可以像查询普通的Java对象一样查询这些方法返回的Annotation。

运行时Annotation解析

该类是指@Retention为RUNTIME的Annotation。
该类型的解析其实本质的使用反射。反射执行的效率是很低的
如果不是必要,应当尽量减少反射的使用,因为它会大大拖累你应用的执行效率。
例如:

public static void viewInject(Activity activity){
        Class<? extends Activity> obj=activity.getClass();
        Field[] fields=obj.getDeclaredFields();//获取声明的字段
        for (Field field :fields){
            ViewInject viewInject=field.getAnnotation(ViewInject.class);
            if(viewInject!=null){
                int viewId=viewInject.viewId();
                if(viewId!=-1){
                    try {
                        Method method=obj.getMethod("findViewById",int.class);
                        Object view=method.invoke(activity,viewId);
                        field.setAccessible(true);//设置属性可以访问
                        field.set(activity,view);
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            }
        }
    }

在Android的开发中使用ButterKnife他也是使用到了注解

//声明的保留时期为编译时期
@Retention(CLASS) @Target(FIELD)
public @interface BindView {
  /** View ID to which the field will be bound. */
  @IdRes int value();
}

使用的是编译类型的注解,这样就不会通过反射来获取数值,不会影响性能。

编译类型注解的过程:

编译类型注解的解析

  • 该类型注解值是@Retention为CLASS的Annotation,由APT(Annotaion Processing Tool)自动进行解析。是在编译时注入,所以不会像反射一样影响效率问题。
  • 根据sun官方的解释,APT(annotation processing tool)是一个命令行工具,
    它对源代码文件进行检测找出其中的annotation后,使用annotation processors来处理annotation。
    而annotation processors使用了一套反射API并具备对JSR175规范的支持。
  • annotation processors处理annotation的基本过程如下:
  1. APT运行annotation processors根据提供的源文件中的annotation生成源代码文件和其它的文件(文件具体内容由annotation processors的编写者决定)
  2. 接着APT将生成的源代码文件和提供的源文件进行编译生成类文件。
  • APT在编译时自动查找所有继承自AbstractProcessor的类,然后调用他们的process方法去处理,这样就拥有了在编译过程中执行代码的能力
  • 所以我们需要完成的工作:
  1. 自定义类继承AbstractProcessor,重写process方法。
  2. 注册处理器,让APT能够检测的到。
  • 但是在Android Studio死活提示找不到AbstractProcessor类,这是因为注解是javase中javax包里面的,android.jar默认是不包含的,所以会编译报错.
    解决方法就是新建一个Module,在选择类型时将该Module的类型选为Java Library。
    然后在该Module中创建就好了Processor就好了,完美解决
  • Android Studio中创建一个Android工程。
  • 新建一个Module,然后选择Java Library类型,并且让app依赖该module
  • 在annotations的module中创建注解类
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)
public @interface AnnotationTest {
    String value() default "";
}

  • 创建自定义的Processor类
@SupportedAnnotationTypes("com.example.AnnotationTest")
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class TestProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        System.out.println("process");
        for (TypeElement te : annotations) {
            for (Element element : roundEnv.getElementsAnnotatedWith(te)) {
                AnnotationTest annotation = element.getAnnotation(AnnotationTest.class);
                String value = annotation.value();
                System.out.println("type : " + value);
            }
        }
        return true;
    }
}

注意:@SupportedAnnotationTypes("com.charon.AnnotationTest")来指定要处理的注解类。
@SupportedSourceVersion(SourceVersion.RELEASE_7)指定编译的版本。这种通过注解指定编译版本和类型的方式是从Java 1.7才有的。
对于之前的版本都是通过重写AbstractProcessor中的方法来指定的。

  • 注册处理器
    我们自定义了Processor那如何才能让其生效呢?就是在annotations的java同级目录新建resources/META-INF/services/javax.annotation.processing.Processor文件
    然后在javax.annotation.processing.Processor文件中指定自定义的处理器,如:
    com.example.TestProcessor
  • 在app中进行使用
    进行Build会在控制台看到输出的信息。

上面只是一个简单的例子,如果你想用编译时注解去做一些更高级的事情,例如自动生成一些代码,那你可能就会用到如下几个类库:

  • 以前使用android-apt,Gradle plugin 2.2提供annotationProcessor来代替了android-apt,还是建议使用官方的

As of the Android Gradle plugin version 2.2, all functionality that was previously provided by android-apt is now available in the Android plugin. This means that android-apt is officially obsolete
Here are the steps to migrate:
Make sure you are on the Android Gradle 2.2 plugin or newer.
Remove the android-apt plugin from your build scripts
Change all apt, androidTestApt and testApt dependencies to their new format:

dependencies {
    compile 'com.google.dagger:dagger:2.0'
    annotationProcessor 'com.google.dagger:dagger-compiler:2.0'
}
  • Google Auto的作用:
    Google Auto的主要作用是注解Processor类,并对其生成META-INF的配置信息,
    可以让你不用去写META-INF这些配置文件,只要在自定义的Processor上面加上@AutoService(Processor.class)
  • Square javapoet的作用:
    javapoet:A Java API for generating .java source files.可以更方便的生成代码,它可以帮助我们通过类调用的形式来生成代码。

自定义编译时注解

在自定义注解时,一般来说可能会建三个modules:

  • app module:写一些使用注解的android应用逻辑。
  • api module:定义一些可以在app中使用的注解。它会被app以及compiler使用。
  • compiler module:定义Processor该module不会被包含到应用中,它只会在构建过程中被使用。在编译的过程中它会生成一些java文件,而这些java文件会被打包进apk中。
    我们可以在该module中使用auto以及javapoet。
    开始进行配置:
  • compiler module中配置auto以及javapoet
dependencies {
    compile fileTree(include: ['*.jar'], dir: 'libs')
    //Google Auto的主要作用是注解Processor类,并对其生成META-INF的配置信息,
    //可以让你不用去写META-INF这些配置文件,只要在自定义的Processor上面加上@AutoService(Processor.class)
    compile 'com.google.auto.service:auto-service:1.0-rc2'
    //可以更方便的生成代码,它可以帮助我们通过类调用的形式来生成代码。
    compile 'com.squareup:javapoet:1.7.0'
    compile project(':apimodule')
}
  • app module中gradle配置:
compile project(':compilermodule')
annotationProcessor project(':compilermodule')
  • 在api module 中创建一个注解
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface Factory {
    String id();
    Class type();
}
  • 在compiler module中自定义一个Processor
@AutoService(Processor.class)
public class MyProcessor extends AbstractProcessor {
    //初始化操作的方法,RoundEnvironment会提供很多有用的工具类Elements、Types和Filer等。
    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
    }
    //这相当于每个处理器的主函数main()。在该方法中去扫描、评估、处理以及生成Java文件。
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        System.out.println("Hello Wolrd,Custom Processor");
        return false;
    }
    //这里你必须指定,该注解器是注册给哪个注解的
    @Override
    public Set<String> getSupportedAnnotationTypes() {
        return super.getSupportedAnnotationTypes();
    }
    //用来指定你使用的java版本。通常这里会直接放回SourceVersion.latestSupported()
    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

}

从jdk 1.7开始,可以使用如下注解来代替getSupporedAnnotationTypes()和getSupportedSourceVersion()方法:

@SupportedSourceVersion(SourceVersion.latestSupported())
@SupportedAnnotationTypes({
   // 合法注解全名的集合
 })

推荐阅读更多精彩内容