Java 注解

Java的注解是个很神奇的东西，它既可以帮你生成代码，又可以结合反射来在运行时获得注解标识的对象，进行逻辑处理，它能帮助我们完成很多很多不可能完成的任务，这回我们就来一起来了解下它。

一、什么可以被注解修饰

Java中的类、方法、变量、参数、包都可以被注解，在java8中注解可以被运用到任何地方。比如：

myString = (@NonNull String) str;
class UnmodifiableList<T> implements @Readonly List<@Readonly T> { ... }
new @Interned MyObject();

需要注意的是，类型注解只是语法而不是语义，并不会影响java的编译时间，加载时间，以及运行时间。在Java8没有普及的情况下，本文仅仅讨论在jdk1.7中可被用于实践的注解方案。

二、注解的类型

2.1 引子

我们先从我们最熟悉的@Override说起

/**
 * Annotation type used to mark methods that override a method declaration in a
 * superclass. Compilers produce an error if a method annotated with @Override
 * does not actually override a method in a superclass.
 *
 * @since 1.5
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

我们注意到了@Target和@Retention这两个注解，这两个家伙就是专门用来修饰注解的注解，看起来吊吊的，但在实际开发中我们都不会去用到他们，所以我们不是很熟悉。但今天我们已经开始学习注解了，姑且就和他们打个招呼吧，先照猫画虎写一个自己的注解，注解的名字叫做classInfo：

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

 String value() default "default";

}

先不管这个注解有什么用，我们就看这个注解类的标识，其实上面两行标识就是起一个说明作用，和他们一样的还有@Document等。

@Documented 是否会保存到 Javadoc 文档中

@Retention 保留时间，可选值 SOURCE（源码时），CLASS（编译时），RUNTIME（运行时），默认为 CLASS。

如果值为 SOURCE 大都为 Mark Annotation，这类 Annotation 大都用来校验，比如 Override, Deprecated, SuppressWarnings

@Target 来指定这个注解可以修饰哪些元素，如 TYPE, METHOD, CONSTRUCTOR, FIELD, PARAMETER 等，未标注则表示可修饰所有类型

@Inherited 是否可以被继承，默认为 false

2.2 详细说明

我们来详细说说看:

@Documented 这个东西如果加在了注解上面，就会在生成java doc时有相关注解的文档，在小项目开发过程中，这个注解意义不大，可以忽略。

@Retention 它里面的值都是以RetentionPolicy开头的，来看看源码是怎么写的：

public enum RetentionPolicy {
    /**
     * Annotation is only available in the source code.
     */
    SOURCE,
    /**
     * Annotation is available in the source code and in the class file, but not
     * at runtime. This is the default policy.
     */
    CLASS,
    /**
     * Annotation is available in the source code, the class file and is
     * available at runtime.
     */
    RUNTIME
}

