設計自己的Annotation Java

設計自己的Annotation Java

Annotation在java的世界正鋪天蓋地展開,有空寫這一篇簡單的annotations的文章,算是關於Annotation入門的文章吧,希望能各位們能拋磚,共同學習......
不講廢話了,實踐才是硬道理.

第一部分:瞭解一下java1.5起預設的三個annotation類型:
一個是@Override:只能用在方法之上的，用來告訴別人這一個方法是改寫父類的。
一個是@Deprecated:建議別人不要使用舊的API的時候用的,編譯的時候會用產生警告資訊,可以設定在程式裡的所有的元素上.
一個是@SuppressWarnings:這一個類型可以來暫時把一些警告資訊訊息關閉.
如果不清楚上面三個類型的具體用法，各位可以baidu或google一下的,很簡單的。

第二部分:講一下annotation的概念先，再來講一下怎樣設計自己的annotation.
首先在jdk內建的java.lang.annotation包裡,開啟如下幾個源檔案:

1、源檔案Target.java

代碼 

1. @Documented  
2. @Retention(RetentionPolicy.RUNTIME)   
3. @Target(ElementType.ANNOTATION_TYPE)   
4. public @interface Target {   
5.    ElementType[] value();   
6. }  

其中的@interface是一個關鍵字，在設計annotations的時候必須把一個類型定義為@interface，而不能用class或interface關鍵字(會不會覺得sun有點吝嗇,偏偏搞得與interface這麼像).

2、源檔案Retention.java 代碼 

1. @Documented  
2. @Retention(RetentionPolicy.RUNTIME)   
3. @Target(ElementType.ANNOTATION_TYPE)   
4. public @interface Retention {   
5.    RetentionPolicy value();   
6. }  

 

看到這裡，大家可能都模糊了,都不知道在說什麼，別急，往下看一下.
在上面的檔案都用到了RetentionPolicy，ElementType這兩個欄位,你可能就會猜到這是兩個java檔案.的確，這兩個檔案的原始碼如下：

3、源檔案RetentionPolicy.java

代碼 

1. public enum RetentionPolicy {   
2.  SOURCE,   
3.  CLASS,   
4.  RUNTIME   
5. }  

這是一個enum類型,共有三個值，分別是SOURCE,CLASS 和 RUNTIME.
SOURCE代表的是這個Annotation類型的資訊只會保留在程式源碼裡，源碼如果經過了編譯之後，Annotation的資料就會消失,並不會保留在編譯好的.class檔案裡面。
ClASS的意思是這個Annotation類型的資訊保留在程式源碼裡,同時也會保留在編譯好的.class檔案裡面,在執行的時候，並不會把這一些資訊載入到虛擬機器(JVM)中去.注意一下，當你沒有設定一個Annotation類型的Retention值時，系統預設值是CLASS.
第三個,是RUNTIME,表示在源碼、編譯好的.class檔案中保留資訊，在執行的時候會把這一些資訊載入到JVM中去的．
　 舉一個例子，如@Override裡面的Retention設為SOURCE,編譯成功了就不要這一些檢查的資訊;相反,@Deprecated裡面的Retention設為RUNTIME,表示除了在編譯時間會警告我們使用了哪個被Deprecated的方法,在執行的時候也可以查出該方法是否被Deprecated.

 

4、源檔案ElementType.java

代碼 

1. public enum ElementType {   
2.  TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR,   
3.  LOCAL_VARIABLE, ANNOTATION_TYPE,PACKAGE   
4. }  

＠Target裡面的ElementType是用來指定Annotation類型可以用在哪一些元素上的.說明一下：TYPE(類型), FIELD(屬性), METHOD(方法), PARAMETER(參數), CONSTRUCTOR(建構函式),LOCAL_VARIABLE(局部變數), ANNOTATION_TYPE,PACKAGE(包),其中的TYPE(類型)是指可以用在Class,Interface,Enum和Annotation類型上.
另外,從1的原始碼可以看出,@Target自己也用了自己來聲明自己,只能用在ANNOTATION_TYPE之上.
如果一個Annotation類型沒有指明@Target使用在哪些元素上,那麼它可以使用在任何元素之上,這裡的元素指的是上面的八種類型.
舉幾個正確的例子:
@Target(ElementType.METHOD)
@Target(value=ElementType.METHOD)
@Target(ElementType.METHOD,ElementType.CONSTRUCTOR)
具體參考一下javadoc文檔

上面一下1和2的源檔案，它們都使用了@Documented,@Documented的目的就是讓這一個Annotation類型的資訊能夠顯示在javaAPI說明文檔上;沒有添加的話，使用javadoc產生API文檔的時候就會找不到這一個類型產生的資訊.
另外一點，如果需要把Annotation的資料繼承給子類，那麼就會用到@Inherited這一個Annotation類型.

