Java Annotation ( 注解 )

Java Annotation ( 注解 )

---

JDK 5 开始， Java 增加了对元数据 (MetaData) 的支持，也就是 Annotation (注解) 。Annotation 其实是代码里的特殊标记，这些标记可以在编译、类加载、运行时被读取，并执行相应的处理。

 

通过使用注解，开发人员可以在不改变原有逻辑的情况下，在源文件中嵌入一些补充信息。代码分析工具、开发工具和部署工具可以通过这些补充信息进行验证或部署。

Annotation 提供了一种为程序元素设置元数据的方法，从某些方面来看， Annotation 就像修饰符一样，可用于修饰包、接口、类、构造器、方法、成员变量、参数、局部变量的声明，这些信息被存储在 Annotation 的 "name=value" 对中。

Annotation 是一个接口，程序可以通过反射来获取指定程序元素的 Annotation 对象，然后通过 Annotation 对象来取得注解里的元数据。

Annotation 不影响程序代码的执行，无论增加、删除 Annotation ，代码都始终如一地执行。如果希望让程序中的 Annotation 在运行时起一定作用，只有通过某种配套的工具对 Annotation 中的信息进行访问和处理。
访问和处理 Annotation 的工具统称 APT (Annotation Processing Tool)



1 基本 Annotation
---------------------------------------------------------------------------------------------------
Annotation 必须使用工具来处理，工具负责提取 Annotation 里包含的元数据，工具还会根据这些元数据增加额外的功能。
使用 Annotation 时要在其前面增加 @ 符号，并把该 Annotation 当成一个修饰符使用，用于修饰它支持的程序元素。

5 个基本的 Annotation:
        @Overrid
        @Deprecated
        @SuppressWarnings
        @SafeVarargs            : Java 7 新增的
        @FunctionalInterface    ：Java 8 新增的
        
        
限定重写父类方法：@Overrid
---------------------------
@Overrid 就是用来指定方法覆盖的，它可以强制一个子类必须覆盖父类的方法。

例子：
public class Fruit
{
    public void info()
    {
        System.out.println("水果的info方法...");
    }
}
class Apple extends Fruit
{
    // 使用@Override指定下面方法必须重写父类方法
    @Override
    public void inf0()
    {
        System.out.println("苹果重写水果的info方法...");
    }
}

@Overrid 的作用是告诉编译器检查这个方法，保证父类要包含一个被该方法重写的方法，否则就会编译出错。
@Overrid 只能修饰方法，不能修饰其他程序元素。


标记已过时：@Deprecated
------------------------
@Deprecated 用于标识某个程序元素(类、方法)已过时，当其他程序使用已过时的类、方法时，编译器将会给出警告。
例子：
class Apple
{
    // 定义info方法已过时
    @Deprecated
    public void info()
    {
        System.out.println("Apple的info方法");
    }
}
public class DeprecatedTest
{
    public static void main(String[] args)
    {
        // 下面使用info方法时将会被编译器警告
        new Apple().info();
    }
}

@Deprecated 的作用与文档注释中的 @deprecated 标记的作用基本相同，但它们的用法不同，前者是 JDK 5 才支持的注解，无须放在文档注释语法 （/** ... */部分 ）中，而是直接用于修饰程序中的程序单元，如方法、类、接口等。


抑制编译器警告： @SuppressWarnings
-----------------------------------
@SuppressWarnings 指示被该 Annotation 修饰的程序元素（以及该程序元素中的所有子元素）取消显示指定的编译器警告。
@SuppressWarnings 会一直作用于该程序元素的所有子元素。例如，使用 @SuppressWarnings 修饰某个类取消显示某个编译器警告，同时又修饰该类里的某个方法取消另一个编译器警告，那么该方法将会同时取消显示这两个编一起去警告。

通常情况下，如果程序中使用没有泛型限制的集合会引起编译器警告，为了避免这种编译器警告，可以使用 @SuppressWarnings 修饰。
例子：

// 关闭整个类里的编译器警告
@SuppressWarnings(value="unchecked")
public class SuppressWarningsTest
{
    public static void main(String[] args)
    {
        List<String> myList = new ArrayList();     // ①
    }
}

