「深入Java」Annotation注解

2016-01-14 本文已影响2184人郭非文

欢迎转载，但请保留作者链接：http://www.jianshu.com/p/82093e5160ae
阅读前提：了解反射及类型信息
相关文章「深入Java」类型信息：RTTI和反射

提供额外的信息与操作手段——这就是“注解”全部的意义。

内置注解

以下三个是java.lang包下的内置注解：

// 方法注解，表示此注解修饰的方法覆盖了父类或是接口的方法
// 如果不是这样，则输出警告
@Override

// 对于此注解所修饰的对象（类、域、方法等）
// 当你使用了它们时编译器将输出“已废弃”警告
@Deprecated

// 关闭警告，通过给此注解的元素赋值
// 可以关闭特定警告
@SuppressWarnings

元注解

元注解，用来注解注解的注解——有点绕-_-||。

// 定义注解所能作用的目标，说明该注解能作用于何种对象（类、方法、域……之类）。
@Target

// 定义注解保存级别
// 1.源代码注解，被编译器丢弃
// 2.类注解，class文件中可用，被VM丢弃
// 3.运行时可用，搭配反射
@Retention

// 标志将此注解包含至javadoc中
@Documented

// 说明假如此注解是类注解而且你在父类中使用此注解，那么子类将会继承此注解
@Inherited

定义注解

我们来看一下官方例子@Override的源码：

@Target(ElementType.METHOD) // 此注解作用于方法
@Retention(RetentionPolicy.SOURCE) // 源代码级别
    public @interface Override {
}

其中，ElementType，RetentionPolicy是enum类型。
定义上看起来有点像interface，这实在是很奇怪的一点。不过事实上，注解也被会编译成.class文件。
两个元注解@Target,@Retention作用于注解@Override。
对于@Override来说，从它所作用的目标上考虑，因为是用于检查方法是否正确覆盖自父亲（或接口），所以作用于方法就好；从它的保存级别上考虑，因为这个注解仅用于提供编译期检查，之后就没有用了，所以应该被编译器丢弃。

注解持有的元素

至于像@Target(ElementType.METHOD)这样的描述是什么意思，我们先看下@Target的源码：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
    ElementType[] value();
}

ElementType[] value();看上去有点像interface中的方法定义，但两者其实没有任何关联。在官方叫法上，"value 是属于 @Target 的元素"。
注意元素支持的类型是有限定的，这一点可以查询相关资料。而十分有用的一个特性在于，可以将一个注解作为另一个注解的元素。

@Target(ElementType.METHOD)其实就是在给注解@Target的元素value赋值，标准写法应该是@Target(value = ElementType.METHOD)，然而这里存在一个隐晦规则：

如果注解中定义了value元素
如果在使用注解时value是惟一需要赋值的元素
那么只需在括号内给出value的值即可

这就是最终简写的原因。

可以给元素添加一个默认值像是这样:

ElementType[] value() default {ElementType.ANNOTATION_TYPE};

这样假如在使用@Target时没有给出value的值，那么处理@Target的注解处理器就会使用默认值。
注意，元素不能有不确定的值，即要么存在默认值，要么就在使用注解时给元素赋值。

对于元注解@Target，如果你希望一个注解可以作用于ElementType中的所有类型，那么就可以不使用@Target——@Deprecated就是这样做的。

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}

注解不支持继承

注解不支持继承，不能用extends关键字来完成“父注解抽象”这样便利的事。不过好在可以将一个注解作为另一个注解的元素，这可以看作是对"组合"进行了支持。

使用注解提供的信息

我们有两种方式来使用注解所提供的信息。
第一种是基于反射的注解处理器。

用《Java编程思想》中的例子来说明问题：

考虑设计一个注解用来追踪项目中的用例，如果一个方法实现了某个用例的需求，则给它加上该注解。
通过计算完成的用例，可以掌握项目进度
如果要更改业务逻辑，开发人员也很容易在代码中找到与相应用例对应的方法

用例@UseCase是这样的：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface UseCase {
    public int id();
    public String description() default "no description";
}

在下面这个类中，有三个方法被注解为用例：

public class PasswordUtils {
  @UseCase(id = 47, description =
  "Passwords must contain at least one numeric")
  public boolean validatePassword(String password) {
      return (password.matches("\\\\w*\\\\d\\\\w*"));
  }

  @UseCase(id = 48)
  public String encryptPassword(String password) {
      return new StringBuilder(password).reverse().toString();
  }

  @UseCase(id = 49, description =
  "New passwords can’t equal previously used ones")
  public boolean checkForNewPassword(
      List<String> prevPasswords, String password) {
      return !prevPasswords.contains(password);
  }
}

再是一个处理此注解的类：