• 如果是SOURCE，注解保留范围为源代码，在编译时将会被编译器丢弃。这类 Annotation 大都用来校验，比如 Override, Deprecated, SuppressWarnings。
• 如果是CLASS，这个注解保留范围是源代码和类文件中，但并非作用于运行时，所以JVM不会识别此。如果你在自定义注解时，不写@Retention，默认就是CLASS的。这类的注解和SOURCE的注解都可以配合AbstractProcessor进行使用，用于在编译时进行自动处理一些事物或者生成一些文件。
• 如果是RUNTIME，这个注解的保留范围是源代码、类文件和运行时，这类的注解一般会和反射配合使用。可以在运行时通过反射查看被这个注解标识的方法，然后得到被标识的元素，接着进行处理。

 　　　　　　 final Method[] allMethods = clazz.getDeclaredMethods();
            for (Method method : allMethods) {
                // 根据注解来解析函数
                Subscriber annotation = method.getAnnotation(Subscriber.class);
　　　　　　　｝

上面这段代码会遍历这个类中被标识了@Subscriber的方法。但如果我们把@Subscriber设定为@Retention(RetentionPolicy.CLASS)，这时这个注解就不会被保留到运行时的代码中了，因此我们用反射就获取不到，就会报出如下错误。

@Target 指定注解可以被标识于哪种Java元素上，指定类型（ElementType）如下：

• ElementType.ANNOTATION_TYPE 注释类型声明。
• ElementType.CONSTRUCTOR 构造方法声明。
• ElementType.FIELD 字段声明（包括枚举常量）。
• ElementType.LOCAL_VARIABLE 局部变量声明。
• ElementType.METHOD 方法声明。
• ElementType.PACKAGE 包声明。
• ElementType.PARAMETER 参数声明。
• ElementType.TYPE 类、接口（包括注释类型）或枚举声明。

这个注解标识仅仅做个标识，没有任何代码逻辑，它的目的是避免使用者随便标识注解，从而造成处理注解时出现错误。

三、自定义编译时注解

3.1 编译时注解

所谓编译时注解就是在你写代码时，就能产生作用的注解，一旦程序运行成apk，你的注解就没用了，所以它的生命周期在于你写代码到编译的过程之间。我们先来看看一个Android特有的注解方式，这种注解方式属于特殊的编译时注解。

　　 public static final int VANILLA = 0;
    public static final int CHOCOLATE = 1;
    public static final int STRAWBERRY = 2;
 
    @IntDef({VANILLA, CHOCOLATE, STRAWBERRY})
    public @interface Flavour {
    }

首先我们定义了三个常量，然后定义了一个注解 @Flavour，在这个注解上用@IntDef标识了这个注解的作用。说明用@Flavour标识的变量，必须是0,1,2这三个int类型值，是不是很像枚举类型呢？其实它就是为了替代枚举而出现的（Android中枚举的效率稍低）。在使用的时候，我们只需要像如下标识，编译器就会自动进行判断，从而提升代码质量。

　　@Flavour
    public int getFlavour() {
        return flavour;
    }
 
    public void setFlavour(@Flavour int flavour) {
        this.flavour = flavour;
    }

如果在使用的时候传入了错误的值（不是0,1,2），编译器自动会提示警告：

好了，上面仅仅是小试牛刀，现在我们开始真正写一个编译时注解。

我希望有个注解可以帮助我们自动生成网络请求的代码，之前我们的网络请求代码是这样的：

public Observable post041(String create_time, String user_name) {
        HashMap<String, String> map = new HashMap<>();
        map.put("create_time", create_time);
        map.put("user_name", user_name);
        map.put("name", "kale");
        map.put("user", "aaaa3");

        return (Observable) mHttpRequest.doPost("http://image.baidu.com", map, null);
}

这种代码就是模板式代码，注解最适合干掉这样的代码了。高兴之余，先分析下需求，拆分可变部分和不可变部分是主要需求，我们的可变部分在于定义url，请求的参数，其中包含默认的请求参数还有从外部传入的请求参数，还有进行json解析的model类、是get请求还是post请求。

分析完毕，分分钟定义一个注解：

@Documented
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.METHOD)
public @interface HttpPost {

    String url();

    Class<?> model() default HttpProcessor.class;
}

这个注解中包含两个方法，一个是url，这个是必须传入的（使用者不写就会报错）。如果你这个请求没有解析的model，那么就不用传入model对象，所以这里给一个默认的model对象。这个注解我希望出现在java doc里面，所以加上了@documented。这个注解标识的是java中的method，所以写了method，而且我希望它仅仅是在编译时有效，所以用了source。

现在定义好了，开始使用：

 @HttpPost(url =  "http://image.baidu.com?user=aaaa3&name=kale", model = String.class)
 Observable post041(String create_time, String user_name);

将url写入注解中，并且定义好model（如果不需要json解析，可以不定义），如果是必须传的参数，就和url写到一起，把需要从外部得到的注解写到方法的参数中。现在两行代码写了一个网络请求，是不是很简单呢？现在api、请求方法体、解析model的聚合度变得很高了。注意哦，现在调用这个方法其实根本不起作用，因为我们还没有去解析这个注解呢，下面来说说怎么解析。

3.2 建立解析编译时注解类

首先在as中建立一个java的lib，然后在这个lib中开始写解析类。我建立了HttpProcessor这个类，这个类继承了AbstractProcessor这个类，它会强制你实现process这个方法，这样HttpProcessor就有了解析注解的能力了。

public class HttpProcessor extends AbstractProcessor{

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        return false;
    }
}

接着，我在头部定义一些配置代码：

@SupportedAnnotationTypes({"kale.net.http.annotation.HttpPost"})
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class HttpProcessor extends AbstractProcessor {

上面两行代码定义了这个类能处理的注解类，并且标识了基于的java版本。写完了之后千万不要忘记了把这个注解处理类注册到项目中，注册的方法就是在resource/META-INF/services中建立一个javax.annotation.processing.Processor文件，在里面写上这个注解处理类的全名。如果你有多个注解处理类，请用回车分割。

3.2 解析注解

我们为了方便首先在init时定义好一个工具类，以后会用到。

　　private Elements elementUtils;

    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        elementUtils = processingEnv.getElementUtils();
    }

