Annotation & Annotation process

前面是一些名词的解释和说明，例子创建可以直接看后面的“创建过程”的章节。

本文主要参考网上各个大神的总结和自己使用过程的问题完成的，如果你发现有你的文章的内容，请通知我，我将你的文章放在引用目录里，谢谢。
如有错误和需要勘正的地方，请指教。

Annotation

注解是JDK5.0引入的新特性
JDK5.0 当时提供了三个注解： @Deprecated（废弃的、过时的）、@Override（重写、覆盖）、@SuppressWarnings（压缩警告）

1. 注解相当于一种标记，在程序中加入注解就等于为程序打上某种标记。
2. javac编译器、开发工具和其他程序可以通过反射来了解类及各元素上的标记信息。
3. 注解可以加在包、类、属性、方法、方法的参数以及局部变量上。

元注解（meta-annotaion）

JDK5.0引入，负责注解其他注解

元注解包含：

1. @Target:规定自定义Annotation所修饰的对象范围
   • ElementType.CONSTRUCTOR，构造器声明
   • ElementType.FIELD，成员变量、对象、属性（包括enum实例）
   • ElementType.LOCAL_VARIABLE，局部变量声明
   • ElementType.METHOD，方法声明
   • ElementType.PACKAGE，包声明
   • ElementType.PARAMETER，参数声明
   • ElementType.TYPE，类、接口（包括注解类型）或enum声明
   • 同时支持多种范围设定，e.g.：
     @Target({ElementType.TYPE,ElementType.FIELD})
2. @Retention:对Annotation的“生命周期”限制，表示需要在什么级别保存该注释信息
   • RetentionPolicy.SOURCE，在源文件中有效
   • RetentionPolicy.CLASS，在class文件中有效
   • RetentionPolicy.RUNTIME，在运行时有效
3. @Documented:用于描述其他类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类工具文档化，Documented是一个标记注解，没有成员
4. @Inherited:标记注解，被标注的类型是被继承的，主要用于类。

自定义注解

使用@interface自定义注释时，自动继承了java.lang.annotation.Annotation接口，由编译程序自动完成其他细节。在定义注解时，不能继承其他的注解或接口。@interface用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称，返回值类型就是参数类型（只能是基本类型、Class、String、enum）。可以通过default来声明参数的默认值。

注解使用的参数

只能用基本类型byte,short,char,int,long,float,double,boolean八种基本数据类型和String,Enum,Class,Annotation等数据类型，以及这些类型的数组。
必须有明确的值，可以在定义注解的默认值中指定；或者 使用注解时指定，非基本类型的注解元素的值不可为null。

自定义注解的局限

1. 不能修改已有的源文件，可以创建新的源文件

APT(Used in Android Studio)

APT(Annotation Processing Tool)是一种处理注释的工具，它对源码文件进行检测找出其中的Annotation，使用Annotation进行额外的处理。
Annotation处理器在处理Annotation时可以根据源文件中的Annotation生成额外的源文件和其他的文件(文件具体内容由Annotation处理器的编写者决定)，APT还会编译生成的源文件和原来的源文件，将它们一起生成class文件。

创建过程

1. 创建一个Java Library(比如叫做annotation)，放置自定义的annotation和关联代码。

   @Target(ElementType.TYPE)
   @Retention(RetentionPolicy.CLASS)  
   public @interface Test {   }
   

2. 配置该library的build.gradle

   该配置信息在android studio将自动生成

   apply plugin: 'java' 
   sourceCompatibility = 1.7  
   targetCompatibility = 1.7   
   dependencies { 
       compile fileTree(dir: 'libs', include: ['*.jar']) 
   }  
   

3. 创建一个Java library(比如叫做compiler)，放置自定义的Annotation Processor。

   AutoService是一个开源库提供的注册Processor的方法。

   @AutoService(Processor.class)
   public class TestProcessor extends AbstractProcessor {
       @Override
       public Set<String> getSupportedAnnotationTypes() {
           return Collections.singleton(Test.class.getCanonicalName());
       }
       @Override
       public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
           return false;
       }
   }
   

4. 配置build.gradle

   apply plugin: 'java'
   sourceCompatibility = 1.7 
   targetCompatibility = 1.7 
   dependencies {
       compile fileTree(dir: 'libs', include: ['*.jar'])
       compile 'com.google.auto.service:auto-service:1.0-rc2'
       compile 'com.squareup:javapoet:1.7.0'
       compile project(':annotation')
   }
   

