「深入Java」Annotation注解

96
郭非文
2016.01.14 20:34* 字数 1803

欢迎转载,但请保留作者链接: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),然而这里存在一个隐晦规则:

  1. 如果注解中定义了value元素
  2. 如果在使用注解时value是惟一需要赋值的元素
  3. 那么只需在括号内给出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 高级应用,更多内容敬请查看原文:

  1. 何谓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的功能。

  1. 为何使用APT?
    使用APT主要目的是简化开发者的工作量,因为APT可以在编译程序源代码的同时,生成一些附属文件(比如源文件、类文件、程序发布描述文字等),这些附属文件的内容也都是与源代码相关的。换句话说,使用APT就是代替了传统的对代码信息和附属文件的维护工作。使用过hibernate或者beehive等软件的朋友可能深有体会。APT可以在编译生成代码类的同时将相关的文件写好,比如在使用beehive时,在代码中使用annotation声明了许多struct要用到的配置信息,而在编译后,这些信息会被APT以struct配置文件的方式存放。

  2. 如何定义processor?

  3. APT工作过程:
    从整个过程来讲,首先APT检测在源代码文件中哪些annotation存在。然后APT将查找我们编写的annotation processor factories类,并且要求factories类提供处理源文件中所涉及的annotation的annotation processor。接下来,一个合适的annotation processors将被执行,如果在processors生成源代码文件时,该文件中含有annotation,则APT将重复上面的过程直到没有新文件生成。

  4. 编写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编程思想》
深入Java
Web note ad 1