Java Annotation手冊作者cleverpig可以自由轉載, 轉載請保留下面的作者信息:作者 cleverpig(http://blog.matrix.org.cn/page/cleverpig)前言：在上篇文章《Java Annotation入門(mén)》中概要性的介紹了Annotation的定義、使用，范圍涵蓋較廣，但是深度不夠。所以作者在《Java Annotation入門(mén)》后，繼續整理了Annotation的概念和知識點(diǎn)，與喜歡research的朋友們共享。
閱讀提示：文中提到的程序成員或者程序元素是一個(gè)概念，指組成程序代碼的單元：如類(lèi)、方法、成員變量。一、Annotation究竟是什么？Annotation提供了一條與程序元素關(guān)聯(lián)任何信息或者任何元數據（metadata）的途徑。從某些方面看，annotation就像修飾符一樣被使用，并應用于包、類(lèi)型、構造方法、方法、成員變量、參數、本地變量的聲明中。這些信息被存儲在annotation的“name=value”結構對中。annotation類(lèi)型是一種接口，能夠通過(guò)java反射API的方式提供對其信息的訪(fǎng)問(wèn)。
annotation能被用來(lái)為某個(gè)程序元素（類(lèi)、方法、成員變量等）關(guān)聯(lián)任何的信息。需要注意的是，這里存在著(zhù)一個(gè)基本的潛規則：annotaion不能影響程序代碼的執行，無(wú)論增加、刪除annotation，代碼都始終如一的執行。另外，盡管一些annotation通過(guò)java的反射api方法在運行時(shí)被訪(fǎng)問(wèn)，而java語(yǔ)言解釋器在工作時(shí)忽略了這些annotation。正是由于java虛擬機忽略了annotation，導致了annotation類(lèi)型在代碼中是“不起作用”的；只有通過(guò)某種配套的工具才會(huì )對annotation類(lèi)型中的信息進(jìn)行訪(fǎng)問(wèn)和處理。本文中將涵蓋標準的annotation和meta-annotation類(lèi)型，陪伴這些annotation類(lèi)型的工具是java編譯器（當然要以某種特殊的方式處理它們）。
由于上述原因，annotation在使用時(shí)十分簡(jiǎn)便。一個(gè)本地變量可以被一個(gè)以NonNull命名的annotation類(lèi)型所標注，來(lái)作為對這個(gè)本地變量不能被賦予null值的斷言。而我們可以編寫(xiě)與之配套的一個(gè)annotation代碼分析工具，使用它來(lái)對具有前面變量的代碼進(jìn)行解析，并且嘗試驗證這個(gè)斷言。當然這些代碼并不必自己編寫(xiě)。在JDK安裝后，在JDK/bin目錄中可以找到名為“apt”的工具，它提供了處理annotation的框架：它啟動(dòng)后掃描源代碼中的annotation，并調用我們定義好的annotation處理器完成我們所要完成的工作（比如驗證前面例子中的斷言）。說(shuō)到這里，annotation的強大功能似乎可以替代XDoclet這類(lèi)的工具了，隨著(zhù)我們的深入，大家會(huì )更加堅信這一點(diǎn)。
注：詳細描述請參看jsr250規范：
http://www.jcp.org/aboutJava/communityprocess/pfd/jsr250/二、Annotation的定義：這段文字開(kāi)始介紹annotation相關(guān)技術(shù)。在此大家將看到j(luò )ava5.0的標準annotation類(lèi)型，這種標準類(lèi)型就是前文中所說(shuō)的“內建”類(lèi)型，它們可以直接被javac支持?？上驳氖?，在java6.0beta版中的javac已經(jīng)加入了對自定義annotation的支持。
1。Annotation的概念和語(yǔ)法：首先，關(guān)鍵的概念是理解annotation是與一個(gè)程序元素相關(guān)聯(lián)信息或者元數據的標注。它從不影響java程序的執行，但是對例如編譯器警告或者像文檔生成器等輔助工具產(chǎn)生影響。
下面是常用的annotation列表，我們應該注意在annotation和annotation類(lèi)型之間的不同：
A.annotation：annotation使用了在java5.0所帶來(lái)的新語(yǔ)法，它的行為十分類(lèi)似public、final這樣的修飾符。每個(gè)annotation具有一個(gè)名字和成員個(gè)數>=0。每個(gè)annotation的成員具有被稱(chēng)為name=value對的名字和值（就像javabean一樣），name=value裝載了annotation的信息。
B.annotation類(lèi)型：annotation類(lèi)型定義了annotation的名字、類(lèi)型、成員默認值。一個(gè)annotation類(lèi)型可以說(shuō)是一個(gè)特殊的java接口，它的成員變量是受限制的，而聲明annotation類(lèi)型時(shí)需要使用新語(yǔ)法。當我們通過(guò)java反射api訪(fǎng)問(wèn)annotation時(shí)，返回值將是一個(gè)實(shí)現了該annotation類(lèi)型接口的對象，通過(guò)訪(fǎng)問(wèn)這個(gè)對象我們能方便的訪(fǎng)問(wèn)到其annotation成員。后面的章節將提到在java5.0的java.lang包里包含的3個(gè)標準annotation類(lèi)型。
C.annotation成員：annotation的成員在annotation類(lèi)型中以無(wú)參數的方法的形式被聲明。其方法名和返回值定義了該成員的名字和類(lèi)型。在此有一個(gè)特定的默認語(yǔ)法：允許聲明任何annotation成員的默認值：一個(gè)annotation可以將name=value對作為沒(méi)有定義默認值的annotation成員的值，當然也可以使用name=value對來(lái)覆蓋其它成員默認值。這一點(diǎn)有些近似類(lèi)的繼承特性，父類(lèi)的構造函數可以作為子類(lèi)的默認構造函數，但是也可以被子類(lèi)覆蓋。
D.marker annotation類(lèi)型：一個(gè)沒(méi)有成員定義的annotation類(lèi)型被稱(chēng)為marker annotation。這種annotation類(lèi)型僅使用自身的存在與否來(lái)為我們提供信息。如后面要說(shuō)的Override。
E.meta-annotation：meta-annotation也稱(chēng)為元annotation，它是被用來(lái)聲明annotation類(lèi)型的annotation。Java5.0提供了一些標準的元-annotation類(lèi)型。下面介紹的target、retention就是meta-annotation。
F.target：annotation的target是一個(gè)被標注的程序元素。target說(shuō)明了annotation所修飾的對象范圍：annotation可被用于packages、types（類(lèi)、接口、枚舉、annotation類(lèi)型）、類(lèi)型成員（方法、構造方法、成員變量、枚舉值）、方法參數和本地變量（如循環(huán)變量、catch參數）。在annotation類(lèi)型的聲明中使用了target可更加明晰其修飾的目標。
G.retention：annotation的retention定義了該annotation被保留的時(shí)間長(cháng)短：某些annotation僅出現在源代碼中，而被編譯器丟棄；而另一些卻被編譯在class文件中；編譯在class文件中的annotation可能會(huì )被虛擬機忽略，而另一些在class被裝載時(shí)將被讀?。ㄕ堊⒁獠⒉挥绊慶lass的執行，因為annotation與class在使用上是被分離的）。使用這個(gè)meta-annotation可以對annotation的“生命周期”限制。
H.metadata：由于metadata被廣泛使用于各種計算機開(kāi)發(fā)過(guò)程中，所以當我們在這里談?wù)摰膍etadata即元數據通常指被annotation裝載的信息或者annotation本身。
2。使用標準Annotation：java5.0在java.lang包中定義了3種標準的annotation類(lèi)型：
A.Override：java.lang.Override是一個(gè)marker annotation類(lèi)型，它被用作標注方法。它說(shuō)明了被標注的方法重載了父類(lèi)的方法，起到了斷言的作用。如果我們使用了這種annotation在一個(gè)沒(méi)有覆蓋父類(lèi)方法的方法時(shí)，java編譯器將以一個(gè)編譯錯誤來(lái)警示。
這個(gè)annotaton常常在我們試圖覆蓋父類(lèi)方法而確又寫(xiě)錯了方法名時(shí)發(fā)揮威力。
使用方法極其簡(jiǎn)單：在使用此annotation時(shí)只要在被修飾的方法前面加上@Override。
下面的代碼是一個(gè)使用@Override修飾一個(gè)企圖重載父類(lèi)的toString方法，而又存在拼寫(xiě)錯誤的sample：
@Override
public String toSting() { // 注意方法名拼寫(xiě)錯了
return "[" + super.toString() + "]";
}
B.Deprecated：同樣Deprecated也是一個(gè)marker annotation。當一個(gè)類(lèi)型或者類(lèi)型成員使用@Deprecated修飾的話(huà)，編譯器將不鼓勵使用這個(gè)被標注的程序元素。而且這種修飾具有一定的“延續性”：如果我們在代碼中通過(guò)繼承或者覆蓋的方式使用了這個(gè)過(guò)時(shí)的類(lèi)型或者成員，雖然繼承或者覆蓋后的類(lèi)型或者成員并不是被聲明為@Deprecated，但編譯器仍然要報警。
值得注意，@Deprecated這個(gè)annotation類(lèi)型和javadoc中的@deprecated這個(gè)tag是有區別的：前者是java編譯器識別的，而后者是被javadoc工具所識別用來(lái)生成文檔（包含程序成員為什么已經(jīng)過(guò)時(shí)、它應當如何被禁止或者替代的描述）。
在java5.0，java編譯器仍然象其從前版本那樣尋找@deprecated這個(gè)javadoc tag，并使用它們產(chǎn)生警告信息。但是這種狀況將在后續版本中改變，我們應在現在就開(kāi)始使用@Deprecated來(lái)修飾過(guò)時(shí)的方法而不是@deprecated javadoc tag。
下面是一段使用@Deprecated的代碼：
/**
* 這里是javadoc的@deprecated聲明.
* @deprecated No one has players for this format any more. Use VHS instead.
*/
@Deprecated public class Betamax { ... }
C.SuppressWarnings：@SuppressWarnings被用于有選擇的關(guān)閉編譯器對類(lèi)、方法、成員變量、變量初始化的警告。在java5.0，sun提供的javac編譯器為我們提供了-Xlint選項來(lái)使編譯器對合法的程序代碼提出警告，此種警告從某種程度上代表了程序錯誤。例如當我們使用一個(gè)generic collection類(lèi)而又沒(méi)有提供它的類(lèi)型時(shí)，編譯器將提示出"unchecked warning"的警告。
通常當這種情況發(fā)生時(shí)，我們就需要查找引起警告的代碼。如果它真的表示錯誤，我們就需要糾正它。例如如果警告信息表明我們代碼中的switch語(yǔ)句沒(méi)有覆蓋所有可能的case，那么我們就應增加一個(gè)默認的case來(lái)避免這種警告。
相仿，有時(shí)我們無(wú)法避免這種警告，例如，我們使用必須和非generic的舊代碼交互的generic collection類(lèi)時(shí)，我們不能避免這個(gè)unchecked warning。此時(shí)@SuppressWarning就要派上用場(chǎng)了，在調用的方法前增加@SuppressWarnings修飾，告訴編譯器停止對此方法的警告。
SuppressWarning不是一個(gè)marker annotation。它有一個(gè)類(lèi)型為String[]的成員，這個(gè)成員的值為被禁止的警告名。對于javac編譯器來(lái)講，被-Xlint選項有效的警告名也同樣對@SuppressWarings有效，同時(shí)編譯器忽略掉無(wú)法識別的警告名。
annotation語(yǔ)法允許在annotation名后跟括號，括號中是使用逗號分割的name=value對用于為annotation的成員賦值：
@SuppressWarnings(value={"unchecked","fallthrough"})
public void lintTrap() { /* sloppy method body omitted */ }
在這個(gè)例子中SuppressWarnings annotation類(lèi)型只定義了一個(gè)單一的成員，所以只有一個(gè)簡(jiǎn)單的value={...}作為name=value對。又由于成員值是一個(gè)數組，故使用大括號來(lái)聲明數組值。
注意：我們可以在下面的情況中縮寫(xiě)annotation：當annotation只有單一成員，并成員命名為"value="。這時(shí)可以省去"value="。比如將上面的SuppressWarnings annotation進(jìn)行縮寫(xiě)：
@SuppressWarnings({"unchecked","fallthrough"})
如果SuppressWarnings所聲明的被禁止警告個(gè)數為一個(gè)時(shí)，可以省去大括號：
@SuppressWarnings("unchecked")
3。Annotation語(yǔ)法：在上一個(gè)章節中，我們看到書(shū)寫(xiě)marker annotation和單一成員annotation的語(yǔ)法。下面本人來(lái)介紹一下完整的語(yǔ)法：
annotation由“@+annotation類(lèi)型名稱(chēng)+(..逗號分割的name-value對...)”組成。其中成員可以按照任何的順序。如果annotation類(lèi)型定義了某個(gè)成員的默認值，則這個(gè)成員可以被省略。成員值必須為編譯時(shí)常量、內嵌的annotation或者數組。
下面我們將定義一個(gè)annotation類(lèi)型名為Reviews，它有一個(gè)由@Review annotation數組構成的成員。這個(gè)@Review annotation類(lèi)型有三個(gè)成員："reviewer"是一個(gè)字符串，"comment" 是一個(gè)具有默認值的可選的字符串，"grade"是一個(gè)Review.Grade枚舉類(lèi)型值。
@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語(yǔ)法的另一個(gè)重要規則是沒(méi)有程序成員可以有多于一個(gè)的同一annotation實(shí)例。例如在一個(gè)類(lèi)中簡(jiǎn)單的放置多個(gè)@Review annotation。這也是在上面代碼中定義@Reviews annotation類(lèi)型數組的原因。
4。Annotation成員類(lèi)型和值：annotation成員必須是非空的編譯時(shí)常量表達式?？捎玫某蓡T類(lèi)型為：primitive類(lèi)型、, String, Class, enumerated類(lèi)型, annotation類(lèi)型, 和前面類(lèi)型的數組。
下面我們定義了一個(gè)名為UncheckedExceptions 的annotation類(lèi)型，它的成員是一個(gè)擴展了RuntimeException類(lèi)的類(lèi)數組。
@UncheckedExceptions({
IllegalArgumentException.class, StringIndexOutOfBoundsException.class
})
5。Annotation的目標：annotation通常被放在類(lèi)型定義和成員定義的前面。然而它也出現在package、方法參數、本地變量的前面。下面，我們來(lái)討論一下這些不大常用的寫(xiě)法：
package annotation出現在package聲明的前面。
下面的例子package-info.java中不包含任何的公共類(lèi)型定義，卻包含一個(gè)可選的javadoc注釋。
/**
* This package holds my custom annotation types.
*/
@com.davidflanagan.annotations.Author("David Flanagan")
package com.davidflanagan.annotations;
當package-info.java文件被編譯時(shí)，它將產(chǎn)生名為包含annotation（特殊的接口）聲明的package-info.class的類(lèi)。這個(gè)接口沒(méi)有成員，它的名字package-info不是一個(gè)合法的java標識，所以它不能用在java源代碼中。這個(gè)接口的存在只是簡(jiǎn)單的被看作一個(gè)為package annotation準備的占位符。
用于修飾方法參數、catch參數、本地變量的annotation只是簡(jiǎn)單的出現在這些程序成員的修飾符位置。java類(lèi)文件格式?jīng)]有為本地變量或者catch參數存儲annotation作準備，所以這些annotation總是保留在源代碼級別（source retention）；方法參數annotation能夠保存在類(lèi)文件中，也可以在保留到運行時(shí)。
最后，請注意，枚舉類(lèi)型定義中不允許任何的修飾符修飾其枚舉值。
6。Annotation和默認值：在A(yíng)nnotation中，沒(méi)有默認值的成員必須有一個(gè)成員值。而如何理解默認值是如何被處理就是一個(gè)很重要的細節：annotation類(lèi)型所定義的成員默認值被存儲在class文件中，不被編譯到annotation里面。如果我們修改一個(gè)annotation類(lèi)型使其成員的默認值發(fā)生了改變，這個(gè)改變對于所有此類(lèi)型的annotation中沒(méi)有明確提供成員值的成員產(chǎn)生影響（即修改了該成員的成員值）。即使在annotation類(lèi)型使其成員的默認值被改變后annotation從沒(méi)被重新編譯過(guò)，該類(lèi)型的annotation(改變前已經(jīng)被編譯的)也受到影響。
三、Annotation工作原理：Annotation與反射在java5.0中Java.lang.reflect提供的反射API被擴充了讀取運行時(shí)annotation的能力。讓我們回顧一下前面所講的：一個(gè)annotation類(lèi)型被定義為runtime retention后，它才是在運行時(shí)可見(jiàn)，當class文件被裝載時(shí)被保存在class文件中的annotation才會(huì )被虛擬機讀取。那么reflect是如何幫助我們訪(fǎng)問(wèn)class中的annotation呢？
下文將在java.lang.reflect用于annotation的新特性，其中java.lang.reflect.AnnotatedElement是重要的接口，它代表了提供查詢(xún)annotation能力的程序成員。這個(gè)接口被java.lang.Package、java.lang.Class實(shí)現，并間接地被Method類(lèi)、Constructor類(lèi)、java.lang.reflect的Field類(lèi)實(shí)現。而annotation中的方法參數可以通過(guò)Method類(lèi)、Constructor類(lèi)的getParameterAnnotations()方法獲得。
下面的代碼使用了AnnotatedElement類(lèi)的isAnnotationPresent()方法判斷某個(gè)方法是否具有@Unstable annotation，從而斷言此方法是否穩定：
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沒(méi)有成員變量，所以我們只要知道class的方法是否使用了annotation修飾就可以了。而當處理具有成員的annotation時(shí)，我們通過(guò)使用getAnnotation()方法來(lái)獲得annotation的成員信息（成員名稱(chēng)、成員值）。這里我們看到了一套優(yōu)美的java annotation系統：如果annotation存在，那么實(shí)現了相應的annotation類(lèi)型接口的對象將被getAnnotation()方法返回，接著(zhù)調用定義在annotation類(lèi)型中的成員方法可以方便地獲得任何成員值。
回想一下，前面介紹的@Reviews annotation，如果這個(gè)annotation類(lèi)型被聲明為runtime retention的話(huà)，我們通過(guò)下面的代碼來(lái)訪(fǎng)問(wèn)@Reviews annotation的成員值：
AnnotatedElement target = WhizzBangClass.class; //獲得被查詢(xún)的AnnotatedElement
// 查詢(xún)AnnotatedElement的@Reviews annotation信息
Reviews annotation = target.getAnnotation(Reviews.class);
// 因為@Reviews annotation類(lèi)型的成員為@Review annotation類(lèi)型的數組，
// 所以下面聲明了Review[] reviews保存@Reviews annotation類(lèi)型的value成員值。
Review[] reviews = annotation.value();
// 查詢(xún)每個(gè)@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類(lèi)型是一個(gè)非凡的接口，所以?xún)烧咧g存在著(zhù)某些差異：
A.Annotation類(lèi)型使用關(guān)鍵字@interface而不是interface。這個(gè)關(guān)鍵字聲明隱含了一個(gè)信息：它是繼承了java.lang.annotation.Annotation接口，并非聲明了一個(gè)interface。
B.Annotation類(lèi)型、方法定義是獨特的、受限制的。Annotation類(lèi)型的方法必須聲明為無(wú)參數、無(wú)異常拋出的。這些方法定義了annotation的成員：方法名成為了成員名，而方法返回值成為了成員的類(lèi)型。而方法返回值類(lèi)型必須為primitive類(lèi)型、Class類(lèi)型、枚舉類(lèi)型、annotation類(lèi)型或者由前面類(lèi)型之一作為元素的一維數組。方法的后面可以使用default和一個(gè)默認數值來(lái)聲明成員的默認值，null不能作為成員默認值，這與我們在非annotation類(lèi)型中定義方法有很大不同。
Annotation類(lèi)型和它的方法不能使用annotation類(lèi)型的參數、成員不能是generic。只有返回值類(lèi)型是Class的方法可以在annotation類(lèi)型中使用generic，因為此方法能夠用類(lèi)轉換將各種類(lèi)型轉換為Class。
C.Annotation類(lèi)型又與接口有著(zhù)近似之處。它們可以定義常量、靜態(tài)成員類(lèi)型（比如枚舉類(lèi)型定義）。Annotation類(lèi)型也可以如接口一般被實(shí)現或者繼承。
2．實(shí)例：下面，我們將看到如何定義annotation類(lèi)型的example。它展示了annotation類(lèi)型聲明以及@interface與interface之間的不同：
package com.davidflanagan.annotations;
import java.lang.annotation.*;
/**
* 使用annotation來(lái)描述那些被標注的成員是不穩定的，需要更改
*/
@Retention(RetentionPolicy.RUNTIME)
public @interface Unstable {}
下面的另一個(gè)example只定義了一個(gè)成員。并通過(guò)將這個(gè)成員命名為value，使我們可以方便的使用這種annotation的快捷聲明方式：
/**
* 使用Author這個(gè)annotation定義在程序中指出代碼的作者
*/
public @interface Author {
/** 返回作者名 */
String value();
}
以下的example更加復雜。Reviews annotation類(lèi)型只有一個(gè)成員，但是這個(gè)成員的類(lèi)型是復雜的：由Review annotation組成的數組。Review annotation類(lèi)型有3個(gè)成員：枚舉類(lèi)型成員grade、表示Review名稱(chēng)的字符串類(lèi)型成員Reviewer、具有默認值的字符串類(lèi)型成員Comment。
import java.lang.annotation.*;
/**
* Reviews annotation類(lèi)型只有一個(gè)成員，
* 但是這個(gè)成員的類(lèi)型是復雜的：由Review annotation組成的數組
*/
@Retention(RetentionPolicy.RUNTIME)
public @interface Reviews {
Review[] value();
}
/**
* Review annotation類(lèi)型有3個(gè)成員：
* 枚舉類(lèi)型成員grade、
* 表示Review名稱(chēng)的字符串類(lèi)型成員Reviewer、
* 具有默認值的字符串類(lèi)型成員Comment。
*/
public @interface Review {
// 內嵌的枚舉類(lèi)型
public static enum Grade { EXCELLENT, SATISFACTORY, UNSATISFACTORY };
// 下面的方法定義了annotation的成員
Grade grade();
String reviewer();
String comment() default "";
}
最后，我們來(lái)定義一個(gè)annotation方法用于羅列出類(lèi)運行中所有的unchecked異常（上文已經(jīng)提到這種情況不一定是錯誤）。這個(gè)annotation類(lèi)型將一個(gè)數組作為了唯一的成員。數組中的每個(gè)元素都是異常類(lèi)。為了加強對未檢查的異常（此類(lèi)異常都是在運行時(shí)拋出）進(jìn)行報告，我們可以在代碼中對異常的類(lèi)型進(jìn)行限制：
public @interface UncheckedExceptions {
Class<? extends RuntimeException>[] value();
}
五、Meta-AnnotationAnnotation類(lèi)型可以被它們自己所標注。Java5.0定義了4個(gè)標準的meta-annotation類(lèi)型，它們被用來(lái)提供對其它annotation類(lèi)型作說(shuō)明。這些類(lèi)型和它們所支持的類(lèi)在java.lang.annotation包中可以找到。如果需要更詳細的信息可以參考jdk5.0手冊。
1．再談Target作為meta-annotation類(lèi)型的Target,它描述了annotation所修飾的程序成員的類(lèi)型。當一個(gè)annotation類(lèi)型沒(méi)有Target時(shí)，它將被作為普通的annotation看待。當將它修飾一個(gè)特定的程序成員時(shí)，它將發(fā)揮其應用的作用，例如：Override用于修飾方法時(shí)，增加了@Target這個(gè)meta-annotation就使編譯器對annotation作檢查，從而去掉修飾錯誤類(lèi)型的Override。
Target meta-annotation類(lèi)型有唯一的value作為成員。這個(gè)成員的類(lèi)型是java.lang.annotation.ElementType[]類(lèi)型的，ElementType類(lèi)型是可以被標注的程序成員的枚舉類(lèi)型。
2．Retention的用法我們在文章的開(kāi)頭曾經(jīng)提到過(guò)Retention，但是沒(méi)有詳細講解。Retention描述了annotation是否被編譯器丟棄或者保留在class文件；如果保留在class文件中，是否在class文件被裝載時(shí)被虛擬機讀取。默認情況下，annotation被保存在class文件中，但在運行時(shí)并不能被反射訪(fǎng)問(wèn)。Retention具有三個(gè)取值：source、class、runtime，這些取值來(lái)自java.lang.annotation.RetentionPolicy的枚舉類(lèi)型值。
Retention meta-annotation類(lèi)型有唯一的value作為成員，它的取值來(lái)自java.lang.annotation.RetentionPolicy的枚舉類(lèi)型值。
3．DocumentedDocumented是一個(gè)meta-annotation類(lèi)型，用于描述其它類(lèi)型的annotation應該被作為被標注的程序成員的公共API，因此可以被例如javadoc此類(lèi)的工具文檔化。
Documented是一個(gè)marker annotation，沒(méi)有成員。
4．Inherited@Inherited meta-annotation也是一個(gè)marker annotation，它闡述了某個(gè)被標注的類(lèi)型是被繼承的。如果一個(gè)使用了@Inherited修飾的annotation類(lèi)型被用于一個(gè)class，則這個(gè)annotation將被用于該class的子類(lèi)。
注意：@Inherited annotation類(lèi)型是被標注過(guò)的class的子類(lèi)所繼承。類(lèi)并不從它所實(shí)現的接口繼承annotation，方法并不從它所重載的方法繼承annotation。
值得思考的是，當@Inherited annotation類(lèi)型標注的annotation的Retention是RetentionPolicy.RUNTIME，則反射API增強了這種繼承性。如果我們使用java.lang.reflect去查詢(xún)一個(gè)@Inherited annotation類(lèi)型的annotation時(shí)，反射代碼檢查將展開(kāi)工作：檢查class和其父類(lèi)，直到發(fā)現指定的annotation類(lèi)型被發(fā)現，或者到達類(lèi)繼承結構的頂層。
六、總結：本文幾乎覆蓋了所有的Annotation的概念和知識點(diǎn)，從annotation的定義、語(yǔ)法到工作原理、如何自定義annotation，直至meta-annotation。其中也具有一些配套的代碼片斷可參考，雖然不是很多，但是可謂言簡(jiǎn)意賅、著(zhù)其重點(diǎn)，本人認為用好annotation的關(guān)鍵還在于使用。希望本手冊能夠幫助大家用好annotation，這也是本人的最大快樂(lè )。
