本系列的第一篇文章 介紹了什麼是元數據，元數據的重要性，以及如何使用 J2SE 5.0（也叫做 Tiger）的基本內置注釋。如果習慣了這些概念，您可能已經在想，Java 5 提供的三種標准注釋也並不是特別健壯，能使用的只有 Deprecated 、 SuppressWarnings 和 Override 而已。所幸的是，Tiger 還允許定義自己的注釋類型。在本文中，我將通過一些示例引導您掌握這個相對簡單的過程。您還將了解如何對自己的注釋進行注解，以及這樣做的一些好處。我要感謝 O'Reilly Media, Inc.，他們非常慷慨地允許我在本文中使用我關於 Tiger 的書籍的“注釋”一章中的代碼示例。
定義自己的注釋類型
通過添加了一個小小的語法（Tiger 添加了大量的語法結構），Java 語言支持一種新的類型 —— 注釋類型（annotation type）。注釋類型看起來很像普通的類，但是有一些特有的性質。最明顯的一點是，可以在類中以符號（ @ ）的形式注釋其他 Java 代碼。我將一步一步地介紹這個過程。
@interface 聲明
定義新的注釋類型與創建接口有很多類似之處，只不過 interface 關鍵字之前要有一個 @ 符號。清單 1 中給出的是一個最簡單的注釋類型的示例：
清單 1. 非常簡單的注釋類型
package com.oreilly.tiger.ch06;
/**
* Marker annotation to indicate that a method or class
* is still in progress.
*/
public @interface InProgress { }
清單 1 的含義非常明顯。如果編譯這個注釋類型，並確信其位於類路徑中，那麼您就可以在自己的源代碼方法中使用它，以指出某個方法或類仍在處理中，如清單 2 所示：
清單 2. 使用定制的注釋類型
@com.oreilly.tiger.ch06.InProgress
public void calculateInterest(float amount, float rate) {
// Need to finish this method later
}
清單 1 所示注釋類型的使用方法和內置注釋類型的使用方法完全相同，只不過要同時使用名稱和所在的包來指示定制注釋。當然，一般的 Java 規則仍然適用，您可以導入該注釋類型，直接使用 @InProgress 引用它。
添加成員
上面所示的基本用法還遠遠不夠健壯。您一定還記得“第 1 部分”中曾經提到的，注釋類型可以有成員變量。這一點非常有用，尤其是准備將注釋作為更加復雜的元數據，而不僅僅將它作為原始文檔使用的時候。代碼分析工具喜歡加工大量的信息，定制注釋可以提供這類信息。
注釋類型中的數據成員被設置成使用有限的信息進行工作。定義數據成員後不需要分別定義訪問和修改的方法。相反，只需要定義一個方法，以成員的名稱命名它。數據類型應該是該方法返回值的類型。清單 3 是一個具體的示例，它澄清了一些比較含糊的要求：
清單 3. 向注釋類型添加成員
package com.oreilly.tiger.ch06;
/**
* Annotation type to indicate a task still needs to be
* completed.
*/
public @interface TODO {
String value();
}
盡管清單 3 看起來很奇怪，但這是注釋類型所要求的格式。清單 3 定義了一個名為 value 的字符串，該注釋類型能夠接受它。然後，就可以像清單 4 中那樣使用注釋類型：
清單 4. 使用帶有成員值的注釋類型
@com.oreilly.tiger.ch06.InProgress
@TODO("Figure out the amount of interest per month")
public void calculateInterest(float amount, float rate) {
// Need to finish this method later
}
這裡同樣沒有多少花樣。清單 4 假設已經引入了 com.oreilly.tiger.ch06.TODO ，因此源代碼中的注釋 不 需要包名作前綴。此外，需要注意的是，清單 4 中采用了簡寫的方法：將值 （"Figure out the amount of interest per month"） 直接提供給注釋，沒有指定成員變量名。清單 4 和清單 5 是等價的，後者沒有采用簡寫形式：
清單 5. 清單 4 的“加長”版
@com.oreilly.tiger.ch06.InProgress
@TODO(value="Figure out the amount of interest per month")
public void calculateInterest(float amount, float rate) {
// Need to finish this method later
}
當然作為編碼人員，我們都不願意跟這種“加長”版攪在一起。不過要注意，只有當注釋類型只有 一個 成員變量，而且變量名為 value 時，才能使用簡寫形式。如果不符合這個條件，那麼就無法利用這種特性。
設置默認值
迄今為止，您已經有了一個很好的起點，但是要做得完美，還有很長的一段路要走。您可能已經想到，下一步就要為注釋設置某個默認值。如果您希望用戶指定某些值，但是只有這些值與默認值不同的時候才需要指定其他的值，那麼設置默認值就是一種很好的辦法。清單 6 用另一個定制注釋 —— 來自 清單 4 的 TODO 注釋類型的一個全功能版本，示范了這個概念及其實現：
清單 6. 帶有默認值的注釋類型
package com.oreilly.tiger.ch06;
public @interface GroupTODO {
public enum Severity { CRITICAL, IMPORTANT, TRIVIAL, DOCUMENTATION };
Severity severity()
default Severity.IMPORTANT;
String item();
String assignedTo();
String dateAssigned();
}
清單 6 中的 GroupTODO 注釋類型中添加了幾個新的變量。因為該注釋類型的成員變量不是一個，所以將一個變量命名為 value 沒有任何意義。只要成員變量多於一個，就應該盡可能准確地為其命名。因為不可能從 清單 5所示的簡寫形式中獲益，所以您需要創建雖然稍微有點冗長，但是更容易理解的注釋類型。
清單 6 中出現的另一個新特性是注釋類型定義了自己的枚舉（枚舉，即 enumeration，通常也稱為 enums，是 Java 5 的另一個新特性。它並沒有多麼地不同凡響，對注釋類型更是如此）。然後，清單 6 使用新定義的枚舉作為一個成員變量的類型。
最後，再回到我們的主題 —— 默認值。建立默認值的過程非常瑣碎，需要在成員聲明的後面添加關鍵字 default ，然後提供默認值。正如您所料，默認值的類型必須與成員變量聲明的類型完全相同。同樣，這也不是什麼火箭科學，只不過是詞法上的變異。清單 7 給出了一個具體應用中的 GroupTODO 注釋，其中 沒有 指定 severity 成員：
清單 7. 使用默認值
@com.oreilly.tiger.ch06.InProgress
@GroupTODO(
item="Figure out the amount of interest per month",
assignedTo="Brett McLaughlin",
dateAssigned="08/04/2004"
)
public void calculateInterest(float amount, float rate) {
// Need to finish this method later
}
清單 8 中使用了同一個注釋，但這一次給出了 severity 的值：
清單 8. 改寫默認值
@com.oreilly.tiger.ch06.InProgress
@GroupTODO(
severity=GroupTODO.Severity.DOCUMENTATION,
item="Need to explain how this rather unusual method works",
assignedTo="Jon Stevens",
dateAssigned="07/30/2004"
)
public void reallyConfusingMethod(int codePoint) {
// Really weird code implementation
}
對注釋的注釋
結束關於注釋的討論之前（至少在本系列文章中），我想簡要地討論一下注釋的注釋。第 1 部分中所接觸的預定義注釋類型都有預定義的目的。但是在編寫自己的注釋類型時，注釋類型的目的並不總是顯而易見的。除了基本的文檔外，可能還要針對某個特定的成員類型或者一組成員類型編寫類型。這就要求您為注釋類型提供某種元數據，以便編譯器保證按照預期的目的使用注釋。
當然，首先想到的就是 Java 語言選擇的元數據形式 —— 注釋。您可以使用 4 種預定義的注釋類型（稱為 元注釋）對您的注釋進行注釋。我將對這 4 種類型分別進行介紹。
指定目標
最明顯的元注釋就是允許何種程序元素具有定義的注釋類型。毫不奇怪，這種元注釋被稱為 Target 。但是在了解如何使用 Target 之前，您還需要認識另一個類，該類被稱為 ElementType ，它實際上是一個枚舉。這個枚舉定義了注釋類型可應用的不同程序元素。清單 9 給出了完整的 ElementType 枚舉：
清單 9. ElementType 枚舉
package java.lang.annotation;
public enum ElementType {
TYPE, // Class, interface, or enum (but not annotation)
FIELD, // Field (including enumerated values)
METHOD, // Method (does not include constructors)
PARAMETER, // Method parameter
CONSTRUCTOR, // Constructor
LOCAL_VARIABLE, // Local variable or catch clause
ANNOTATION_TYPE, // Annotation Types (meta-annotations)
PACKAGE // Java package
}
清單 9 中的枚舉值意義很明確，您自己可以分析其應用的目標（通過後面的注解）。使用 Target 元注釋時，至少要提供這些枚舉值中的一個並指出注釋的注釋可以應用的程序元素。清單 10 說明了 Target 的用法：
清單 10. 使用 Target 元注釋
package com.oreilly.tiger.ch06;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
/**
* Annotation type to indicate a task still needs to be completed
*/
@Target({ElementType.TYPE,
ElementType.METHOD,
ElementType.CONSTRUCTOR,
ElementType.ANNOTATION_TYPE})
public @interface TODO {
String value();
}
現在，Java 編譯器將把 TODO 應用於類型、方法、構造函數和其他注釋類型。這樣有助於避免他人誤用您的注釋類型（或者最好的地方是， 您自己也不會因為疲憊而誤用它）。
設置保持性
下一個要用到的元注釋是 Retention 。這個元注釋和 Java 編譯器處理注釋的注釋類型的方式有關。編譯器有幾種不同選擇：
將注釋保留在編譯後的類文件中，並在第一次加載類時讀取它。
將注釋保留在編譯後的類文件中，但是在運行時忽略它。
按照規定使用注釋，但是並不將它保留到編譯後的類文件中。
這三種選項用 java.lang.annotation.RetentionPolicy 枚舉表示，如清單 11 所示：
清單 11. RetentionPolicy 枚舉
package java.lang.annotation;
public enum RetentionPolicy {
SOURCE, // Annotation is discarded by the compiler
CLASS, // Annotation is stored in the class file, but ignored by the VM
RUNTIME // Annotation is stored in the class file and read by the VM
}
現在可以看出， Retention 元注釋類型使用清單 11 所示的枚舉值中的一個作為惟一的參數。可以將該元注釋用於您的注釋，如清單 12 所示：
清單 12. 使用 Retention 元注釋
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
// annotation type body
}
如清單 12 所示，這裡可以使用簡寫形式，因為 Retention 只有一個成員變量。如果要將保持性設為 RetentionPolicy.CLASS ，那麼什麼也不需要做，因為這就是默認行為。
添加公共文檔
下一個元注釋是 Documented 。這個元注釋也非常容易理解，部分原因是 Documented 是一個標記注釋。您應該還記得第 1 部分中曾經提到，標記注釋沒有成員變量。 Documented 表示注釋應該出現在類的 Javadoc 中。在默認情況下，注釋 不包括在 Javadoc 中，如果花費大量時間注釋一個類、詳細說明未完成的工作、正確完成了什麼或者描述行為，那麼您應該記住這一點。
清單 13 說明了 Documented 元注釋的用法：
清單 13. 使用 Documented 元注釋
package com.oreilly.tiger.ch06;
import java.lang.annotation.Documented;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Marker annotation to indicate that a method or class
* is still in progress.
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface InProgress { }
Documented 的一個實用技巧是保持性策略。注意，清單 13 中規定注釋的保持性（retention）是 RUNTIME ，這是使用 Documented 注釋類型所 必需的。Javadoc 使用虛擬機從其類文件（而非源文件）中加載信息。確保 VM 從這些類文件中獲得生成 Javadoc 所需信息的惟一方法是將保持性規定為 RetentionPolicy.RUNTIME 。這樣，注釋就會保留在編譯後的類文件中 並且由虛擬機加載，然後 Javadoc 可以從中抽取出來添加到類的 HTML 文檔中。
設置繼承
最後一個元注釋 Inherited ，可能是最復雜、使用最少、也最容易造成混淆的一個。這就是說，我們簡單地看一看就可以了。
首先考慮這樣一種情況：假設您通過定制的 InProgress 注釋標記一個類正在開發之中，這完全沒有問題，對吧？這些信息還會出現在 Javadoc 中，只要您正確地應用了 Documented 元注釋。現在，假設您要編寫一個新類，擴展那個還在開發之中的類，也不難，是不是？但是要記住，那個超類還在開發之中。如果您使用子類，或者查看它的文檔，根本沒有線索表明還有什麼地方沒有完成。您本來希望看到 InProgress 注釋被帶到子類中 —— 因為這是 繼承 的 —— 但情況並非如此。您必須使用 Inherited 元注釋說明所期望的行為，如清單 14 所示：
清單 14. 使用 Inherited 元注釋
package com.oreilly.tiger.ch06;
import java.lang.annotation.Documented;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* Marker annotation to indicate that a method or class
* is still in progress.
*/
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface InProgress { }
添加 @Inherited 後，您將看到 InProgress 出現在注釋類的子類中。當然，您並不希望所有的注釋類型都具有這種行為（因此默認值是 不 繼承的）。比如， TODO 注釋就不會（也不應該）被傳播。但是對於這裡示范的情況， Inherited 可能非常有用。
結束語
現在，您也許已經准備回到 Java 世界為所有的事物編寫文檔和注釋了。這不禁令我回想起人們了解 Javadoc 之後發生的事情。我們都陷入了文檔過濫的泥潭，直到有人認識到最好使用 Javadoc 來理清容易混淆的類或者方法。無論用 Javadoc 做了多少文章，也沒有人會去看那些易於理解的 getXXX() 和 setXXX() 方法。
注釋也可能出現同樣的趨勢，雖然不一定到那種程度。經常甚至頻繁地使用標准注釋類型是一種較好的做法。所有的 Java 5 編譯器都支持它們，它們的行為也很容易理解。但是，如果要使用定制注釋和元注釋，那麼就很難保證花費很大力氣創建的那些類型在您的開發環境之外還有什麼意義。因此要慎重。在合理的情況下使用注釋，不要荒謬使用。無論如何，注釋都是一種很好的工具，可以在開發過程中提供真正的幫助。
