基礎學習教程: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();
    }

 

 

 清單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 { }

 

 

 在上面的代碼中,@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的測試工具:

 

 清單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的使用方法和用途主要分爲以下幾類:

 

 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.*;

/**
 *
一個實例程序應用前面定義的AnnotationAnnotationDefineForTestFunction
 * @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.

 四、Annotation分類:  這個程序從命令行參數中取出類名,並且遍歷此類的所有方法,嘗試調用其中被上面的測試annotation類型標註過的方法。在此過程中爲了找出哪些方法被annotation類型標註過,需要使用反射的方式執行此查詢。如果在調用方法時拋出異常,此方法被認爲已經失敗,並打印一個失敗報告。最後,打印運行通過/失敗的方法數量。  值得注意的是annotaion類型聲明是可以標註自己的,這樣的annotation被稱爲“meta-annotations”。  更爲方便的是對於具有唯一成員且成員名爲value的annotation(如上文),在其使用時可以忽略掉成員名和賦值號(=):

 

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章