然后，在process方法中开始处理传入的注解对象。需要注意的是，这个process方法会被调用多次，调用次数取决于你这个注解处理类能处理的注解个数。

@SupportedAnnotationTypes({"kale.net.http.annotation.HttpPost"})
@SupportedSourceVersion(SourceVersion.RELEASE_7)
public class HttpProcessor01 extends AbstractProcessor{

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        // 传入当前注解处理器可以处理的注解元素
        for (TypeElement te : annotations) {
            // 找到被标识了可处理的注解的元素
            for (Element e : roundEnv.getElementsAnnotatedWith(te)) {
                if (e.getKind() == ElementKind.INTERFACE) {
                    // 如果是接口
                    TypeElement ele = (TypeElement) e;
                    // ……
                    
                    
                } else if (e.getKind() == ElementKind.METHOD) {
                    // 如果是方法
                    ExecutableElement method = (ExecutableElement) e;
                    // ……
                   
                }
            }
        }
        return true;
    }
}

代码有些复杂，我分布讲解：

@Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        // 传入当前注解处理器可以处理的注解元素
        for (TypeElement te : annotations) {
            // 找到被标识了可处理的注解的元素
            for (Element e : roundEnv.getElementsAnnotatedWith(te)) {

在这个for循环中，我们可以利用 e.getKind() 这个方法来判断注解标识的是什么对象，如果是方法就采用方法的处理逻辑，如果标识的是类就采用类的处理逻辑，如果是接口就用接口的，根据需要进行处理即可。

　　　　　　     if (e.getKind() == ElementKind.METHOD) {
                    // 如果是方法
                    ExecutableElement method = (ExecutableElement) e;
                    if (method.getAnnotation(HttpPost.class) != null) {
                        handlerHttp(mStringBuilder, e, method, true);
                   ｝
                }

进入if块后，我首先将e进行了强制转换，为啥要强制转换呢，因为e是标识被@httpPost标识的元素对象，但目前程序不知道它是什么类型的。我们通过之前的判断，知道它现在是方法对象，所以在这里就强转了。那么如果是接口改强转成什么呢？如果是类应该强转什么呢？来看下面的说明：

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
   　　　　　　　　　　　) {}
}

如果注解标识到了类中，就强转为TypeElement；

如果标识的是变量，就强转VariableElement；

如果标识内部类或者方法，强转ExecuteableElement；

如果标识方法中的参数，就强转为TypeElement。

说明：这里的每个强转后的对象都有自己好用的api，我就不详细说明了，大家可以在用的时候进行测试。

现在我们必须换个角度来看源代码，它只是结构化的文本，他不是可运行的。你可以想象它就像你将要去解析的XML文件一样（或者是编译器中抽象的语法树）。就像XML解释器一样，有一些类似DOM的元素。你可以从一个元素导航到它的父或者子元素上。

举例来说，假如你有一个代表public class Foo类的TypeElement元素，你可以遍历它的孩子，如下：

TypeElement fooClass = ... ;  
for (Element e : fooClass.getEnclosedElements()){ // iterate over children  
    Element parent = e.getEnclosingElement();  // parent == fooClass
}

正如你所见，Element代表的是源代码。TypeElement代表的是源代码中的类型元素，例如类。然而，TypeElement并不包含类本身的信息。你可以从TypeElement中获取类的名字，但是你获取不到类的信息，例如它的父类。这种信息需要通过TypeMirror获取。你可以通过调用elements.asType()获取元素的TypeMirror。

好，现在我们回过头来扩充上面的那段代码：

@Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        // 传入当前注解处理器可以处理的注解元素
        for (TypeElement te : annotations) {
            // 找到被标识了可处理的注解的元素
            for (Element e : roundEnv.getElementsAnnotatedWith(te)) {
                if (e.getKind() == ElementKind.INTERFACE) {
                    // 如果是接口
                    TypeElement ele = (TypeElement) e;
                    if (ele.getAnnotation(ApiInterface.class) != null) {
                        String interFaceName = ele.getQualifiedName().toString();
                        mStringBuilder = createClsBlock(interFaceName, mStringBuilder);
                    } else {
                        fatalError("Should use " + ApiInterface.class.getName());
                    }
                } else if (e.getKind() == ElementKind.METHOD) {
                    // 如果是方法
                    ExecutableElement method = (ExecutableElement) e;
                    if (method.getAnnotation(HttpPost.class) != null) {
                        handlerHttp(mStringBuilder, e, method, true);
                    } else {
                        handlerHttp(mStringBuilder, e, method, false);
                    }
                }
            }
        }
        mStringBuilder.append("
}");
        createClassFile(PACKAGE_NAME, CLASS_NAME, mStringBuilder.toString());
        return true;
    }

