Java_Annotation入門.doc

Java Annotation入門 收藏 在開發(fā)Java代碼的時(shí)候，我們總是習(xí)慣于利用注釋來表達(dá)代碼中無法放置的一些東西，其中一些內(nèi)容被JavaDoc用來產(chǎn)生幫助文檔。只有幫助文檔還是不夠的，在越來越多的情況下，注釋中的標(biāo)記用來表達(dá)更多的含義。例如，在使用了xDoclet工具的項(xiàng)目中，特殊用途的各種xDoclet標(biāo)記用于生成新的代碼和對應(yīng)的配置文件， Hibernate也是借助于hibernate開頭的xDocle來生成代碼和文件的。在更多的情況下，單純在代碼中利用注釋部分添加標(biāo)記的做法也顯得不夠用了，這時(shí)候我們通常會(huì)使用Java的屬性文件或一個(gè)在名稱或配置上相對應(yīng)的XML文件來增加描述的能力。在Hiberanate中，使用了與名稱相對應(yīng)的hbm映射文件。這些方式一方面使部分重復(fù)的工作自動(dòng)化了，另一方面也使程序員的維護(hù)負(fù)擔(dān)加重了。原本只需要專注于代碼的工作被不同類型的標(biāo)記和配置文件分了，而且一個(gè)項(xiàng)目中往往要同時(shí)照顧各種的文件。 J2SE 5.0增加的元數(shù)據(jù)功能使我們可以不必再把那些感興趣的信息放在帶“*“的注釋后面藏起來了。元數(shù)據(jù)實(shí)際上是在代碼中添加注釋的方法。J2SE 5O給出了一些注釋，但更重要的是J2SE 5.0設(shè)計(jì)支持了一種新的類型：注釋(Annotation)。開發(fā)者可以自己開發(fā)實(shí)現(xiàn)自己需求的注釋，然后支持其他程序在代碼中使用這些注釋，利用注釋，程序員可以把標(biāo)準(zhǔn)化的信息公開地寫在代碼中。J2SE 5.0的元數(shù)據(jù)目前為各種開發(fā)標(biāo)準(zhǔn)所支持，例如EJB 3o標(biāo)準(zhǔn)就是完全基于J2SE 5.0的元數(shù)據(jù)功能的。一改EJB 21之前版本的復(fù)雜性，利用元數(shù)據(jù)使開發(fā)過程簡捷了，代碼也易讀了很多。上面這兩段引用看來在Java 編程方面一個(gè)新的趨勢是使用元數(shù)據(jù)。簡單地說，元數(shù)據(jù)就是關(guān)于數(shù)據(jù)的數(shù)據(jù)。元數(shù)據(jù)可以用于創(chuàng)建文檔，跟蹤代碼中的依賴性，甚至執(zhí)行基本編譯時(shí)檢查。許多元數(shù)據(jù)工具，如開源工具XDoclet，這些功能已經(jīng)添加到了核心Java 語言中。 現(xiàn)在關(guān)于這方面的資料網(wǎng)上還是不少啊，感覺下面轉(zhuǎn)載的cleverpig的這篇文章對于剛接觸JDK5.0新特性Annotation是個(gè)很好的入門，感謝作者為我們提供了這么好的學(xué)習(xí)資料。（轉(zhuǎn)載）摘要：本文針對java初學(xué)者或者annotation初次使用者全面地說明了annotation的使用方法、定義方式、分類。初學(xué)者可以通過以上的說明制作簡單的annotation程序，但是對于一些高級(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)用還沒有涉及，一、為什么使用Annotation：在JAVA應(yīng)用中，我們常遇到一些需要使用模版代碼。例如，為了編寫一個(gè)JAX-RPC web service，我們必須提供一對接口和實(shí)現(xiàn)作為模版代碼。如果使用annotation對遠(yuǎn)程訪問的方法代碼進(jìn)行修飾的話，這個(gè)模版就能夠使用工具自動(dòng)生成。另外，一些API需要使用與程序代碼同時(shí)維護(hù)的附屬文件。例如，JavaBeans需要一個(gè)BeanInfo Class與一個(gè)Bean同時(shí)使用/維護(hù)，而EJB則同樣需要一個(gè)部署描述符。此時(shí)在程序中使用annotation來維護(hù)這些附屬文件的信息將十分便利而且減少了錯(cuò)誤。二、Annotation工作方式：在5.0版之前的Java平臺(tái)已經(jīng)具有了一些ad hoc annotation機(jī)制。比如，使用transient修飾符來標(biāo)識(shí)一個(gè)成員變量在序列化子系統(tǒng)中應(yīng)被忽略。而deprecated這個(gè)javadoc tag也是一個(gè)ad hoc annotation用來說明一個(gè)方法已過時(shí)。從Java5.0版發(fā)布以來，5.0平臺(tái)提供了一個(gè)正式的annotation功能：允許開發(fā)者定義、使用自己的annoatation類型。此功能由一個(gè)定義annotation類型的語法和一個(gè)描述annotation聲明的語法，讀取annotaion的API，一個(gè)使用annotation修飾的class文件，一個(gè)annotation處理工具（apt）組成。annotation并不直接影響代碼語義，但是它能夠工作的方式被看作類似程序的工具或者類庫，它會(huì)反過來對正在運(yùn)行的程序語義有所影響。annotation可以從源文件、class文件或者以在運(yùn)行時(shí)反射的多種方式被讀取。當(dāng)然annotation在某種程度上使javadoc tag更加完整。一般情況下，如果這個(gè)標(biāo)記對java文檔產(chǎn)生影響或者用于生成java文檔的話，它應(yīng)該作為一個(gè)javadoc tag；否則將作為一個(gè)annotation。三、Annotation使用方法：1。類型聲明方式：通常，應(yīng)用程序并不是必須定義annotation類型，但是定義annotation類型并非難事。Annotation類型聲明于一般的接口聲明極為類似，區(qū)別只在于它在interface關(guān)鍵字前面使用“”符號(hào)。annotation類型的每個(gè)方法聲明定義了一個(gè)annotation類型成員，但方法聲明不必有參數(shù)或者異常聲明；方法返回值的類型被限制在以下的范圍：primitives、String、Class、enums、annotation和前面類型的數(shù)組；方法可以有默認(rèn)值。下面是一個(gè)簡單的annotation類型聲明：清單1:/* * Describes the Request-For-Enhancement(RFE) that led * to the presence of the annotated API element. */public interface RequestForEnhancement intid();String synopsis();String engineer() default unassigned; String date();default unimplemented; 代碼中只定義了一個(gè)annotation類型RequestForEnhancement。2。修飾方法的annotation聲明方式：annotation是一種修飾符，能夠如其它修飾符（如public、static、final）一般使用。習(xí)慣用法是annotaions用在其它的修飾符前面。annotations由“+annotation類型+帶有括號(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è)沒有成員的annotation類型聲明時(shí)，可使用以下方式：清單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中只有唯一一個(gè)成員，則該成員應(yīng)命名為value：清單5:/* * Associates a copyright notice with the annotated API element. */public interface Copyright String value();更為方便的是對于具有唯一成員且成員名為value的annotation（如上文），在其使用時(shí)可以忽略掉成員名和賦值號(hào)（=）：清單6:Copyright(2002 Yoyodyne Propulsion Systems)public class OscillationOverthruster . 3。一個(gè)使用實(shí)例：結(jié)合上面所講的，我們在這里建立一個(gè)簡單的基于annotation測試框架。首先我們需要一個(gè)annotation類型來表示某個(gè)方法是一個(gè)應(yīng)該被測試工具運(yùn)行的測試方法。清單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類型聲明是可以標(biāo)注自己的，這樣的annotation被稱為“meta-annotations”。在上面的代碼中，Retention(RetentionPolicy.RUNTIME)這個(gè)meta-annotation表示了此類型的annotation將被虛擬機(jī)保留使其能夠在運(yùn)行時(shí)通過反射被讀取。而Target(ElementType.METHOD)表示此類型的annotation只能用于修飾方法聲明。下面是一個(gè)簡單的程序，其中部分方法被上面的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(args0).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ù)中取出類名，并且遍歷此類的所有方法，嘗試調(diào)用其中被上面的測試annotation類型標(biāo)注過的方法。在此過程中為了找出哪些方法被annotation類型標(biāo)注過，需要使用反射的方式執(zhí)行此查詢。如果在調(diào)用方法時(shí)拋出異常，此方法被認(rèn)為已經(jīng)失敗，并打印一個(gè)失敗報(bào)告。最后，打印運(yùn)行通過/失敗的方法數(shù)量。下面文字表示了如何運(yùn)行這個(gè)基于annotation的測試工具：清單9:$ java RunTests FooTest 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分類：根據(jù)annotation的使用方法和用途主要分為以下幾類：1。內(nèi)建AnnotationJava5.0版在java語法中經(jīng)常用到的內(nèi)建Annotation：Deprecated用于修飾已經(jīng)過時(shí)的方法；Override用于修飾此方法覆蓋了父類的方法（而非重載）；SuppressWarnings用于通知java編譯器禁止特定的編譯警告。下面代碼展示了內(nèi)建Annotation類型的用法：清單10:package com.bjinfotech.practice.annotation;/* * 演示如何使用java5內(nèi)建的annotation * 參考資料： * /docs/books/tutorial/java/javaOO/annotations.html * /j2se/1.5.0/docs/guide/language/annotations.html * /jgloss/annotations.html * author cleverpig * */import java.util.List;public class UsingBuiltInAnnotation /食物類class Food/干草類class Hay extends Food/動(dòng)物類class AnimalFood getFood()return null;/使用Annotation聲明Deprecated方法Deprecatedvoid deprecatedMethod()/馬類-繼承動(dòng)物類class Horse extends Animal/使用Annotation聲明覆蓋方法OverrideHay getFood()return new Hay();/使用Annotation聲明禁止警告SuppressWarnings(deprecation,unchecked)void callDeprecatedMethod(List horseGroup)Animal an=new Animal();an.deprecatedMethod();horseGroup.add(an);2。開發(fā)者自定義Annotation：由開發(fā)者自定義Annotation類型。下面是一個(gè)使用annotation進(jìn)行方法測試的sample：AnnotationDefineForTestFunction類型定義如下：清單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測試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 Exceptionint pas