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心采取不同的处理，具有”让编译器进行编译检查的功能”

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

• 标记，告诉编译器一些信息(RetentionPolicy.SOURCE)
• 运行时动态处理，如通过反射的信息获取注解信息进行操作(RetentionPolicy.RUNTIME)
• 编译时动态处理，如生成代码或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 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 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 annotations, RoundEnvironment roundEnv) {
        System.out.println("Hello Wolrd,Custom Processor");
        return false;
    }
    //这里你必须指定，该注解器是注册给哪个注解的
    @Override
    public Set getSupportedAnnotationTypes() {
        return super.getSupportedAnnotationTypes();
    }
    //用来指定你使用的java版本。通常这里会直接放回SourceVersion.latestSupported()
    @Override
    public SourceVersion getSupportedSourceVersion() {
        return SourceVersion.latestSupported();
    }

}

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

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

非常感谢分析。
参考链接：http://blog.csdn.net/charon_chui/article/details/51896830
实践例子
Hannes Dorfmann