当使用 @SuppressWarnings Annotation 来关闭编译器警告时，一定要在括号里使用 name=value 的形式为该 Annotation 的成员变量设置值。



Java 7 的“堆污染”警告与 @SafeVarargs
--------------------------------------
如下代码可能导致运行时异常

List list = new ArrayList<Integer>();
list.Add(20); //添加元素时引发 unchecked 异常

// 下面的代码引起 “未经检查的转换” 的警告。编译、运行时完全正常
List<String> ls = list;  ①
// 但只要访问ls 里的元素，如下面代码就会引起运行时异常
System.out.println(ls.get(0));
Java 把引发这种错误的原因称为“堆污染” (Heap pollution)，当把一个不带泛型的对象赋给一个带泛型的变量时，往往就会发生这种“堆污染”，如 ① 代码所示。

对于形参数可变的方法，该形参的类型又是泛型，这将更容易导致“堆污染”，例如：

public class ErrorUtils
{
    @SafeVarargs
    public static void faultyMethod(List<String>... listStrArray)
    {
        // Java语言不允许创建泛型数组，因此listArray只能被当成List[]处理
        // 此时相当于把List<String>赋给了List，已经发生了“擦除”
        List[] listArray = listStrArray;
        List<Integer> myList = new ArrayList<Integer>();
        myList.add(new Random().nextInt(100));
        // 把listArray的第一个元素赋为myList
        listArray[0] = myList;
        String s = listStrArray[0].get(0);
    }
}
由于该方法有个形参 List<String>...类型，个数可变的形参相当于数组，但Java又不支持泛型数组，因此程序只能把 List<String>...当成 List[]处理，这里就发生了“堆污染”。
Java 7 会在定义该方法时就发出“堆污染”警告，这样保证开发者更早地注意到程序可能存在的漏洞。
但在有些时候，开发者不希望看到这个警告，则可以用如下三种方式来抑制警告：
    1.使用 @SafeVarargs 修饰引发该警告的方法或构造器
    2.使用 @SuppressWarnings("unchecked")修饰。
    3.编译时使用 -Xlint:varargs 选项
弟三种方式比较少用，通常可以选择第一种或第二种方式，尤其是使用 @SafeVarargs 修饰引发警告的方法或构造器。


Java 8 的函数式接口与 @FunctionalInterface
-------------------------------------------
Java 8 规定：如果接口中只有一个抽象方法（可以包含多个默认方法或多个 static 方法），该接口就是函数式接口。
@FunctionalInterface 就是用来指定某个接口必须是函数式接口。

@FunctionalInterface
public interface FunInterface
{
    static void foo()
    {
        System.out.println("foo类方法");
    }
    default void bar()
    {
        System.out.println("bar默认方法");
    }
    void test(); // 只定义一个抽象方法

//    void abc();
}
编译上面的程序，可能丝毫看不出程序中 @FunctionalInterface 有任何作用， @FunctionalInterface 只是告诉编译器检查这个接口，保证该接口只能包含一个抽象方法，否则就会编译出错。

@FunctionalInterface 主要是帮助程序员避免一些低级错误，例如，在 FunInterface 接口中再增加一个抽象方法 abc(),编译程序时将出现错误。

@FunctionalInterface 只能修饰接口，不能修饰其他程序元素。

*
*
*

2 JDK 的元 Annotation
----------------------------------------------------------------------------------------
java.lang.annotation 下的6个 Meta Annotation (元 Annotation)


使用 @Retention
----------------------------
@Retention 只能用于修饰 Annotation 定义，用于指定被修饰的 Annotation 可以保留多长时间，@Retention 包含一个 RetentionPolicy 类型的 value 成员变量，所以使用@Retention 时必须为该 value 成员变量指定值。

