Java Annotation手冊（轉）

原作:cleverpig(作者的Blog:http://blog.matrix.org.cn/page/cleverpig)
原文:http://www.matrix.org.cn/resource/article/44/44055_Java+Annotation+Reflect.html
關鍵字:java,annotation,reflect

前言：
在上篇文章《Java Annotation入門》中概要性的介紹了Annotation的定義、使用，範圍涵蓋較廣，但是深度不夠。所以作者在《Java Annotation入門》後，繼續整理了Annotation的概念和知識點，與喜歡research的朋友們共享。

閱讀提示：文中提到的程序成員或者程序元素是一個概念，指組成程序代碼的單元：如類、方法、成員變量。

一、Annotation究竟是什麼？

Annotation提供了一條與程序元素關聯任何信息或者任何元數據（metadata）的途徑。從某些方面看，annotation就像修飾符一樣被使用，並應用於包、類型、構造方法、方法、成員變量、參數、本地變量的聲明中。這些信息被存儲在annotation的“name=value”結構對中。annotation類型是一種接口，能夠通過java反射API的方式提供對其信息的訪問。

annotation能被用來爲某個程序元素（類、方法、成員變量等）關聯任何的信息。需要注意的是，這裏存在着一個基本的潛規則：annotaion不能影響程序代碼的執行，無論增加、刪除annotation，代碼都始終如一的執行。另外，儘管一些annotation通過java的反射api方法在運行時被訪問，而java語言解釋器在工作時忽略了這些annotation。正是由於java虛擬機忽略了annotation，導致了annotation類型在代碼中是“不起作用”的；只有通過某種配套的工具纔會對annotation類型中的信息進行訪問和處理。本文中將涵蓋標準的annotation和meta-annotation類型，陪伴這些annotation類型的工具是java編譯器（當然要以某種特殊的方式處理它們）。

由於上述原因，annotation在使用時十分簡便。一個本地變量可以被一個以NonNull命名的annotation類型所標註，來作爲對這個本地變量不能被賦予null值的斷言。而我們可以編寫與之配套的一個annotation代碼分析工具，使用它來對具有前面變量的代碼進行解析，並且嘗試驗證這個斷言。當然這些代碼並不必自己編寫。在JDK安裝後，在JDK/bin目錄中可以找到名爲“apt”的工具，它提供了處理annotation的框架：它啓動後掃描源代碼中的annotation，並調用我們定義好的annotation處理器完成我們所要完成的工作（比如驗證前面例子中的斷言）。說到這裏，annotation的強大功能似乎可以替代XDoclet這類的工具了，隨着我們的深入，大家會更加堅信這一點。
注：詳細描述請參看jsr250規範：
http://www.jcp.org/aboutJava/communityprocess/pfd/jsr250/

二、Annotation的定義：

這段文字開始介紹annotation相關技術。在此大家將看到java5.0的標準annotation類型，這種標準類型就是前文中所說的“內建”類型，它們可以直接被javac支持。可喜的是，在java6.0beta版中的javac已經加入了對自定義annotation的支持。

1。Annotation的概念和語法：

首先，關鍵的概念是理解annotation是與一個程序元素相關聯信息或者元數據的標註。它從不影響java程序的執行，但是對例如編譯器警告或者像文檔生成器等輔助工具產生影響。

下面是常用的annotation列表，我們應該注意在annotation和annotation類型之間的不同：

A.annotation：
annotation使用了在java5.0所帶來的新語法，它的行爲十分類似public、final這樣的修飾符。每個annotation具有一個名字和成員個數>=0。每個annotation的成員具有被稱爲name=value對的名字和值（就像javabean一樣），name=value裝載了annotation的信息。

B.annotation類型：
annotation類型定義了annotation的名字、類型、成員默認值。一個annotation類型可以說是一個特殊的java接口，它的成員變量是受限制的，而聲明annotation類型時需要使用新語法。當我們通過java反射api訪問annotation時，返回值將是一個實現了該annotation類型接口的對象，通過訪問這個對象我們能方便的訪問到其annotation成員。後面的章節將提到在java5.0的java.lang包裏包含的3個標準annotation類型。

C.annotation成員：
annotation的成員在annotation類型中以無參數的方法的形式被聲明。其方法名和返回值定義了該成員的名字和類型。在此有一個特定的默認語法：允許聲明任何annotation成員的默認值：一個annotation可以將name=value對作爲沒有定義默認值的annotation成員的值，當然也可以使用name=value對來覆蓋其它成員默認值。這一點有些近似類的繼承特性，父類的構造函數可以作爲子類的默認構造函數，但是也可以被子類覆蓋。

D.marker annotation類型：
一個沒有成員定義的annotation類型被稱爲marker annotation。這種annotation類型僅使用自身的存在與否來爲我們提供信息。如後面要說的Override。

E.meta-annotation：
meta-annotation也稱爲元annotation，它是被用來聲明annotation類型的annotation。Java5.0提供了一些標準的元-annotation類型。下面介紹的target、retention就是meta-annotation。

F.target：
annotation的target是一個被標註的程序元素。target說明了annotation所修飾的對象範圍：annotation可被用於packages、types（類、接口、枚舉、annotation類型）、類型成員（方法、構造方法、成員變量、枚舉值）、方法參數和本地變量（如循環變量、catch參數）。在annotation類型的聲明中使用了target可更加明晰其修飾的目標。

G.retention：
annotation的retention定義了該annotation被保留的時間長短：某些annotation僅出現在源代碼中，而被編譯器丟棄；而另一些卻被編譯在class文件中；編譯在class文件中的annotation可能會被虛擬機忽略，而另一些在class被裝載時將被讀取（請注意並不影響class的執行，因爲annotation與class在使用上是被分離的）。使用這個meta-annotation可以對annotation的“生命週期”限制。

H.metadata：
由於metadata被廣泛使用於各種計算機開發過程中，所以當我們在這裏談論的metadata即元數據通常指被annotation裝載的信息或者annotation本身。

2。使用標準Annotation：
java5.0在java.lang包中定義了3種標準的annotation類型：

A.Override：
java.lang.Override是一個marker annotation類型，它被用作標註方法。它說明了被標註的方法重載了父類的方法，起到了斷言的作用。如果我們使用了這種annotation在一個沒有覆蓋父類方法的方法時，java編譯器將以一個編譯錯誤來警示。
這個annotaton常常在我們試圖覆蓋父類方法而確又寫錯了方法名時發揮威力。

使用方法極其簡單：在使用此annotation時只要在被修飾的方法前面加上@Override。
下面的代碼是一個使用@Override修飾一個企圖重載父類的toString方法，而又存在拼寫錯誤的sample：
清單1：

@Overridepublic String toSting() { // 注意方法名拼寫錯了 return "[" + super.toString() + "]";}


B.Deprecated：
同樣Deprecated也是一個marker annotation。當一個類型或者類型成員使用@Deprecated修飾的話，編譯器將不鼓勵使用這個被標註的程序元素。而且這種修飾具有一定的“延續性”：如果我們在代碼中通過繼承或者覆蓋的方式使用了這個過時的類型或者成員，雖然繼承或者覆蓋後的類型或者成員並不是被聲明爲@Deprecated，但編譯器仍然要報警。
值得注意，@Deprecated這個annotation類型和javadoc中的@deprecated這個tag是有區別的：前者是java編譯器識別的，而後者是被javadoc工具所識別用來生成文檔（包含程序成員爲什麼已經過時、它應當如何被禁止或者替代的描述）。
在java5.0，java編譯器仍然象其從前版本那樣尋找@deprecated這個javadoc tag，並使用它們產生警告信息。但是這種狀況將在後續版本中改變，我們應在現在就開始使用@Deprecated來修飾過時的方法而不是@deprecated javadoc tag。
清單2：

下面是一段使用@Deprecated的代碼：/** * 這裏是javadoc的@deprecated聲明. * @deprecated No one has players for this format any more. Use VHS instead. */@Deprecated public class Betamax { ... }


C.SuppressWarnings：
@SuppressWarnings被用於有選擇的關閉編譯器對類、方法、成員變量、變量初始化的警告。在java5.0，sun提供的javac編譯器爲我們提供了-Xlint選項來使編譯器對合法的程序代碼提出警告，此種警告從某種程度上代表了程序錯誤。例如當我們使用一個generic collection類而又沒有提供它的類型時，編譯器將提示出"unchecked warning"的警告。

通常當這種情況發生時，我們就需要查找引起警告的代碼。如果它真的表示錯誤，我們就需要糾正它。例如如果警告信息表明我們代碼中的switch語句沒有覆蓋所有可能的case，那麼我們就應增加一個默認的case來避免這種警告。
相仿，有時我們無法避免這種警告，例如，我們使用必須和非generic的舊代碼交互的generic collection類時，我們不能避免這個unchecked warning。此時@SuppressWarning就要派上用場了，在調用的方法前增加@SuppressWarnings修飾，告訴編譯器停止對此方法的警告。
SuppressWarning不是一個marker annotation。它有一個類型爲String[]的成員，這個成員的值爲被禁止的警告名。對於javac編譯器來講，被-Xlint選項有效的警告名也同樣對@SuppressWarings有效，同時編譯器忽略掉無法識別的警告名。

annotation語法允許在annotation名後跟括號，括號中是使用逗號分割的name=value對用於爲annotation的成員賦值：
清單3：

@SuppressWarnings(value={"unchecked","fallthrough"})public void lintTrap() { /* sloppy method body omitted */ }


在這個例子中SuppressWarnings annotation類型只定義了一個單一的成員，所以只有一個簡單的value={...}作爲name=value對。又由於成員值是一個數組，故使用大括號來聲明數組值。

注意：我們可以在下面的情況中縮寫annotation：當annotation只有單一成員，併成員命名爲"value="。這時可以省去"value="。比如將上面的SuppressWarnings annotation進行縮寫：
清單4：

@SuppressWarnings({"unchecked","fallthrough"})

如果SuppressWarnings所聲明的被禁止警告個數爲一個時，可以省去大括號：

@SuppressWarnings("unchecked")


3。Annotation語法：

在上一個章節中，我們看到書寫marker annotation和單一成員annotation的語法。下面本人來介紹一下完整的語法：

annotation由“@+annotation類型名稱+(..逗號分割的name-value對...)”組成。其中成員可以按照任何的順序。如果annotation類型定義了某個成員的默認值，則這個成員可以被省略。成員值必須爲編譯時常量、內嵌的annotation或者數組。

下面我們將定義一個annotation類型名爲Reviews，它有一個由@Review annotation數組構成的成員。這個@Review annotation類型有三個成員："reviewer"是一個字符串，"comment" 是一個具有默認值的可選的字符串，"grade"是一個Review.Grade枚舉類型值。
清單5：

@Reviews({ // Single-value annotation, so "value=" is omitted here @Review(grade=Review.Grade.EXCELLENT, reviewer="df"), @Review(grade=Review.Grade.UNSATISFACTORY, reviewer="eg", comment="This method needs an @Override annotation")})

annotation語法的另一個重要規則是沒有程序成員可以有多於一個的同一annotation實例。例如在一個類中簡單的放置多個@Review annotation。這也是在上面代碼中定義@Reviews annotation類型數組的原因。

4。Annotation成員類型和值：

annotation成員必須是非空的編譯時常量表達式。可用的成員類型爲：primitive類型、, String, Class, enumerated類型, annotation類型, 和前面類型的數組。

下面我們定義了一個名爲UncheckedExceptions 的annotation類型，它的成員是一個擴展了RuntimeException類的類數組。
清單6：

@UncheckedExceptions({ IllegalArgumentException.class, StringIndexOutOfBoundsException.class})


5。Annotation的目標：

annotation通常被放在類型定義和成員定義的前面。然而它也出現在package、方法參數、本地變量的前面。下面，我們來討論一下這些不大常用的寫法：

package annotation出現在package聲明的前面。
下面的例子package-info.java中不包含任何的公共類型定義，卻包含一個可選的javadoc註釋。
清單7：

/** * This package holds my custom annotation types. */@com.davidflanagan.annotations.Author("David Flanagan")package com.davidflanagan.annotations;

當package-info.java文件被編譯時，它將產生名爲包含annotation（特殊的接口）聲明的package-info.class的類。這個接口沒有成員，它的名字package-info不是一個合法的java標識，所以它不能用在java源代碼中。這個接口的存在只是簡單的被看作一個爲package annotation準備的佔位符。

用於修飾方法參數、catch參數、本地變量的annotation只是簡單的出現在這些程序成員的修飾符位置。java類文件格式沒有爲本地變量或者catch參數存儲annotation作準備，所以這些annotation總是保留在源代碼級別（source retention）；方法參數annotation能夠保存在類文件中，也可以在保留到運行時。

最後，請注意，枚舉類型定義中不允許任何的修飾符修飾其枚舉值。

6。Annotation和默認值：
在Annotation中，沒有默認值的成員必須有一個成員值。而如何理解默認值是如何被處理就是一個很重要的細節：annotation類型所定義的成員默認值被存儲在class文件中，不被編譯到annotation裏面。如果我們修改一個annotation類型使其成員的默認值發生了改變，這個改變對於所有此類型的annotation中沒有明確提供成員值的成員產生影響（即修改了該成員的成員值）。即使在annotation類型使其成員的默認值被改變後annotation從沒被重新編譯過，該類型的annotation(改變前已經被編譯的)也受到影響。

三、Annotation工作原理：

Annotation與反射
在java5.0中Java.lang.reflect提供的反射API被擴充了讀取運行時annotation的能力。讓我們回顧一下前面所講的：一個annotation類型被定義爲runtime retention後，它纔是在運行時可見，當class文件被裝載時被保存在class文件中的annotation纔會被虛擬機讀取。那麼reflect是如何幫助我們訪問class中的annotation呢？

下文將在java.lang.reflect用於annotation的新特性，其中java.lang.reflect.AnnotatedElement是重要的接口，它代表了提供查詢annotation能力的程序成員。這個接口被java.lang.Package、java.lang.Class實現，並間接地被Method類、Constructor類、java.lang.reflect的Field類實現。而annotation中的方法參數可以通過Method類、Constructor類的getParameterAnnotations()方法獲得。

下面的代碼使用了AnnotatedElement類的isAnnotationPresent()方法判斷某個方法是否具有@Unstable annotation，從而斷言此方法是否穩定：
清單8：

import java.lang.reflect.*;Class c = WhizzBangClass.class; Method m = c.getMethod("whizzy", int.class, int.class); boolean unstable = m.isAnnotationPresent(Unstable.class);

isAnnotationPresent()方法對於檢查marker annotation是十分有用的，因爲marker annotation沒有成員變量，所以我們只要知道class的方法是否使用了annotation修飾就可以了。而當處理具有成員的annotation時，我們通過使用getAnnotation()方法來獲得annotation的成員信息（成員名稱、成員值）。這裏我們看到了一套優美的java annotation系統：如果annotation存在，那麼實現了相應的annotation類型接口的對象將被getAnnotation()方法返回，接着調用定義在annotation類型中的成員方法可以方便地獲得任何成員值。

回想一下，前面介紹的@Reviews annotation，如果這個annotation類型被聲明爲runtime retention的話，我們通過下面的代碼來訪問@Reviews annotation的成員值：
清單9：

AnnotatedElement target = WhizzBangClass.class; //獲得被查詢的AnnotatedElement// 查詢AnnotatedElement的@Reviews annotation信息Reviews annotation = target.getAnnotation(Reviews.class);// 因爲@Reviews annotation類型的成員爲@Review annotation類型的數組，// 所以下面聲明瞭Review[] reviews保存@Reviews annotation類型的value成員值。Review[] reviews = annotation.value();// 查詢每個@Review annotation的成員信息for(Review r : reviews) { Review.Grade grade = r.grade(); String reviewer = r.reviewer(); String comment = r.comment(); System.out.printf("%s assigned a grade of %s and comment '%s'%n", reviewer, grade, comment);}


四、如何自定義Annotation？

1．詳解annotation與接口的異同：
因爲annotation類型是一個非凡的接口，所以兩者之間存在着某些差異：

A.Annotation類型使用關鍵字@interface而不是interface。
這個關鍵字聲明隱含了一個信息：它是繼承了java.lang.annotation.Annotation接口，並非聲明瞭一個interface。

B.Annotation類型、方法定義是獨特的、受限制的。
Annotation類型的方法必須聲明爲無參數、無異常拋出的。這些方法定義了annotation的成員：方法名成爲了成員名，而方法返回值成爲了成員的類型。而方法返回值類型必須爲primitive類型、Class類型、枚舉類型、annotation類型或者由前面類型之一作爲元素的一維數組。方法的後面可以使用default和一個默認數值來聲明成員的默認值，null不能作爲成員默認值，這與我們在非annotation類型中定義方法有很大不同。
Annotation類型和它的方法不能使用annotation類型的參數、成員不能是generic。只有返回值類型是Class的方法可以在annotation類型中使用generic，因爲此方法能夠用類轉換將各種類型轉換爲Class。

C.Annotation類型又與接口有着近似之處。
它們可以定義常量、靜態成員類型（比如枚舉類型定義）。Annotation類型也可以如接口一般被實現或者繼承。

2．實例：
下面，我們將看到如何定義annotation類型的example。它展示了annotation類型聲明以及@interface與interface之間的不同：
清單10：

package com.davidflanagan.annotations;import java.lang.annotation.*;/** * 使用annotation來描述那些被標註的成員是不穩定的，需要更改*/@Retention(RetentionPolicy.RUNTIME)public @interface Unstable {}


下面的另一個example只定義了一個成員。並通過將這個成員命名爲value，使我們可以方便的使用這種annotation的快捷聲明方式：
清單11：

/** * 使用Author這個annotation定義在程序中指出代碼的作者 */public @interface Author { /** 返回作者名 */ String value();}


以下的example更加複雜。Reviews annotation類型只有一個成員，但是這個成員的類型是複雜的：由Review annotation組成的數組。Review annotation類型有3個成員：枚舉類型成員grade、表示Review名稱的字符串類型成員Reviewer、具有默認值的字符串類型成員Comment。
清單12：

import java.lang.annotation.*; /** * Reviews annotation類型只有一個成員， * 但是這個成員的類型是複雜的：由Review annotation組成的數組 */@Retention(RetentionPolicy.RUNTIME)public @interface Reviews { Review[] value();}/*** Review annotation類型有3個成員： * 枚舉類型成員grade、 * 表示Review名稱的字符串類型成員Reviewer、 * 具有默認值的字符串類型成員Comment。 */public @interface Review { // 內嵌的枚舉類型 public static enum Grade { EXCELLENT, SATISFACTORY, UNSATISFACTORY }; // 下面的方法定義了annotation的成員 Grade grade(); String reviewer(); String comment() default ""; }


最後，我們來定義一個annotation方法用於羅列出類運行中所有的unchecked異常（上文已經提到這種情況不一定是錯誤）。這個annotation類型將一個數組作爲了唯一的成員。數組中的每個元素都是異常類。爲了加強對未檢查的異常（此類異常都是在運行時拋出）進行報告，我們可以在代碼中對異常的類型進行限制：
清單13：

public @interface UncheckedExceptions { Class<? extends RuntimeException>[] value();}


五、Meta-Annotation

Annotation類型可以被它們自己所標註。Java5.0定義了4個標準的meta-annotation類型，它們被用來提供對其它annotation類型作說明。這些類型和它們所支持的類在java.lang.annotation包中可以找到。如果需要更詳細的信息可以參考jdk5.0手冊。

1．再談Target
作爲meta-annotation類型的Target,它描述了annotation所修飾的程序成員的類型。當一個annotation類型沒有Target時，它將被作爲普通的annotation看待。當將它修飾一個特定的程序成員時，它將發揮其應用的作用，例如：Override用於修飾方法時，增加了@Target這個meta-annotation就使編譯器對annotation作檢查，從而去掉修飾錯誤類型的Override。

Target meta-annotation類型有唯一的value作爲成員。這個成員的類型是java.lang.annotation.ElementType[]類型的，ElementType類型是可以被標註的程序成員的枚舉類型。

2．Retention的用法
我們在文章的開頭曾經提到過Retention，但是沒有詳細講解。Retention描述了annotation是否被編譯器丟棄或者保留在class文件；如果保留在class文件中，是否在class文件被裝載時被虛擬機讀取。默認情況下，annotation被保存在class文件中，但在運行時並不能被反射訪問。Retention具有三個取值：source、class、runtime，這些取值來自java.lang.annotation.RetentionPolicy的枚舉類型值。

Retention meta-annotation類型有唯一的value作爲成員，它的取值來自java.lang.annotation.RetentionPolicy的枚舉類型值。

3．Documented
Documented是一個meta-annotation類型，用於描述其它類型的annotation應該被作爲被標註的程序成員的公共API，因此可以被例如javadoc此類的工具文檔化。

Documented是一個marker annotation，沒有成員。

4．Inherited
@Inherited meta-annotation也是一個marker annotation，它闡述了某個被標註的類型是被繼承的。如果一個使用了@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的概念和知識點，從annotation的定義、語法到工作原理、如何自定義annotation，直至meta-annotation。其中也具有一些配套的代碼片斷可參考，雖然不是很多，但是可謂言簡意賅、着其重點，本人認爲用好annotation的關鍵還在於使用。希望本手冊能夠幫助大家用好annotation，這也是本人的最大快樂。