Java Annotation入門
作者：cleverpig




版權聲明：本文可以自由轉載，轉載時請務必以超鏈接形式標明文章原始出處和作者信息及本聲明
作者:cleverpig(作者的Blog:http://blog.matrix.org.cn/page/cleverpig)
原文:[http://www.matrix.org.cn/resource/article/44/44048_Java+Annotation.html]http://www.matrix.org.cn/resource/article/44/44048_Java+Annotation.html[/url]
關鍵字:Java,annotation,標注


摘要：
本文針對java初學者或者annotation初次使用者全面地說明了annotation的使用方法、定義方式、分類。初學者可以通過以上的說明制作簡單的annotation程序，但是對于一些高級的annotation應用（例如使用自定義annotation生成javabean映射xml文件）還需要進一步的研究和探討。涉及到深入annotation的內容，作者將在后文《Java Annotation高級應用》中談到。

同時，annotation運行存在兩種方式：運行時、編譯時。上文中討論的都是在運行時的annotation應用，但在編譯時的annotation應用還沒有涉及，

一、為什么使用Annotation：

在JAVA應用中，我們常遇到一些需要使用模版代碼。例如，為了編寫一個JAX-RPC web service，我們必須提供一對接口和實現作為模版代碼。如果使用annotation對遠程訪問的方法代碼進行修飾的話，這個模版就能夠使用工具自動生成。
另外，一些API需要使用與程序代碼同時維護的附屬文件。例如，JavaBeans需要一個BeanInfo Class與一個Bean同時使用/維護，而EJB則同樣需要一個部署描述符。此時在程序中使用annotation來維護這些附屬文件的信息將十分便利而且減少了錯誤。

二、Annotation工作方式：

在5.0 版之前的Java平臺已經具有了一些ad hoc annotation機制。比如，使用transient修飾符來標識一個成員變量在序列化子系統中應被忽略。而@deprecated這個 javadoc tag也是一個ad hoc annotation用來說明一個方法已過時。從Java5.0版發布以來，5.0平臺提供了一個正式的annotation功能：允許開發者定義、使用自己的annoatation類型。此功能由一個定義annotation類型的語法和一個描述annotation聲明的語法，讀取annotaion 的API，一個使用annotation修飾的class文件，一個annotation處理工具（apt）組成。
annotation并不直接影響代碼語義，但是它能夠工作的方式被看作類似程序的工具或者類庫，它會反過來對正在運行的程序語義有所影響。annotation可以從源文件、class文件或者以在運行時反射的多種方式被讀取。
當然annotation在某種程度上使javadoc tag更加完整。一般情況下，如果這個標記對java文檔產生影響或者用于生成java文檔的話，它應該作為一個javadoc tag；否則將作為一個annotation。

三、Annotation使用方法：

1。類型聲明方式：
通常，應用程序并不是必須定義annotation類型，但是定義annotation類型并非難事。Annotation類型聲明于一般的接口聲明極為類似，區別只在于它在interface關鍵字前面使用“@”符號。
annotation 類型的每個方法聲明定義了一個annotation類型成員，但方法聲明不必有參數或者異常聲明；方法返回值的類型被限制在以下的范圍： primitives、String、Class、enums、annotation和前面類型的數組；方法可以有默認值。

下面是一個簡單的annotation類型聲明：
清單1:

????/**
???? * Describes the Request-For-Enhancement(RFE) that led
???? * to the presence of the annotated API element.
???? */
????public @interface RequestForEnhancement {
????????int????id();
????????String synopsis();
????????String engineer() default "[unassigned]"; 
????????String date();????default "[unimplemented]"; 
????}

代碼中只定義了一個annotation類型RequestForEnhancement。

2。修飾方法的annotation聲明方式：
annotation 是一種修飾符，能夠如其它修飾符（如public、static、final）一般使用。習慣用法是annotaions用在其它的修飾符前面。 annotations由“@+annotation類型+帶有括號的成員-值列表”組成。這些成員的值必須是編譯時常量（即在運行時不變）。

A：下面是一個使用了RequestForEnhancement annotation的方法聲明：
清單2:

????@RequestForEnhancement(
????????id?????? = 2868724,
????????synopsis = "Enable time-travel",
????????engineer = "Mr. Peabody",
????????date???? = "4/1/3007"
????)
????public static void travelThroughTime(Date destination) { ... }

B：當聲明一個沒有成員的annotation類型聲明時，可使用以下方式：
清單3:

????/**
???? * Indicates that the specification of the annotated API element
???? * is preliminary and subject to change.
???? */
????public @interface Preliminary { }

作為上面沒有成員的annotation類型聲明的簡寫方式：
清單4:

????@Preliminary public class TimeTravel { ... }

C：如果在annotations中只有唯一一個成員，則該成員應命名為value：
清單5:

????/**
???? * Associates a copyright notice with the annotated API element.
???? */
????public @interface Copyright {
????????String value();
????}

更為方便的是對于具有唯一成員且成員名為value的annotation（如上文），在其使用時可以忽略掉成員名和賦值號（=）：
清單6:

????@Copyright("2002 Yoyodyne Propulsion Systems")
????public class OscillationOverthruster { ... }

3。一個使用實例：
結合上面所講的，我們在這里建立一個簡單的基于annotation測試框架。首先我們需要一個annotation類型來表示某個方法是一個應該被測試工具運行的測試方法。
清單7:

????import java.lang.annotation.*;

????/**
???? * Indicates that the annotated method is a test method.
???? * This annotation should be used only on parameterless static methods.
???? */
????@Retention(RetentionPolicy.RUNTIME)
????@Target(ElementType.METHOD)
????public @interface Test { }

值得注意的是annotaion類型聲明是可以標注自己的，這樣的annotation被稱為“meta-annotations”。

在上面的代碼中，@Retention(RetentionPolicy.RUNTIME)這個meta-annotation表示了此類型的 annotation將被虛擬機保留使其能夠在運行時通過反射被讀取。而@Target(ElementType.METHOD)表示此類型的 annotation只能用于修飾方法聲明。

下面是一個簡單的程序，其中部分方法被上面的annotation所標注：
清單8:

????public class Foo {
????????@Test public static void m1() { }
????????public static void m2() { }
????????@Test public static void m3() {
????????????throw new RuntimeException("Boom");
????????}
????????public static void m4() { }
????????@Test public static void m5() { }
????????public static void m6() { }
????????@Test public static void m7() {
????????????throw new RuntimeException("Crash");
????????}
????????public static void m8() { }
????}

Here is the testing tool:

????import java.lang.reflect.*;

????public class RunTests {
?????? public static void main(String[] args) throws Exception {
??????????int passed = 0, failed = 0;
??????????for (Method m : Class.forName(args[0]).getMethods()) {
???????????? if (m.isAnnotationPresent(Test.class)) {
????????????????try {
?????????????????? m.invoke(null);
?????????????????? passed++;
????????????????} catch (Throwable ex) {
?????????????????? System.out.printf("Test %s failed: %s %n", m, ex.getCause());
?????????????????? failed++;
????????????????}
???????????? }
??????????}
??????????System.out.printf("Passed: %d, Failed %d%n", passed, failed);
?????? }
????}

這個程序從命令行參數中取出類名，并且遍歷此類的所有方法，嘗試調用其中被上面的測試annotation類型標注過的方法。在此過程中為了找出哪些方法被 annotation類型標注過，需要使用反射的方式執行此查詢。如果在調用方法時拋出異常，此方法被認為已經失敗，并打印一個失敗報告。最后，打印運行通過/失敗的方法數量。
下面文字表示了如何運行這個基于annotation的測試工具：

清單9:

????$ java RunTests Foo
????Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom 
????Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash 
????Passed: 2, Failed 2

四、Annotation分類：

根據annotation的使用方法和用途主要分為以下幾類：

1。內建Annotation——Java5.0版在java語法中經常用到的內建Annotation：
@Deprecated用于修飾已經過時的方法；
@Override用于修飾此方法覆蓋了父類的方法（而非重載）；
@SuppressWarnings用于通知java編譯器禁止特定的編譯警告。

下面代碼展示了內建Annotation類型的用法：
清單10:

package com.bjinfotech.practice.annotation;

/**
 * 演示如何使用java5內建的annotation
 * 參考資料：
 * http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
 * http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
 * http://mindprod.com/jgloss/annotations.html
 * @author cleverpig
 *
 */
import java.util.List;

public class UsingBuiltInAnnotation {
????????//食物類
????????class Food{}
????????//干草類
????????class Hay extends Food{}
????????//動物類
????????class Animal{
????????????????Food getFood(){
????????????????????????return null;
????????????????}
????????????????//使用Annotation聲明Deprecated方法
????????????????@Deprecated
????????????????void deprecatedMethod(){
????????????????}
????????}
????????//馬類-繼承動物類
????????class Horse extends Animal{
????????????????//使用Annotation聲明覆蓋方法
????????????????@Override
????????????????Hay getFood(){
????????????????????????return new Hay();
????????????????}
????????????????//使用Annotation聲明禁止警告
????????????????@SuppressWarnings({"deprecation","unchecked"})
????????????????void callDeprecatedMethod(List horseGroup){
????????????????????????Animal an=new Animal();
????????????????????????an.deprecatedMethod();
????????????????????????horseGroup.add(an);
????????????????}
????????}
}

2。開發者自定義Annotation：由開發者自定義Annotation類型。
下面是一個使用annotation進行方法測試的sample：

AnnotationDefineForTestFunction類型定義如下：
清單11:

package com.bjinfotech.practice.annotation;

import java.lang.annotation.*;
/**
 * 定義annotation
 * @author cleverpig
 *
 */
//加載在VM中，在運行時進行映射
@Retention(RetentionPolicy.RUNTIME)
//限定此annotation只能標示方法
@Target(ElementType.METHOD)
public @interface AnnotationDefineForTestFunction{}

測試annotation的代碼如下：

清單12:

package com.bjinfotech.practice.annotation;

import java.lang.reflect.*;

/**
 * 一個實例程序應用前面定義的Annotation：AnnotationDefineForTestFunction
 * @author cleverpig
 *
 */
public class UsingAnnotation {
????????@AnnotationDefineForTestFunction public static void method01(){}
????????
????????public static void method02(){}
????????
????????@AnnotationDefineForTestFunction public static void method03(){
????????????????throw new RuntimeException("method03");
????????}
????????
????????public static void method04(){
????????????????throw new RuntimeException("method04");
????????}
????????
????????public static void main(String[] argv) throws Exception{
????????????????int passed = 0, failed = 0;
????????????????//被檢測的類名
????????????????String className="com.bjinfotech.practice.annotation.UsingAnnotation";
????????????????//逐個檢查此類的方法，當其方法使用annotation聲明時調用此方法
????????????for (Method m : Class.forName(className).getMethods()) {
?????????????? if (m.isAnnotationPresent(AnnotationDefineForTestFunction.class)) {
??????????????????try {
???????????????????? m.invoke(null);
???????????????????? passed++;
??????????????????} catch (Throwable ex) {
???????????????????? System.out.printf("測試 %s 失敗: %s %n", m, ex.getCause());
???????????????????? failed++;
??????????????????}
?????????????? }
????????????}
????????????System.out.printf("測試結果： 通過: %d, 失敗： %d%n", passed, failed);
????????}
}

3。使用第三方開發的Annotation類型
這也是開發人員所常常用到的一種方式。比如我們在使用Hibernate3.0時就可以利用Annotation生成數據表映射配置文件，而不必使用Xdoclet。

五、總結：

1。前面的文字說明了annotation的使用方法、定義方式、分類。初學者可以通過以上的說明制作簡單的annotation程序，但是對于一些高級的 annotation應用（例如使用自定義annotation生成javabean映射xml文件）還需要進一步的研究和探討。

2。同時，annotation運行存在兩種方式：運行時、編譯時。上文中討論的都是在運行時的annotation應用，但在編譯時的annotation應用還沒有涉及，因為編譯時的annotation要使用annotation processing tool。

涉及以上2方面的深入內容，作者將在后文《Java Annotation高級應用》中談到。

六、參考資源：
·Matrix-Java開發者社區:http://www.matrix.org.cn
·http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·作者的Blog:http://blog.matrix.org.cn/page/cleverpig