Java注解(Annotation)详解

Java注解(Annotation)详解

基本概念
什么是注解（Annotation）
　　Annotation（注解）是JDK5.0及以后版本引入的。它可以用于创建文档，跟踪代码中的依赖性，甚至执行基本编译时检查。从某些方面来看，Annotation像一种修饰符一样，应用于包、类型、构造方法、方法、成员变量、参数以及本地变量的声明语句中。这些信息被存储在Annotation的”name=value”结构对中。更通俗的意思是为程序的元素(类、方法、成员变量等)加上更直观更明了的说明，这些说明信息是与程序的业务逻辑无关，并且是供指定的工具或框架使用的。

什么是metadata（元数据）
　　元数据从metadata一词译来，就是“关于数据的数据”的意思。
　　元数据的功能作用有很多，比如：你可能用过Javadoc的注释自动生成文档。这就是元数据功能的一种。总的来说，元数据可以用来创建文档，跟踪代码的依赖性，执行编译时格式检查，代替已有的配置文件。如果要对于元数据的作用进行分类，目前还没有明确的定义，不过我们可以根据它所起的作用，大致可分为三类：

编写文档：通过代码里标识的元数据生成文档
代码分析：通过代码里标识的元数据对代码进行分析
编译检查：通过代码里标识的元数据让编译器能实现基本的编译检查
在Java中元数据以标签的形式存在于Java代码中，元数据标签的存在并不影响程序代码的编译和执行，它只是被用来生成其它的文件或针在运行时知道被运行代码的描述信息。
综上所述：

第一，元数据以标签的形式存在于Java代码中。
第二，元数据描述的信息是类型安全的，即元数据内部的字段都是有明确类型的。
第三，元数据需要编译器之外的工具额外的处理用来生成其它的程序部件。
第四，元数据可以只存在于Java源代码级别，也可以存在于编译之后的Class文件内部。
注解（Annotation)原理
　　Annotation其实是一种接口。通过Java的反射机制相关的API来访问annotation信息。相关类(框架或工具中的类)根据这些信息来决定如何使用该程序元素或改变它们的行为。
　　Annotation是不会影响程序代码的执行，无论annotation怎么变化，代码都始终如一地执行。
　　Java语言解释器在工作时会忽略这些annotation，因此在JVM中这些annotation是“不起作用”的，只能通过配套的工具才能对这些annotation类型的信息进行访问和处理。
Annotation与Interface的异同：

Annotation类型使用关键字@interface而不是interface
这个关键字声明隐含了一个信息：它是继承了java.lang.annotation.Annotation接口，并非声明了一个interface
Annotation类型、方法定义是独特的、受限制的
Annotation类型的方法必须声明为无参数的、无异常抛出的。这些方法定义了annotation的成员：方法名成为了成员名，而方法返回值成为了成员的类型。方法返回值类型必须为primitive类型、Class类型、枚举类型、Annotation类型或者由前面类型之一作为元素的一维数组。方法的后面可以使用default和一个默认数值来声明成员的默认值，null不能作为成员默认值，这与我们在非Annotation类型中定义方法有很大不同。
Annotation类型和它的方法不能使用Annotation类型的参数、成员不能是generic。只有返回值类型是Class的方法可以在Annotation类型中使用generic，因为此方法能够用类转换将各种类型转换为Class。
Annotation类型又与接口有着近似之处
它们可以定义常量、静态成员类型（比如枚举类型定义）。Annotation类型也可以如接口一般被实现或者继承。
应用场合
　　Annotation一般作为一种辅助途径，应用在软件框架或工具中，在这些工具类中根据不同的Annotation注解信息采取不同的处理过程或改变相应程序元素(类、方法、成员变量等)的行为。
　　例如:JUnit、Struts、Spring等流行工具框架中均广泛使用了Annotation，使代码的灵活性大大提高。

Java定义的标准Annotation
从Java5版本开始，自带了四种标准Annotation类型。

@Override
　　java.lang.Override是一个标记注解（Marker Annotation）类型，它被用作标注方法。它说明了被标注的方法重载了父类的方法，起到了断言的作用。如果我们使用了这些annotation在一个没有覆盖父类方法的方法时，java编译器将以一个编译错误来警示。这个annotation常常在我们试图覆盖父类方法而却又写错了方法名时加一个保障性的校验过程。

@Deprecated
　　Deprecated也是一种标记注解（Marker Annotation）类型。当一个类型或者类型成员使用@Deprecated修饰的话，编译器将不鼓励使用这个被标注的程序元素。所以使用这种修饰具有一定的“延续性”，如果我们在代码中通过继承或者覆盖的方式使用了这个过时的类型或者成员，虽然继承或者覆盖后的类型或者成员并不是被声明为@Deprecated，但编译器仍然要报警。
　　注意：@Deprecated这个Annotation类型和Javadoc中的@deprecated这个Tag是有区别的：前者是java编译器识别的，而后者是被Javadoc工具所识别用来生成文档（包含程序成员为什么已经过时、它应当如何被禁止或者替代的描述）。

@SuppressWarnings
　　@SuppressWarnings 被用于有选择的关闭编译器对类、方法、成员变量、变量初始化的警告。
有时编译时会提出一些警告，对于这些警告有的隐藏着Bug，有的是无法避免的，对于某些不想看到的警告信息，可以通过这个注解来屏蔽。
　　SuppressWarnings不是一个标记注解（Marker Annotaion）。它有一个类型为String[]的成员，这个成员的值为被禁止的警告名。对于javac编译器来讲，被-Xlint选项有效的警告名也同样对@SuppressWarnings有效，同时编译器忽略掉无法识别的警告名。
　　Annotation语法允许在Annotation名后跟括号，括号中是使用逗号分割的name=value对用于为Annotation的成员赋值。
代码：

