內(nèi)容: Java Annotation入門(mén)作者：cleverpig版權(quán)聲明：本文可以自由轉(zhuǎn)載，轉(zhuǎn)載時(shí)請(qǐng)務(wù)必以超鏈接形式標(biāo)明文章原始出處和作者信息及本聲明作者: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]關(guān)鍵字:Java,annotation,標(biāo)注摘要：本文針對(duì)java初學(xué)者或者annotation初次使用者全面地說(shuō)明了annotation的使用方法、定義方式、分類(lèi)。初學(xué)者可以通過(guò)以上的說(shuō)明制作簡(jiǎn)單的annotation程序，但是對(duì)于一些高級(jí)的annotation應(yīng)用（例如使用自定義annotation生成javabean映射xml文件）還需要進(jìn)一步的研究和探討。涉及到深入annotation的內(nèi)容，作者將在后文《Java Annotation高級(jí)應(yīng)用》中談到。同時(shí)，annotation運(yùn)行存在兩種方式：運(yùn)行時(shí)、編譯時(shí)。上文中討論的都是在運(yùn)行時(shí)的annotation應(yīng)用，但在編譯時(shí)的annotation應(yīng)用還沒(méi)有涉及，一、為什么使用Annotation：在JAVA應(yīng)用中，我們常遇到一些需要使用模版代碼。例如，為了編寫(xiě)一個(gè)JAX-RPC web service，我們必須提供一對(duì)接口和實(shí)現(xiàn)作為模版代碼。如果使用annotation對(duì)遠(yuǎn)程訪(fǎng)問(wèn)的方法代碼進(jìn)行修飾的話(huà)，這個(gè)模版就能夠使用工具自動(dòng)生成。另外，一些API需要使用與程序代碼同時(shí)維護(hù)的附屬文件。例如，JavaBeans需要一個(gè)BeanInfo Class與一個(gè)Bean同時(shí)使用/維護(hù)，而EJB則同樣需要一個(gè)部署描述符。此時(shí)在程序中使用annotation來(lái)維護(hù)這些附屬文件的信息將十分便利而且減少了錯(cuò)誤。二、Annotation工作方式：在5.0版之前的Java平臺(tái)已經(jīng)具有了一些ad hoc annotation機(jī)制。比如，使用transient修飾符來(lái)標(biāo)識(shí)一個(gè)成員變量在序列化子系統(tǒng)中應(yīng)被忽略。而@deprecated這個(gè)javadoc tag也是一個(gè)ad hoc annotation用來(lái)說(shuō)明一個(gè)方法已過(guò)時(shí)。從Java5.0版發(fā)布以來(lái)，5.0平臺(tái)提供了一個(gè)正式的annotation功能：允許開(kāi)發(fā)者定義、使用自己的annoatation類(lèi)型。此功能由一個(gè)定義annotation類(lèi)型的語(yǔ)法和一個(gè)描述annotation聲明的語(yǔ)法，讀取annotaion的API，一個(gè)使用annotation修飾的class文件，一個(gè)annotation處理工具（apt）組成。annotation并不直接影響代碼語(yǔ)義，但是它能夠工作的方式被看作類(lèi)似程序的工具或者類(lèi)庫(kù)，它會(huì)反過(guò)來(lái)對(duì)正在運(yùn)行的程序語(yǔ)義有所影響。annotation可以從源文件、class文件或者以在運(yùn)行時(shí)反射的多種方式被讀取。當(dāng)然annotation在某種程度上使javadoc tag更加完整。一般情況下，如果這個(gè)標(biāo)記對(duì)java文檔產(chǎn)生影響或者用于生成java文檔的話(huà)，它應(yīng)該作為一個(gè)javadoc tag；否則將作為一個(gè)annotation。三、Annotation使用方法：1。類(lèi)型聲明方式：通常，應(yīng)用程序并不是必須定義annotation類(lèi)型，但是定義annotation類(lèi)型并非難事。Annotation類(lèi)型聲明于一般的接口聲明極為類(lèi)似，區(qū)別只在于它在interface關(guān)鍵字前面使用“@符號(hào)。annotation類(lèi)型的每個(gè)方法聲明定義了一個(gè)annotation類(lèi)型成員，但方法聲明不必有參數(shù)或者異常聲明；方法返回值的類(lèi)型被限制在以下的范圍：primitives、String、Class、enums、annotation和前面類(lèi)型的數(shù)組；方法可以有默認(rèn)值。下面是一個(gè)簡(jiǎn)單的annotation類(lèi)型聲明：清單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]'; }代碼中只定義了一個(gè)annotation類(lèi)型RequestForEnhancement。2。修飾方法的annotation聲明方式：annotation是一種修飾符，能夠如其它修飾符（如public、static、final）一般使用。習(xí)慣用法是annotaions用在其它的修飾符前面。annotations由“@+annotation類(lèi)型+帶有括號(hào)的成員-值列表組成。這些成員的值必須是編譯時(shí)常量（即在運(yùn)行時(shí)不變）。A：下面是一個(gè)使用了RequestForEnhancement annotation的方法聲明：清單2: @RequestForEnhancement( id = 2868724, synopsis = 'Enable time-travel', engineer = 'Mr. Peabody', date = '4/1/3007' ) public static void travelThroughTime(Date destination) { ... }B：當(dāng)聲明一個(gè)沒(méi)有成員的annotation類(lèi)型聲明時(shí)，可使用以下方式：清單3: /** * Indicates that the specification of the annotated API element * is preliminary and subject to change. */ public @interface Preliminary { }作為上面沒(méi)有成員的annotation類(lèi)型聲明的簡(jiǎn)寫(xiě)方式：清單4: @Preliminary public class TimeTravel { ... }C：如果在annotations中只有唯一一個(gè)成員，則該成員應(yīng)命名為value：清單5: /** * Associates a copyright notice with the annotated API element. */ public @interface Copyright { String value(); }更為方便的是對(duì)于具有唯一成員且成員名為value的annotation（如上文），在其使用時(shí)可以忽略掉成員名和賦值號(hào)（=）：清單6: @Copyright('2002 Yoyodyne Propulsion Systems') public class OscillationOverthruster { ... }3。一個(gè)使用實(shí)例：結(jié)合上面所講的，我們?cè)谶@里建立一個(gè)簡(jiǎn)單的基于annotation測(cè)試框架。首先我們需要一個(gè)annotation類(lèi)型來(lái)表示某個(gè)方法是一個(gè)應(yīng)該被測(cè)試工具運(yùn)行的測(cè)試方法。清單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類(lèi)型聲明是可以標(biāo)注自己的，這樣的annotation被稱(chēng)為“meta-annotations。在上面的代碼中，@Retention(RetentionPolicy.RUNTIME)這個(gè)meta-annotation表示了此類(lèi)型的annotation將被虛擬機(jī)保留使其能夠在運(yùn)行時(shí)通過(guò)反射被讀取。而@Target(ElementType.METHOD)表示此類(lèi)型的annotation只能用于修飾方法聲明。下面是一個(gè)簡(jiǎn)單的程序，其中部分方法被上面的annotation所標(biāo)注：清單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); } }這個(gè)程序從命令行參數(shù)中取出類(lèi)名，并且遍歷此類(lèi)的所有方法，嘗試調(diào)用其中被上面的測(cè)試annotation類(lèi)型標(biāo)注過(guò)的方法。在此過(guò)程中為了找出哪些方法被annotation類(lèi)型標(biāo)注過(guò)，需要使用反射的方式執(zhí)行此查詢(xún)。如果在調(diào)用方法時(shí)拋出異常，此方法被認(rèn)為已經(jīng)失敗，并打印一個(gè)失敗報(bào)告。最后，打印運(yùn)行通過(guò)/失敗的方法數(shù)量。下面文字表示了如何運(yùn)行這個(gè)基于annotation的測(cè)試工具：清單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分類(lèi)：根據(jù)annotation的使用方法和用途主要分為以下幾類(lèi)：1。內(nèi)建Annotation——Java5.0版在java語(yǔ)法中經(jīng)常用到的內(nèi)建Annotation：@Deprecated用于修飾已經(jīng)過(guò)時(shí)的方法；@Override用于修飾此方法覆蓋了父類(lèi)的方法（而非重載）；@SuppressWarnings用于通知java編譯器禁止特定的編譯警告。下面代碼展示了內(nèi)建Annotation類(lèi)型的用法：清單10:package com.bjinfotech.practice.annotation;/** * 演示如何使用java5內(nèi)建的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 { //食物類(lèi) class Food{} //干草類(lèi) class Hay extends Food{} //動(dòng)物類(lèi) class Animal{ Food getFood(){ return null; } //使用Annotation聲明Deprecated方法 @Deprecated void deprecatedMethod(){ } } //馬類(lèi)-繼承動(dòng)物類(lèi) 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。開(kāi)發(fā)者自定義Annotation：由開(kāi)發(fā)者自定義Annotation類(lèi)型。下面是一個(gè)使用annotation進(jìn)行方法測(cè)試的sample：AnnotationDefineForTestFunction類(lèi)型定義如下：清單11:package com.bjinfotech.practice.annotation;import java.lang.annotation.*;/** * 定義annotation * @author cleverpig * *///加載在VM中，在運(yùn)行時(shí)進(jìn)行映射@Retention(RetentionPolicy.RUNTIME)//限定此annotation只能標(biāo)示方法@Target(ElementType.METHOD)public @interface AnnotationDefineForTestFunction{}測(cè)試annotation的代碼如下：清單12:package com.bjinfotech.practice.annotation;import java.lang.reflect.*;/** * 一個(gè)實(shí)例程序應(yīng)用前面定義的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; //被檢測(cè)的類(lèi)名 String className='com.bjinfotech.practice.annotation.UsingAnnotation'; //逐個(gè)檢查此類(lèi)的方法，當(dāng)其方法使用annotation聲明時(shí)調(diào)用此方法 for (Method m : Class.forName(className).getMethods()) { if (m.isAnnotationPresent(AnnotationDefineForTestFunction.class)) { try { m.invoke(null); passed++; } catch (Throwable ex) { System.out.printf('測(cè)試 %s 失敗: %s %n', m, ex.getCause()); failed++; } } } System.out.printf('測(cè)試結(jié)果： 通過(guò): %d, 失敗： %d%n', passed, failed); }}3。使用第三方開(kāi)發(fā)的Annotation類(lèi)型這也是開(kāi)發(fā)人員所常常用到的一種方式。比如我們?cè)谑褂肏ibernate3.0時(shí)就可以利用Annotation生成數(shù)據(jù)表映射配置文件，而不必使用Xdoclet。五、總結(jié)：1。前面的文字說(shuō)明了annotation的使用方法、定義方式、分類(lèi)。初學(xué)者可以通過(guò)以上的說(shuō)明制作簡(jiǎn)單的annotation程序，但是對(duì)于一些高級(jí)的annotation應(yīng)用（例如使用自定義annotation生成javabean映射xml文件）還需要進(jìn)一步的研究和探討。2。同時(shí)，annotation運(yùn)行存在兩種方式：運(yùn)行時(shí)、編譯時(shí)。上文中討論的都是在運(yùn)行時(shí)的annotation應(yīng)用，但在編譯時(shí)的annotation應(yīng)用還沒(méi)有涉及，因?yàn)榫幾g時(shí)的annotation要使用annotation processing tool。涉及以上2方面的深入內(nèi)容，作者將在后文《Java Annotation高級(jí)應(yīng)用》中談到。六、參考資源：·Matrix-Java開(kāi)發(fā)者社區(qū):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 Java, java, J2SE, j2se, J2EE, j2ee, J2ME, j2me, ejb, ejb3, JBOSS, jboss, spring, hibernate, jdo, struts, webwork, ajax, AJAX, mysql, MySQL, Oracle, Weblogic, Websphere, scjp, scjd Java Annotation入門(mén)作者：cleverpig