Java注解(Annotation)

本文讲述Java Annotation的原理，如何自定义Java注解以及通过反射解析注解。

一、注解

1.1 概述

注解(Annotation)在JDK1.5之后增加的一个新特性，注解的引入意义很大，有很多非常有名的框架，比如Hibernate、Spring等框架中都大量使用注解。注解作为程序的元数据嵌入到程序。注解可以被解析工具或编译工具解析，此处注意注解不同于注释(comment)。

当一个接口直接继承java.lang.annotation.Annotation接口时，仍是接口，而并非注解。要想自定义注解类型，只能通过@interface关键字的方式，其实通过该方式会隐含地继承.Annotation接口。

1.2 API 摘要

所有与Annotation相关的API摘要如下：

(1). 注解类型(Annotation Types) API

(2). 枚举(Enum) API

(3). 异常和错误 API

二、注解类型

前面讲到注解类型共4种，分别为Documented、Inherited、Retention、Target，接下来从jdk1.7的源码角度，来分别加以说明：

2.1 Documented

源码：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Documented {
}

@Documented：表示拥有该注解的元素可通过javadoc此类的工具进行文档化。该类型应用于注解那些影响客户使用带注释(comment)的元素声明的类型。如果类型声明是用Documented来注解的，这种类型的注解被作为被标注的程序成员的公共API。

例如，上面源码@Retention的定义中有一行@Documented，意思是指当前注解的元素会被javadoc工具进行文档化，那么在查看Java API文档时可查看当该注解元素。

2.2 Inherited

源码：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}

@Inherited：表示该注解类型被自动继承，如果用户在当前类中查询这个元注解类型并且当前类的声明中不包含这个元注解类型，那么也将自动查询当前类的父类是否存在Inherited元注解，这个动作将被重复执行知道这个标注类型被找到，或者是查询到顶层的父类。

2.3 Retention

源码：

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

@Retention：表示该注解类型的注解保留的时长。当注解类型声明中没有@Retention元注解，则默认保留策略为RetentionPolicy.CLASS。关于保留策略(RetentionPolicy)是枚举类型，共定义3种保留策略，如下表：

例如，上面源码@Retention的定义中有一行@Retention(RetentionPolicy.RUNTIME)，意思是指当前注解的保留策略为RUNTIME，即存在Java源文件，也存在经过编译器编译后的生成的Class字节码文件，同时在运行时虚拟机(VM)中也保留该注解，可通过反射机制获取当前注解内容。

2.4 Target

源码：

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

@Target：表示该注解类型的所使用的程序元素类型。当注解类型声明中没有@Target元注解，则默认为可适用所有的程序元素。如果存在指定的@Target元注解，则编译器强制实施相应的使用限制。关于程序元素(ElementType)是枚举类型，共定义8种程序元素，如下表：

例如，上面源码@Target的定义中有一行@Target(ElementType.ANNOTATION_TYPE)，意思是指当前注解的元素类型是注解类型。

三、内建注解

Java提供了多种内建的注解，下面接下几个比较常用的注解：@Override、@Deprecated、@SuppressWarnings这3个注解。

3.1 @Override(覆写)

源码：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

用途：用于告知编译器，我们需要覆写超类的当前方法。如果某个方法带有该注解但并没有覆写超类相应的方法，则编译器会生成一条错误信息。

注解类型分析：@Override可适用元素为方法，仅仅保留在java源文件中。

3.2 @Deprecated(不赞成使用)

源码：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

用途：用于告知编译器，某一程序元素(比如方法，成员变量)不建议使用时，应该使用这个注解。Java在javadoc中推荐使用该注解，一般应该提供为什么该方法不推荐使用以及相应替代方法。

注解类型分析： @Deprecated可适合用于除注解类型声明之外的所有元素，保留时长为运行时VM。

3.3 @SuppressWarnings(压制警告)

源码：

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}

用于：用于告知编译器忽略特定的警告信息，例在泛型中使用原生数据类型。

注解类型分析： @SuppressWarnings可适合用于除注解类型声明和包名之外的所有元素，仅仅保留在java源文件中。

该注解有方法value(）,可支持多个字符串参数，例如：

@SupressWarning(value={"uncheck","deprecation"})

前面讲的@Override，@Deprecated都是无需参数的，而压制警告是需要带有参数的，可用参数如下：

3.4 对比

3种内建注解的对比：

四、 实战

4.1 自定义注解

创建自定义注解，与创建接口有几分相似，但注解需要以@开头，下面先声明一个自定义注解（AuthorAnno.java）文件：

package com.gityuan.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface AuthorAnno{
    String name();
    String website() default "gityuan.com";
    int revision() default 1;
}

自定义注解规则：

1. 注解方法不带参数，比如name()，website()；
2. 注解方法返回值类型：基本类型、String、Enums、Annotation以及前面这些类型的数组类型
3. 注解方法可有默认值，比如default "gityuan.com"，默认website=”gityuan.com”

有了前面的自定义注解@AuthorAnno，那么我们便可以在代码中使用(AnnotationDemo.java)，如下：

package com.gityuan.annotation;
public class AnnotationDemo {
    @AuthorAnno(name="gityuan", website="gityuan.com", revision=1)
    public static void main(String[] args) {
        System.out.println("I am main method");
    }

    @SuppressWarnings({ "unchecked", "deprecation" })
    @AuthorAnno(name="gityuan", website="gityuan.com", revision=2)
    public void demo(){
        System.out.println("I am demo method");
    }
}

由于该注解的保留策略为RetentionPolicy.RUNTIME，故可在运行期通过反射机制来使用，否则无法通过反射机制来获取。

4.2 注解解析

接下来，通过反射技术来解析自定义注解@AuthorAnno，关于反射类位于包java.lang.reflect，其中有一个接口AnnotatedElement，该接口定义了注释相关的几个核心方法，如下：

前面自定义的注解，适用对象为Method。类Method继承类AccessibleObject，而类AccessibleObject实现了AnnotatedElement接口，那么可以利用上面的反射方法，来实现解析@AuthorAnno的功能(AnnotationParser.java)，内容如下：

package com.gityuan.annotation;
import java.lang.reflect.Method;

public class AnnotationParser {
    public static void main(String[] args) throws SecurityException, ClassNotFoundException {
        String clazz = "com.gityuan.annotation.AnnotationDemo";
        Method[]  demoMethod = AnnotationParser.class
                .getClassLoader().loadClass(clazz).getMethods();

        for (Method method : demoMethod) {
            if (method.isAnnotationPresent(AuthorAnno.class)) {
                 AuthorAnno authorInfo = method.getAnnotation(AuthorAnno.class);
                 System.out.println("method: "+ method);
                 System.out.println("name= "+ authorInfo.name() +
                         " , website= "+ authorInfo.website()
                        + " , revision= "+authorInfo.revision());
            }
        }
    }
}

程序运行的输出结果：

method: public void com.gityuan.annotation.AnnotationDemo.demo()
name= gityuan , website= gityuan.com , revision= 2
method: public static void com.gityuan.annotation.AnnotationDemo.main(java.lang.String[])
name= gityuan , website= gityuan.com , revision= 1

这里通过反射将注解直接输出只是出于demo，完全可以根据拿到的注解信息做更多有意义的事。

关于注解、反射的内容，可直接查看oracle提供的Java API： http://docs.oracle.com/javase/7/docs/api/

• 上一篇
  性能工具Traceview
• 下一篇
  Java类加载器(ClassLoader)