5. 配置Project的build.gradle

   加在buildscript的dependencies中

   classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
   

6. 配置app的build.gradle

   增加pluge

   apply plugin: 'com.neenbedankt.android-apt'
   

   dependencies中增加

   compile project(':annotation')
   apt project(':compiler')
   

7. 新版本android studio 5和6的配置会报错，只要直接使用annotationProcessor引入依赖就好，即源码如下：

   dependencies中增加

   compile project(':annotation')
   annotationProcessor project(':compiler')
   

Debug自定义Annotaion Processor

编译过程：

1. javac启动一个JVM运行processor；
2. compiler编译代码，所以processor生成的代码可以被编译进apk；
3. IDE启动JVM运行代码。

1. 将需要debug的processor加入compiler中

   • 在setting中打开Enable annotation processing（setting[需要在File->Other Settings->Default Setting 或者 Android studio欢迎页面中的Configure->Preferences]->Build,Execution,Deployment->Compiler->Annotation Processors）
   • Processor FQ Name中增加一个自定义Processor的全路径

2. 设置javac为debug模式

   • 在Annotation Processors的设置项上面的Java Compiler中

   • 设置Additional command line parameters中设置：

     -J-Xdebug -J-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005
     

3. 增加一个远程编译选项并启动编译

   • 打开项目的Run/Debug Configurations
   • 在左边栏中，点击“+”增加一个Remote，确定。

4. 设置项目gradle.properties增加：

   org.gradle.jvmargs=-Xmx1536m -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
   

5. 点击调试按钮，打开远程调试功能(这个时候自定义processor中的断点显示生效)

6. 重新编译工程，断点响应

注1：1、2步骤在实际中发现，不是必须要设置的，具体1、2步骤会有什么作用，还在研究。
注2：当遇到unable to open debugger port: connection refused的错误时，是因为：

1. 当前的端口号被占用，你需要找到一个你电脑未被占用的端口号进行调试
2. 工程引用的所有gradle.properties文件中，存在未加调试命令的文件

常用操作

1. 获取VariableElement的类型的TypeElement:Types.asElement(VariableElement.asType())：
   • 注意：如果类型是基本类型，则返回值是null，需要通过Types.boxedClass((PrimitiveType) VariableElement.asType());获取到装箱类的类型，基本类型只有PrimitiveType，他是一个TypeMirror。
2. TypeElement可以通过getEnclosingElement().toString()获取包名，getSimpleName().toString()获取类名
3. 数组的处理：asType()，返回ArrayType，getComponentType()返回是哪种类型的数组
4. List的处理：asType()，返回DeclaredType，getTypeArguments()获取是哪种类型的list。

相关类说明

AbstractProcessor

• init:ProcessingEnvironment，参数ProcessingEvnironment提供很多有用的工具类。
• process:Set<TypeElement> RoundEnvironment，RoundEvnironment可以用来查询出包含特定注解的被注解元素。
  1. 注意问题：
     • 可能你使用的源文件还未编译，会抛出异常MirroredTypeException
     • 可能存在process多次调用，因为处理之后有新的文件生成，所以需要注意内部数据的更新和清空问题。
• getSupportedAnnotationTypes，指定这个注解处理器是注册给哪个注解的。
• getSupportedSourceVersion，指定你使用的Java版本。

ProcessingEnvironment

• getElementUtils:获取element的操作类，用于扫描源码文件，源码的每一个部分都是一个element，如图：

  package com.example;    // PackageElement
  
  public class Foo {        // TypeElement
  
  private int a;      // VariableElement
  private Foo other;  // VariableElement
  
  public Foo () {}    // ExecuteableElement
  
  public void setA (  // ExecuteableElement
                   int newA   // TypeElement
                   ) {}
  }
  

  Element可以是类、方法、变量等等。

• getMessager: 获取Messager的操作类，用于报告错误、警告 以及 提示信息的途径。

Test

1. testCompile 'com.google.testing.compile:compile-testing:0.8'：但是因为编译出来的文件中存在当前工程没有的类，所以虽然测试用例过了，但是依然会报错。

使用缺点

1. 额外生成一定量的类：编译时间加长、包变大
2. 可读性比较差：对代码的理解需要一定的门槛

引用文章

1. annotation processing tool教程