Java Annotation

一、概述    

     Annotation 是Java JDK 5.0 映入的新特性，是一种安全的注解机制，用来标注数据元素与程序元素(类、方法、属性等)之间的关系。注解不影响程序的运行，只是一种标记的方式而已，获得注解的相关信息，可以通过反射形式获取。

二、基本API摘要

    Annotation 相关的API类在java.lang.annotaiton 包下，包含以下   

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

注解类型	含义
Documented	表示含有该注解类型的元素(带有注释的)会通过javadoc或类似工具进行文档化
Inherited	表示注解类型能被自动继承
Retention	表示注解类型的存活时长
Target	表示注解类型所适用的程序元素的种类

(2). 枚举(Enum) API

枚举	含义
ElementType	程序元素类型，用于Target注解类型
RetentionPolicy	注解保留策略，用于Retention注解类型

(3). 异常和错误 API

异常/错误	含义
AnnotationTypeMismatchException	当注解经过编译(或序列化)后，注解类型改变的情况下，程序视图访问该注解所对应的元素，则抛出此异常
IncompleteAnnotationException	当注解经过编译(或序列化)后，将其添加到注解类型定义的情况下，程序视图访问该注解所对应的元素，则抛出此异常。
AnnotationFormatError	当注解解析器试图从类文件中读取注解并确定注解出现异常时，抛出该错误

三、注解类型

      注解类型用于在自定义注解时修饰相关策略于机制，包好Document、Inherited、Retention和Target。

    (1). Document

        源码:

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

         指示某一类型的注释将通过 javadoc 和类似的默认工具进行文档化。应使用此类型来注释这些类型的声明：其注释会影响由其客户端注释的元素的使用。如果类型声明是用 Documented 来注释的，则其注释将成为注释元素的公共 API 的一部分。

    (2).Inherited

        源码:

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

        指示注释类型被自动继承。如果在注释类型声明中存在 Inherited 元注释，并且用户在某一类声明中查询该注释类型，同时该类声明中没有此类型的注释，则将在该类的超类中自动查询该注释类型。此过程会重复进行，直 到找到此类型的注释或到达了该类层次结构的顶层 (Object) 为止。如果没有超类具有该类型的注释，则查询将指示当前类没有这 样的注释。

注意，如果使用注释类型注释类以外的任何事物，此元注释类型都是无效的。还要注意，此元注释仅促成从超类继承注释；对已实现接口的注释无效。

 (3).Rntention

       源码:

        

        

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
    /**
     * Returns the retention policy.
     * @return the retention policy
     */
    RetentionPolicy value();
}

    

        指示注释类型的注释要保留多久。如果注释类型声明中不存在 Retention 注释，则保留策略默认为   RetentionPolicy.CLASS 。

只有元注释类型直接用于注释时，Target 元注释才有效。如果元注释类型用作另一种注释类型的成员，则无效。

        Retention 保留机制由RetentionPolicy 枚举提供，包含如下选项

        

RetentionPolicy	含义
SOURCE	源码中保留，编译器在编译时丢弃
CLASS	保留在Class 字节码文件中，但是在运行时JVN 不保留此注解
RUNTIME	保留在Class 字节码文件中，但是在运行时JVN 保留此注解，因此可以使用反射获取

 (4).Target

       源码:

        

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
    /**
     * Returns an array of the kinds of elements an annotation type
     * can be applied to.
     * @return an array of the kinds of elements an annotation type
     * can be applied to
     */
    ElementType[] value();
}

     指示注释类型所适用的程序元素的种类。如果注释类型声明中不存在 Target 元注释，则声明的类型可以用在任一程序元素上。如果存在这样的元注释，则编译器强制实施指定的使用限制。修饰的程序元素有ElementType 枚举修饰，包含以下类型：

    

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

四、获取注解

          获取注解的内容可以通过Class 中的相关方法获取，涉及到一下方法

       

返回值	方法	解释
T	getAnnotation(Class annotationClass)	当存在该元素的指定类型注解，则返回相应注释，否则返回null
Annotation[]	getAnnotations()	返回此元素上存在的所有注解
Annotation[]	getDeclaredAnnotations()	返回直接存在于此元素上的所有注解。
boolean	isAnnotationPresent(Class<? extends Annotation> annotationClass)	当存在该元素的指定类型注解，则返回true，否则返回false

五、自定义注解

    语法：

        public @interface Annotiaon_Name {

                [FiledType filedName() [defualt ] ];

        }

        注意

        1、参数类型只支持基本数据类型、String 、枚举、数组和Annotation

        2、可以使用default 指定默认值

    

     实例：

           a>.定义自定义注解

           @Document

           @Inherited

           @Target({ElementType.METHOD, ElementType.FIELD})

           @Retention(RetentionPolicy.RUNTIME)

          public @interface Test {

                public String name default "张三";

                public int age;

        }

        b>.使用注解

        public class User {

            @Test(name="李四"， age = 20)

            public String A;

        }

        

        c>.使用反射获得注解相关的信息

            Test test = Test.class. getAnnotation(Test.class);

            System.out.println(“name : ” + test.name + "    age: " + test.age );