@SuppressWarnings(value={"unchecked","fallthrough"})
public void lintTrap() {
    /* sloppy method body omitted */
}1
　　在这个例子中SuppressWarnings Annotation类型只定义了一个单一的成员，所以只有一个简单的value={…}作为name=value对。又由于成员值是一个数组，故使用大括号来声明数组值。
　　注意：我们可以在下面的情况中缩写annotation：当annotation只有单一成员，并成员命名为“value=”。这时可以省去”value=”。比如将上面的SuppressWarnings annotation进行缩写：

@SuppressWarnings({"unchecked","fallthrough"})
　　如果SuppressWarnings所有声明的被禁止警告个数为一个时，可以省去大括号：

@suppressWarnings("unchecked")
SuppressWarnings注解的常见参数值的简单说明：

deprecation：使用了不赞成使用的类或方法时的警告
unchecked：执行了未检查的转换时的警告，例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型;
fallthrough：当 Switch 程序块直接通往下一种情况而没有 Break 时的警告
path：在类路径、源文件路径等中有不存在的路径时的警告
serial：当在可序列化的类上缺少 serialVersionUID 定义时的警告;
finally：任何 finally 子句不能正常完成时的警告;
all：关于以上所有情况的警告
Java定义的元注解
　　元注解的作用就是负责注释其他注解。Java5.0定义了4个标准的meta-annotation类型，它们被用来提供对其他annotation类型作说明。
　　Java5.0定义的元注解：

@Target
@Retention
@Documented
@Inherited
这些类型和它们所支持的类在java.lang.annotation包中可以找到。
　　下面我们看一下每个元注解的作用和相应的参数的使用说明。

@Target
　　@Target说明了Annotation所修饰的对象范围：Annotation可被用于packages、types（类、接口、枚举、Annotation类型）、类型成员（方法，构造方法、成员变量、枚举值）、方法参数和本地变量（如循环变量、catch参数）。在Annotation类的声明中使用了target可更加明晰其修饰的目标。
　　作用：用于描述注解的使用范围（即：被描述的注解可以用在什么地方）
　　取值(ElementType）有：

CONSTRUCTOR:用于描述构造器
FIELD：用于描述域
LOCAL_VARIABLE：用于描述局部变量
METHOD：用于描述方法
PACKAGE：用于描述包
PARAMETER：用于描述参数
TYPE：用于描述类、接口（包括注解类型）或enum声明
@Retention
　　@Retention定义了该Annotation被保留的时间长短：某些Annotation仅出现在源代码中，而被编译器丢弃；而另一些却被编译在class文件中；编译在class文件中的Annotation可能会被虚拟机忽略，而另一些在class被装载时将被读取（请注意并不影响class的执行，因为Annotation与class在使用上是被分离的）。使用这个meta-annotation可以对Annotation的”生命周期”限制。
　　作用：表示需要在什么级别保存该注释信息，用于描述注解的生命周期（即：被描述的注解在什么范围内有效）
　　取值（RetentionPolicy）有：

SOURCE：在源文件中有效（即源文件保留）
CLASS：在class文件中有效（即class保留）
RUNTIME：咋运行时有效（即运行时保留）
@Documented
　　@Documented用于描述其他类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。Documented是一个标记注解，没有成员。

@Inherited
　　@Inherited元注解是一个标记注解，它表示了某个被标注的类型是被继承的。如果一个使用了@Inherited修饰的annotation类型被用于一个class，则这个annotation将被用于该class的子类。
　　注意：@Inherited annotation类型是被标注过的class的子类所继承。类并不从它所实现的接口继承annotation，方法并不从它所重载的方法继承annotation。
　　当@Inherited annotation类型标注的annotation的Retention是RetentionPolicy.RUNTIME，则发射API增强了这种继承性。如果我们使用java.lang.reflect去查询一个@Inherited annotation类型的annotation时，反射代码检查将展开工作：检查class和其父类，直到发现指定的annotation类型被发现��或者到达类继承结构的顶层。

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

public @interface 注解名 ｛定义体｝

注解参数的可支持数据类型：

所有基本数据类型（int,float,boolean,byte,double,char,long,short）
String类型
Class类型
enum类型
Annotation类型
以上所有类型的数组
自定义注解（Annotation）示例
package org.grape.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/*
 * 作者信息注解
 * @author grape
 */

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface Author {
    String name() default "";
    String group() default "";
}1
package org.grape.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/*
 * 类描述注解
 * @author grape
 */

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface Description {
    String value() default "";
}1
package org.grape.annotation;

@Description(value="这是一个有用的工具类")
public class Utility {
    @Author(name="jlq",group="grape")
    public String work(){
        return "work over!";
    }
}

提取注解
package org.grape.annotation;

import java.lang.reflect.Method;

public class AnalysisAnnotation {
    public static void main(String[] args) {
        try {
            Class rt_class = Class.forName("org.grape.annotation.Utility");
            Method[] methods = rt_class.getMethods();

            boolean flag = rt_class.isAnnotationPresent(Description.class);
            if (flag) {
                Description description = (Description) rt_class
                        .getAnnotation(Description.class);
                System.out.println("Utility's Description---->"
                        + description.value());
                for (Method method : methods) {
                    if(method.isAnnotationPresent(Author.class)){
                        Author author = (Author)method.getAnnotation(Author.class);
                        System.out.println("Utility's Author---->" + author.name() + " from " + author.group());
                    }
                }
            }
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
        }
    }
}

通过此类来获得与普通Java类Utility.java关联的信息，即描述和作者。
运行AnalysisAnnotation，输出结果为：
Utility’s Description—>这是一个有用的工具类
Utility’s Author—>jlq from grape

本文永久更新链接地址：