第三部分:下面講的設計一個最簡單的Annotation例子,這一例子共用四個檔案;
1、Description.java 代碼 

1. package lighter.javaeye.com;   
2.   
3. import java.lang.annotation.Documented;   
4. import java.lang.annotation.ElementType;   
5. import java.lang.annotation.Retention;   
6. import java.lang.annotation.RetentionPolicy;   
7. import java.lang.annotation.Target;   
8.   
9. @Target(ElementType.TYPE)   
10. @Retention(RetentionPolicy.RUNTIME)   
11. @Documented  
12. public @interface Description {   
13.     String value();   
14. }  

說明:所有的Annotation會自動繼承java.lang.annotation這一個介面,所以不能再去繼承別的類或是介面.
最重要的一點,Annotation類型裡面的參數該怎麼設定:
第一,只能用public或預設(default)這兩個訪問權修飾.例如,String value();這裡把方法設為defaul預設類型.
第二,參數成員只能用基本類型byte,short,char,int,long,float,double,boolean八種基礎資料型別 (Elementary Data Type)和String,Enum,Class,annotations等資料類型,以及這一些類型的數組.例如,String value();這裡的參數成員就為String.
第三,如果只有一個參數成員,參數名稱一定要為"value",後加小括弧.例:上面的例子就只胡一個參數成員.

 

2、Name.java

代碼 

1. package lighter.javaeye.com;   
2.   
3. import java.lang.annotation.Documented;   
4. import java.lang.annotation.ElementType;   
5. import java.lang.annotation.Retention;   
6. import java.lang.annotation.RetentionPolicy;   
7. import java.lang.annotation.Target;   
8.   
9.  //注意這裡的@Target與@Description裡的不同,參數成員也不同   
10. @Target(ElementType.METHOD)   
11. @Retention(RetentionPolicy.RUNTIME)   
12. @Documented  
13. public @interface Name {   
14.     String originate();   
15.     String community();   
16. }  

 

3、JavaEyer.java

代碼 

1. package lighter.javaeye.com;   
2.   
3. @Description("javaeye,做最棒的軟體開發交流社區")   
4. public class JavaEyer {   
5.     @Name(originate="創始人:robbin",community="javaEye")   
6.     public String getName()   
7.     {   
8.         return null;   
9.     }   
10.        
11.     @Name(originate="創始人:江南白衣",community="springside")   
12.     public String getName2()   
13.     {   
14.         return "借用兩位老大的id,寫這一個例子,請見諒!";   
15.     }   
16. }  

4、最後，寫一個可以運行提取JavaEyer資訊的類TestAnnotation 代碼 

1.  package lighter.javaeye.com;   
2.   
3.   import java.lang.reflect.Method;   
4.   import java.util.HashSet;   
5.   import java.util.Set;   
6.   
7.   public class TestAnnotation {   
8.     /**  
9.      * author lighter  
10.      * 說明:具體關天Annotation的API的用法請參見javaDoc文檔  
11.      */  
12.        public static void main(String[] args) throws Exception {   
13.        String  CLASS_NAME = "lighter.javaeye.com.JavaEyer";   
14.        Class  test = Class.forName(CLASS_NAME);   
15.        Method[] method = test.getMethods();   
16.        boolean flag = test.isAnnotationPresent(Description.class);   
17.         if(flag)   
18.         {   
19.             Description des = (Description)test.getAnnotation(Description.class);   
20.             System.out.println("描述:"+des.value());   
21.             System.out.println("-----------------");   
22.         }   
23.            
24.         //把JavaEyer這一類有利用到@Name的全部方法儲存到Set中去   
25.         Set<Method> set = new HashSet<Method>();   
26.         for(int i=0;i<method.length;i++)   
27.         {   
28.             boolean otherFlag = method[i].isAnnotationPresent(Name.class);   
29.             if(otherFlag) set.add(method[i]);   
30.         }   
31.         for(Method m: set)   
32.         {   
33.             Name name = m.getAnnotation(Name.class);   
34.             System.out.println(name.originate());   
35.             System.out.println("建立的社區:"+name.community());   
36.         }   
37.      }   
38. }  

5、運行結果：
描述:javaeye,做最棒的軟體開發交流社區
-----------------
創始人:robbin
建立的社區:javaEye
創始人:江南白衣
建立的社區:springside

 

這一篇文章寫了兩個小時有多啦，也算是一篇關於設計自定的Annotation的入門篇啦；另外，特在處聲明，如果轉載請註明出處：http://lighter.javaeye.com。
參考資料:
1、http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
2、http://caterpillar.onlyfun.net/Gossip/
3、http://calvin.javaeye.com/blog/33210