public class UseCaseTracker {
  public static void trackUseCases(List<Integer> useCases, Class<?> cl) {
      for(Method m : cl.getDeclaredMethods()) {
          UseCase uc = m.getAnnotation(UseCase.class);
          if(uc != null) {
              System.out.println("Found Use Case:" + uc.id() +
              " " + uc.description());
              useCases.remove(new Integer(uc.id()));
          }
      }
      for(int i : useCases) {
          System.out.println("Warning: Missing use case-" + i);
      }
  }

  public static void main(String[] args) {
      List<Integer> useCases = new ArrayList<Integer>();
      Collections.addAll(useCases, 47, 48, 49, 50);
      trackUseCases(useCases, PasswordUtils.class);
  }
}

/* Output:
Found Use Case:47 Passwords must contain at least one numeric
Found Use Case:48 no description
Found Use Case:49 New passwords can’t equal previously used ones
Warning: Missing use case-50
*///:~

第二种是基于apt的注解处理工具。
apt:annotation processing tool
总得来说，实现一个apt工具分两步，一是实现处理器（实现接口AnnotationProcessor），二是实现返回此处理器的工厂类（实现接口AnnotationProcessorFactory）。
最后运行命令使用它，如：

apt -nocompile -factory com.bjinfotech.practice.annotation.apt.ReviewProcessorFactory  ./*.java

这一条命令及以下内容摘自：Java Annotation 高级应用，更多内容敬请查看原文：

何谓APT？
根据sun官方的解释，APT（annotation processing tool）是一个命令行工具，它对源代码文件进行检测找出其中的annotation后，使用annotation processors来处理annotation。而annotation processors使用了一套反射API并具备对JSR175规范的支持。

annotation processors处理annotation的基本过程如下：首先，APT运行annotation processors根据提供的源文件中的annotation生成源代码文件和其它的文件（文件具体内容由annotation processors的编写者决定），接着APT将生成的源代码文件和提供的源文件进行编译生成类文件。

简单的和前面所讲的annotation实例BRFW相比，APT就像一个在编译时处理annotation的javac。而且从sun开发者的blog中看到，java1.6 beta版中已将APT的功能写入到了javac中，这样只要执行带有特定参数的javac就能达到APT的功能。

为何使用APT？
使用APT主要目的是简化开发者的工作量，因为APT可以在编译程序源代码的同时，生成一些附属文件（比如源文件、类文件、程序发布描述文字等），这些附属文件的内容也都是与源代码相关的。换句话说，使用APT就是代替了传统的对代码信息和附属文件的维护工作。使用过hibernate或者beehive等软件的朋友可能深有体会。APT可以在编译生成代码类的同时将相关的文件写好，比如在使用beehive时，在代码中使用annotation声明了许多struct要用到的配置信息，而在编译后，这些信息会被APT以struct配置文件的方式存放。
如何定义processor？
APT工作过程：
从整个过程来讲，首先APT检测在源代码文件中哪些annotation存在。然后APT将查找我们编写的annotation processor factories类，并且要求factories类提供处理源文件中所涉及的annotation的annotation processor。接下来，一个合适的annotation processors将被执行，如果在processors生成源代码文件时，该文件中含有annotation，则APT将重复上面的过程直到没有新文件生成。
编写annotation processors：
编写一个annotation processors需要使用java1.5 lib目录中的tools.jar提供的以下4个包：
com.sun.mirror.apt: 和APT交互的接口；
com.sun.mirror.declaration: 用于模式化类成员、类方法、类声明的接口；
com.sun.mirror.type: 用于模式化源代码中类型的接口；
com.sun.mirror.util: 提供了用于处理类型和声明的一些工具。

每个processor实现了在com.sun.mirror.apt包中的AnnotationProcessor接口，这个接口有一个名为“process”的方法，该方法是在APT调用processor时将被用到的。一个processor可以处理一种或者多种annotation类型。

一个processor实例被其相应的工厂返回，此工厂为AnnotationProcessorFactory接口的实现。APT将调用工厂类的getProcessorFor方法来获得processor。在调用过程中，APT将提供给工厂类一个AnnotationProcessorEnvironment 类型的processor环境类对象，在这个环境对象中，processor将找到其执行所需要的每件东西，包括对所操作的程序结构的参考，与APT通讯并合作一同完成新文件的建立和警告/错误信息的传输。

提供工厂类有两个方式：通过APT的“-factory”命令行参数提供，或者让工厂类在APT的发现过程中被自动定位（关于发现过程详细介绍[请看这里](http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html)）。前者对于一个已知的factory来讲是一种主动而又简单的方式；而后者则是需要在jar文件的META-INF/services目录中提供一个特定的发现路径：

在包含factory类的jar文件中作以下的操作：在META-INF/services目录中建立一个名为com.sun.mirror.apt.AnnotationProcessorFactory 的UTF-8编码文件，在文件中写入所有要使用到的factory类全名，每个类为一个单独行。

本篇至此结束。

参考资料

《Java编程思想》