value 成员变量的值只能是如下三个：
    RetentionPolicy.CLASS:    编译器将把 Annotation 记录在 class 文件中。当运行 Java 程序时， JVM 不可获取 Annotation 信息，这是默认值。
    RetentionPolicy.RUNTIME:编译器将把 Annotation 记录在 class 文件中。当运行 Java 程序时， JVM 也可获取 Annotation 信息，程序可以通过反射获取该 Annotation 信息。
    RetentionPolicy.SOURCE: Annotation 只保留在源代码中，编译器直接丢弃这种 Annotation。

    // 定义下面的 Testable Annotation 保留到运行时
    @Retention(value=RetentionPolicy.RUNTIME)
    public @interface Testable{}
    
    //定义下面的 Testable Annotation 将被编译器直接丢弃
    @Retention(RetentionPolicy.SOURCE)
    public @interface Testable{}
    
上面代码中使用 @Retention 元 Annotation 时，并未通过 value=RetentionPolicy.SOURCE 的方式来为该成员变量指定值，这是因为但 Annotation 的成员变量名为 value 时，程序中可以直接在 Annotation 后的括号里指定该成员变量的值，无须指定 name=value 的形式。

如果使用注解时只需要为 value 成员变量指定值，则使用该注解时可以直接在该注解后的括号里指定 value 成员变量的值，无须使用 "name=变量值" 的形式。    
    

使用 @Target
------------------
@Target 也只能修饰一个 Annotation 定义，它用于指定被修饰的 Annotation 能用于修饰哪些程序单元。
@Target 元 Annotation 也包含一个名为 value 的成员变量，该成员变量的值只能是如下几个：
    ElementType.ANNOTATION_TYPE: 指定该策略的 Annotation 只能修饰 Annotation
    ElementType.CONSTRUCTOR: 指定该策略的 Annotation 只能修饰构造器
    ElementType.FIELD: 指定该策略的 Annotation 只能修饰成员变量
    ElementType.LOCAL_VARIABLE: 指定该策略的 Annotation 只能修饰局部变量
    ElementType.METHOD: 指定该策略的 Annotation 只能修饰方法
    ElementType.PACKAGE: 指定该策略的 Annotation 只能修饰 包定义
    ElementType.PARAMETER: 指定该策略的 Annotation 可以修饰参数
    ElementType.TYPE: 指定该策略的 Annotation 可以修饰类、接口 （包括注解类型）或枚举定义
例子：
    //@ActionListenerFor Annotation 只能修饰成员变量
    @Target(ElementType.FIELD)
    public @interface ActionListenerFor{}
    
    // @Testable Annotation 只能修饰方法
    @Target(ElementType.METHOD)
    public @interface Testable{}
    
    
使用 @Documented
----------------------------------------
@Documented 用于指定被该元 Annotation 修饰的 Annotation 类将被 javadoc 工具提取成文档
如果定义 Annotation 类时使用了 @Documented 修饰，则所有使用该 Annotation 修饰的程序元素的 API 文档中将会包含该 Annotation 的说明

下面定义了一个 Tesble Annotation, 程序使用 @Documented 来修饰 @Testable Annotation 定义，所以该 Annotation 将被 javadoc 工具提取。

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
// 定义Testable Annotation将被javadoc工具提取
@Documented
public @interface Testable
{
}

上面代码中指定了 javadoc 工具生成的 API 文档将提取 @Testable 的使用信息。
下面代码定义了一个 MyTest 类，该类中的 info() 方法使用了 @Testable 修饰

public class MyTest
{
    // 使用@Test修饰info方法
    @Testable
    public void info()
    {
        System.out.println("info方法...");
    }
}


使用 @Inherited
--------------------------------------
@Inherited 元 Annotation 指定被它修饰的 Annotation 将具有继承性-----如果某个类使用了 @Xxx注解修饰（定义该 Annotation 时使用了 @inherited 修饰），则其子类将自动被 @Xxx 修饰

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Inheritable
{
}
上面代码表明 @Inheritable 具有继承性， 如果某个类使用了 @Inheritable 修饰，则该类的子类将自动使用 @Inheritable 修饰

// 使用@Inheritable修饰的Base类
@Inheritable
class Base
{
}
// TestInheritable类只是继承了Base类，
// 并未直接使用@Inheritable Annotiation修饰
public class InheritableTest extends Base
{
    public static void main(String[] args)
    {
        // 打印TestInheritable类是否具有@Inheritable修饰
        System.out.println(InheritableTest.class
            .isAnnotationPresent(Inheritable.class)); //输出： true
    }
}

*
*
*