如果是被标识为@HttpPost的方法体，那么就开始进入handlerHttp（…）中了。这个方法的代码和注解其实没啥关系了，就是做些字符串的拼接，拼接完毕后生成一个类文件。

public void handlerHttp(StringBuilder sb, Element ele, ExecutableElement method, boolean isPost) {
        String url;
        String modelName;
        if (isPost) {
            HttpPost httpPost = ele.getAnnotation(HttpPost.class);
            url = httpPost.url();
            try {
                modelName = httpPost.model().getName();
            } catch (MirroredTypeException ex) {
                modelName = ex.getTypeMirror().toString();
            }
        } else {
            HttpGet httpGet = ele.getAnnotation(HttpGet.class);
            url = httpGet.url();
            try {
                modelName = httpGet.model().getName();
            } catch (MirroredTypeException ex) {
                modelName = ex.getTypeMirror().toString();
            }
        }

        if (url.equals("")) {
            fatalError("Url is null");
            return;
        }
        log("Working on method: " + method.getSimpleName());
        Map<String, String> defaultParams = UrlUtil.getParams(url);
        List<String> customParams = getCustomParams(method);
        if (modelName.equals(HttpProcessor.class.getName())) {
            modelName = null;
        }

        if (modelName != null && modelName.contains("<any?>")) {
            modelName = modelName.replace("<any?>", UrlUtil.url2packageName(url));
        }
        url = UrlUtil.getRealUrl(url);
        if (isPost) {
            sb.append(createPostMethodBlock(method.getSimpleName().toString(), url, defaultParams, customParams, modelName));
        } else {
            sb.append(createGetMethodBlock(method.getSimpleName().toString(), url, defaultParams, customParams, modelName));
        }
        log("Parse method: " + method.getSimpleName() + " completed");
    }

3.3 生成文件的方法

还记得我们在init中产生的工具类么，现在我们需要靠它来生成文件了。传入类包名、类名和类内部的信息就行。

private void createClassFile(String PACKAGE_NAME, String clsName, String content) {
        //PackageElement pkgElement = elementUtils.getPackageElement("");
        TypeElement pkgElement = elementUtils.getTypeElement(PACKAGE_NAME);

        OutputStreamWriter osw = null;
        try {
            JavaFileObject fileObject = processingEnv.getFiler().createSourceFile(PACKAGE_NAME + "." + clsName, pkgElement);
            OutputStream os = fileObject.openOutputStream();
            osw = new OutputStreamWriter(os, Charset.forName("UTF-8"));
            osw.write(content, 0, content.length());

        } catch (IOException e) {
            e.printStackTrace();
            //fatalError(e.getMessage());
        } finally {
            try {
                if (osw != null) {
                    osw.flush();
                    osw.close();
                }
            } catch (IOException e) {
                e.printStackTrace();
                fatalError(e.getMessage());
            }
        }
    }

3.4 打log的方法

注解中的log有个自己的api，封装一下就是这样了：

　　 private void log(String msg) {
        if (processingEnv.getOptions().containsKey("debug")) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, TAG + msg);
        }
    }

    private void fatalError(String msg) {
        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, TAG + " FATAL ERROR: " + msg);
    }

关于详细的代码可以参考：https://github.com/tianzhijiexian/HttpAnnotation

关于用编译时注解写工厂方法的代码：http://www.codeceo.com/article/java-annotation-processor.html

类似的用注解写网络框架的文章：http://segmentfault.com/a/1190000002785541

四、运行时注解

有时候一些注解会配合反射进行调用，比如事件总线。

/**
 * 事件接收函数的注解类,运用在函数上
 *
 * @author mrsimple
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Subscriber {

    /**
     * 事件的tag,类似于BroadcastReceiver中的Action,事件的标识符
     */
    String tag();

}

这种注解必须把生命周期写到Runtime，否则反射就获取不到它了。写好了后，就可以通过反射来得到它标记的元素，从而进行处理：