3 自定义 Annotation
---------------------------------------------------------------------------------------------
定义新的 Annotation 类型使用 @interface 关键字 （在原有 interface 关键字前增加 @ 符号）
例子：
    //定义一个简单的 Annotation 类型
    public @interface Test
    {
    }
定义了新的 Annotation 之后，就可以在程序的任何地方使用该 Annotation, 通常会把 Annotation 放在所有修饰符之前，而且由于使用 Annotation 时可能还需要为成员变量指定值，因而 Annotation 的长度可能较长，所以通常把 Annotation 单独另放一行。

//使用 @Test 修饰类定义
@Test
public class MyClass
{
    ...
}
默认情况下， Annotation 可以用于修饰任何程序元素。

Annotation 不仅可以是这种简单的 Annotation, 还可以带成员变量， Annotation 的成员变量在 Annotation 定义中以无形参的方法形式声明，其方法名和返回值定义了该成员变量的名称和类型
例子：
public @interface MyTag
{
    // 定义带两个成员变量的 Annotation
    // Annotation 中的成员变量以方法的形式定义
    String name();
    int age();
}
上面定义 Annotation 的代码与定义接口的语法非常类似，只是使用 @interface 关键字来定义，而接口使用 interface 定义。

一旦在 Annotation 里定义了成员变量之后，使用该 Annotation 时就应该为该 Annotation 的成员变量指定值
public class Test
{
    //使用带成员变量的 Annotation 时，需要为成员变量赋值
    @MyTag(name="xx", age=6)
    public void info()
    {
    }
}

也可以在定义 Annotation 的成员变量时为其指定初始值（默认值），指定成员变量的初始值使用 default 关键字。
public @interface MyTag
{
    //定义了两个成员变量的 Annotation
    //使用 default 为两个成员变量指定初始值
    String name() default "yeeku" ;
    int age() default 32;
}

如果为 Annotation 的成员变量指定了默认值，使用该 Annotation 时则可以不为这些成员变量指定值，而是直接使用默认值
例子：
public class Test
{
    //使用带成员变量的 Annotation, 因为它的成员变量有默认值，所以可以不为它的成员变量指定值
    @MyTag
    public void info()
    {
    }
}

当然也可以在使用 MyTag Annotation 时为成员变量指定值，默认值不会起作用。

根据 Annotation 是否可以包含成员变量，可以把 Annotation 分为如下两类：
    标记 Annotation: 没有定义成员变量的 Annotation 类型被称为标记。这种 Annotation 仅利用自身的存在与否来提供信息，如 @Overrid, @Test 等 Annotation
    元数据 Annotation: 包含成员变量的 Annotation, 因为它们可以接受更多的元数据，所以被称为元数据 Annotation
    
    
提取 Annotation 信息
------------------------------------------------
使用 Annotation 修饰了类、方法、成员变量等成员之后，这些 Annotation 不会自己生效，必须由开发者提供相应的工具来提取并处理 Annotation 信息
Java 使用 java.lang.annotation.Annotation 接口来代表程序元素前面的注解，该接口是所有注解的父接口。
Java 5 在 java.lang.reflect 包下新增 AnnotatedElement 接口，该接口代表程序中可以接受注解的程序元素，有如下几个实现类：
    Class: 类定义
    Constructor: 构造器定义
    Field: 类的成员变量定义
    Method: 类的方法定义
    Package: 包定义
    
java.lang.reflect 包所提供的反射 API 增加了读取运行时 Annotation 的能力。
只有在定义 Annotation 是使用了 @Retention(RetentionPolicy.RUNTIME) 修饰，该 Annotation 才会在运行时可见， JVM 才会在装载 *.class 文件时读取保存在 class 文件中的 Annotation.

AnnotatedElement接口是所有程序元素的父接口，所以程序通过反射获取了某个类的 AnnotatedElement 对象 (如 Class, Method, Constructor 等）之后，程序就可以调用该对象的 AnnotatedElement 接口方法来访问 Annotation 信息。
// 获取 Test 类的 info方法的所有注解
Annotation[] aArray = Class.forName("Test").getMethod("info",null).getAnnotations();
// 遍历所有注解
for( Annotation an : aArray)
{
    System.out.println(an);
}

如果需要获取某个注解里的元数据，则可以将注解强制类型转换成所需的注解类型，然后通过注解对象的抽象方法来访问这些元数据。

例子：
    //获取 tt 对象的 info 方法所包含的所有注解
    Annotation[] annotation = Class.forName("Test").getMethod("info",null).getAnnotations();
    //遍历每个注解对象
    for (Annotation tag : annotation)
    {
        //如果 tag 注解是 MyTag1 类型
        if ( tag instanceof MyTag1)
        {
            System.out.println("Tag is: " + tag);
            //将 tag 强制类型转换为 MyTag1
            //输出 tag 对象的name 和 age 两个成员变量的值
            System.out.println("tag.name(): " + ((MyTag1)tag).name());
            System.out.println("tag.age(): " + ((MyTag1)tag).age());
        }
        //如果 tag 注解是 MyTag2 类型
        if ( tag instanceof MyTag2)
        {
            System.out.println("Tag is: " + tag);
            //将 tag 强制类型转换为 MyTag2
            //输出 tag 对象的name 和 age 两个成员变量的值
            System.out.println("tag.name(): " + ((MyTag2)tag).name());
            System.out.println("tag.age(): " + ((MyTag2)tag).age());
        }
    }


Java 8 新增的重复注解
---------------------------------------------------------------------------
Java 8 之前，同一个程序元素前最多只能使用一个相同类型的 Annotation; 如果需要在同一个元素前使用相同类型的 Annotation, 则必须使用 Annotation “容器”
Java 8 之前只能这样写：

@Results({@Result(name="failure", location="failed.jsp"),
@Result(name="success", location="succ/jsp")})
public Action FooAction{...}

实质是，@Results注解只包含一个名字为 value， 类型为 Result[] 的成员变量，程序指定的多个 @Result将作为 @Results 的value属性（数组类型）的数组元素。

Java 8 开始，传统的语法得到简化。

开发重复注解需要使用 @Repeatable 修饰

// 指定该注解信息会保留到运行时
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Repeatable(FkTags.class)
public @interface FkTag
{
    // 为该注解定义2个成员变量
    String name() default "疯狂软件";
    int age();
}

使用 @Repeatable 时必须为value成员变量指定值，该成员变量的值应该是一个“容器”注解----该“容器”注解可以包含多个 @FkTag, 因此还需要定义如下的"容器"注解

// 指定该注解信息会保留到运行时
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface FkTags
{
    // 定义value成员变量，该成员变量可接受多个@FkTag注解
    FkTag[] value();
}

注意：“容器”注解的保留期必须和它所包含的注解的保留期相同或更长，否则编译器报错

@FkTag(age=5)
@FkTag(name="疯狂Java" , age=9)
//@FkTags({@FkTag(age=5),
//    @FkTag(name="疯狂Java" , age=9)})
public class FkTagTest
{
    public static void main(String[] args)
    {
        Class<FkTagTest> clazz = FkTagTest.class;
        /* 使用Java 8新增的getDeclaredAnnotationsByType()方法获取
            修饰FkTagTest类的多个@FkTag注解 */
        FkTag[] tags = clazz.getDeclaredAnnotationsByType(FkTag.class);
        // 遍历修饰FkTagTest类的多个@FkTag注解
        for(FkTag tag : tags)
        {
            System.out.println(tag.name() + "-->" + tag.age());
        }
        /* 使用传统的getDeclaredAnnotation()方法获取
            修饰FkTagTest类的@FkTags注解 */
        FkTags container = clazz.getDeclaredAnnotation(FkTags.class);
        System.out.println(container);
    }
}

重复注解只是一种简化写法，这种简化写法是一种假象：多个重复注解其实会被作为“容器”注解的value成员变量的数组元素



Java 8 新增的 Type Annotation
------------------------------------------
Java 8 为 ElementType 枚举增加了 TYPE_PARAMTER, TYPE_USE 两个枚举值，这样就允许定义枚举时使用 @Target(ElementType.TYPE_USE) 修饰，这种注解被称为 Type Annotation (类型注解)
Type Annotation 可用在任何用到类型的地方