public void registerMethods(Object subscriber) {
        Class<?> clazz = subscriber.getClass();
        // 查找类中符合要求的注册方法,直到Object类
        while (clazz != null && !isSystemCls(clazz.getName())) {
            final Method[] allMethods = clazz.getDeclaredMethods();
            for (Method method : allMethods) {
                // 根据注解来解析函数
                Subscriber annotation = method.getAnnotation(Subscriber.class);
                if (annotation != null) {
                    String tag = annotation.tag();
                    // 获取方法的tag
                    if (!TextUtils.isEmpty(tag)) {
                        SubscriberBean bean = new SubscriberBean();
                        bean.setSubscriber(subscriber);
                        bean.setMethod(method);
                        if (subscriberMap.containsKey(tag)) {
                            // 如果已经有这个tag了，那么说明已经有人注册了，所以可以直接添加到注册列表中
                            subscriberMap.get(tag).add(bean);
                        } else {
                            // 如果之前没有这个tag，那么建立新的注册列表
                            List<SubscriberBean> list = new ArrayList<>();
                            list.add(bean);
                            subscriberMap.put(tag, list);
                  
                        }
                    }
                }
            } // end for
            // 获取父类,以继续查找父类中符合要求的方法
            clazz = clazz.getSuperclass();
        }
    }

如果想用注解干掉findviewById也是可以的。先定义一个注入的注解：

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface InjectView 
{
  //id就是控件id，在某一个控件上使用注解标注其id
  int id() default -1;
}

在activity中进行反射查找，找到了后利用注解自动调用findviewById即可：

public class MainActivity extends Activity 
{
  public static final String TAG=MainActivity;
  //标注TextView的id
  @InjectView(id=R.id.tv_img)
  private TextView mText;
   
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    try {
      autoInjectAllField(this);
    } catch (IllegalAccessException e) {
    } catch (IllegalArgumentException e) {
    }
     
    if(mText!=null)
      mText.setText(Hello Gavin);
  }
   
  public void autoInjectAllField(Activity activity) throws IllegalAccessException, IllegalArgumentException
  {
    //得到Activity对应的Class
    Class clazz=this.getClass();
    //得到该Activity的所有字段
    Field []fields=clazz.getDeclaredFields();
    Log.v(TAG, fields size-->+fields.length);
    for(Field field :fields)
    {
      //判断字段是否标注InjectView
      if(field.isAnnotationPresent(InjectView.class))
      {
        Log.v(TAG, is injectView);
        //如果标注了，就获得它的id
        InjectView inject=field.getAnnotation(InjectView.class);
        int id=inject.id();
        Log.v(TAG, id--->+id);
        if(id>0)
        {
          //反射访问私有成员，必须加上这句
          field.setAccessible(true);
          //然后对这个属性赋值
          field.set(activity, activity.findViewById(id));
        }
      }
    }
  }
 
}

 如果你活学活用了这一特性，那么你完全可以用它做任何事情。假如你厌倦了在Android程序中打出一个完整的静态限定常量，比如：

public class CrimeActivity {
    public static final String ACTION_VIEW_CRIME = 
        “com.bignerdranch.android.criminalintent.CrimeActivity.ACTION_VIEW_CRIME”;
}

你完全可以使用一个运行时注解来帮你做这些事情。首先，创建一个注解类：

@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.FIELD })
public @interface ServiceConstant { }

一旦定义了注解，我们接着就要写些代码来寻找并自动填充带注解的字段：

public static void populateConstants(Class<?> klass) {
    String packageName = klass.getPackage().getName();
    for (Field field : klass.getDeclaredFields()) {
        if (Modifier.isStatic(field.getModifiers()) && 
                field.isAnnotationPresent(ServiceConstant.class)) {
            String value = packageName + "." + field.getName();
            try {
                field.set(null, value);
                Log.i(TAG, "Setup service constant: " + value + "");
            } catch (IllegalAccessException iae) {
                Log.e(TAG, "Unable to setup constant for field " + 
                        field.getName() +
                        " in class " + klass.getName());
            }
        }
    }
}

哈哈，现在我们就可以用注解自动赋值常量了：

public class CrimeActivity {
    @ServiceConstant
    public static final String ACTION_VIEW_CRIME;

    static {
        ServiceUtils.populateConstants(CrimeActivity.class);
}

得到className的小技巧：

 try {
                modelName = httpPost.model().getName();
            } catch (MirroredTypeException ex) {
                modelName = ex.getTypeMirror().toString();
            }

参考自：

http://www.trinea.cn/android/java-annotation-android-open-source-analysis/

http://blog.zenfery.cc/archives/78.html

http://www.race604.com/annotation-processing/

http://www.2cto.com/kf/201405/302998.html

http://objccn.io/issue-11-6/

http://www.codeceo.com/article/java-annotation-processor.html