1. 程式人生 > >一小時搞明白自定義註解(Annotation)

一小時搞明白自定義註解(Annotation)

*本篇文章已授權微信公眾號 guolin_blog (郭霖)獨家釋出

什麼是註解

        Annotation(註解)就是Java提供了一種元程式中的元素關聯任何資訊和著任何元資料(metadata)的途徑和方法。Annotion(註解)是一個介面,程式可以通過反射來獲取指定程式元素的Annotion物件,然後通過Annotion物件來獲取註解裡面的元資料。

        Annotation(註解)是JDK5.0及以後版本引入的。它可以用於建立文件,跟蹤程式碼中的依賴性,甚至執行基本編譯時檢查。從某些方面看,annotation就像修飾符一樣被使用,並應用於包、類 型、構造方法、方法、成員變數、引數、本地變數的宣告中。這些資訊被儲存在Annotation的“name=value”結構對中。

什麼是metadata元資料

元資料從metadata一詞譯來,就是“關於資料的資料”的意思。

元資料的功能作用有很多,比如:你可能用過Javadoc的註釋自動生成文件。這就是元資料功能的一種。總的來說,元資料可以用來建立文件,跟蹤程式碼的依賴性,執行編譯時格式檢查,代替已有的配置檔案。如果要對於元資料的作用進行分類,目前還沒有明確的定義,不過我們可以根據它所起的作用,大致可分為三類: 
   1. 編寫文件:通過程式碼裡標識的元資料生成文件
   2. 程式碼分析:通過程式碼裡標識的元資料對程式碼進行分析
   3. 編譯檢查:通過程式碼裡標識的元資料讓編譯器能實現基本的編譯檢查

Annotation和Annotation型別

Annotation使用了在java5.0所帶來的新語法,它的行為十分類似public、final這樣的修飾符。每個Annotation具有一個名字和成員個數>=0。每個Annotation的成員具有被稱為name=value對的名字和值(就像javabean一樣),name=value裝載了Annotation的資訊。

Annotation型別定義了Annotation的名字、型別、成員預設值。一個Annotation型別可以說是一個特殊的java介面,它的成員變數是受限制的,而宣告Annotation型別時需要使用新語法。當我們通過java反射api訪問Annotation時,返回值將是一個實現了該 annotation型別介面的物件,通過訪問這個物件我們能方便的訪問到其Annotation成員。後面的章節將提到在java5.0的 java.lang包裡包含的3個標準Annotation型別。

註解的分類

根據註解的引數個數分類:

        1.標記註解,一個沒有成員的Annotation型別被稱為標記註解,這種型別僅僅使用自身的存在與否來為我們提供資訊,比如常見的@Override

        2.單值註解

        3.完整註解

        根據註解使用的方法和用途分類:

        1.JDK內建系統註解

        2.元註解

        3.自定義註解

元註解

元註解的作用就是負責註解其他註解,java 5.0定義了4個meta-annotation型別,用來提供對愛他的annotation型別做說明。

 java.lang.annotation

[email protected]

 [email protected]

 [email protected]

 [email protected]

 @Target

修飾的物件範圍:packages、types(類、介面、列舉、Annotation型別)、型別成員(方法、構造方法、成員變數、列舉值)、方法引數和本地變數(如迴圈變數、catch引數)。

作用:用於描述註解的使用範圍。

ElementType取值:

   1.CONSTRUCTOR:用於描述構造器

                2.FIELD:用於描述域

                3.LOCAL_VARIABLE:用於描述區域性變數

                4.METHOD:用於描述方法

                5.PACKAGE:用於描述包

                6.PARAMETER:用於描述引數

                7.TYPE:用於描述類、介面(包括註解型別) 或enum宣告

                例如:

Name可以註解類的成員變數

@Target(ElementType.FIELD)
@Documented
public @interface Name {
    String value() default "";
}

Person可以註解類、介面(包括註解型別)、或者enum宣告

@Target(ElementType.TYPE)
public @interface Person {
    String value() default "";
}

 @Retention

定義了該Annotation被保留的時間長短:某些Annotation僅出現在原始碼中,而被編譯器丟棄;而另一些卻被編譯在class檔案中;編譯在class檔案中的Annotation可能會被虛擬機器忽略,而另一些在class被裝載時將被讀取(請注意並不影響class的執行,因為Annotation與class在使用上是被分離的)。使用這個meta-Annotation可以對 Annotation的“生命週期”限制。

作用:表示需要在什麼級別儲存該註釋資訊,用於描述註解的生命週期(即:被描述的註解在什麼範圍內有效)

RetentionPoicy取值

1.SOURCE:在原始檔中有效(即原始檔保留)

 2.CLASS:在class檔案中有效(即class保留)

 3.RUNTIME:在執行時有效(即執行時保留)

                例如:

Name註解的RetentionPolicy的值為RUNTIME,這樣註解處理器可以通過反射,獲取到該註解的屬性,從而做一些執行時的邏輯處理。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

@Document

        用於描述其它型別的annotation應該被作為被標註的程式成員的公共API,因此可以被例如javadoc此類的工具文件化。Documented是一個標記註解,沒有成員。

作用:表示需要在什麼級別儲存該註釋資訊,用於描述註解的生命週期(即:被描述的註解在什麼範圍內有效)。

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

 @Inhrited

是一個標記註解,@Inherited闡述了某個被標註的型別是被繼承的。如果一個使用了@Inherited修飾的annotation型別被用於一個class,則這個annotation將被用於該class的子類。

@Inherited annotation型別是被標註過的class的子類所繼承。類並不從它所實現的介面繼承annotation,方法並不從它所過載的方法繼承annotation

當@Inherited annotation型別標註的annotation的Retention是RetentionPolicy.RUNTIME,則反射API增強了這種繼承性。如果我們使用java.lang.reflect去查詢一個@Inherited annotation型別的annotation時,反射程式碼檢查將展開工作:檢查class和其父類,直到發現指定的annotation型別被發現,或者到達類繼承結構的頂層。

自定義註解

使用@interface自定義註解時,自動繼承了java.lang.annotation.Annotation介面,由編譯程式自動完成其他細節。在定義註解時,不能繼承其他的註解或介面。@interface用來宣告一個註解,其中的每一個方法實際上是聲明瞭一個配置引數。方法的名稱就是引數的名稱,返回值型別就是引數的型別(返回值型別只能是基本型別、Class、String、enum)。可以通過default來宣告引數的預設值。

自定義註解格式:

        public @interface 註解名{註解體}

                1.所有基本資料型別(int,float,boolean,byte,double,char,long,short)

                2.String型別

                3.Class型別

                4.enum型別

                5.Annotation型別

                6.以上所有型別的陣列

        Annotation型別裡面的引數該怎麼設定:

                第一,只能用public或預設(default)這兩個訪問權修飾.例如,String value();這裡把方法設為defaul預設型別;   
                第二,引數成員只能用基本型別byte,short,char,int,long,float,double,boolean八種基本資料型別和 String,Enum,Class,annotations等資料型別,以及這一些型別的陣列.例如,String value();這裡的引數成員就為String;  
                第三,如果只有一個引數成員,最好把引數名稱設為"value",後加小括號.例:下面的例子Name註解就只有一個引數成員。 

                例如:

Name姓名註解:

/**
 * Created by mingwei on 12/2/16.
 * <p/>
 * 姓名註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Name {
    String value() default "";
}

Gander性別註解:

/**
 * Created by mingwei on 12/2/16.
 * 性別註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Gender {

    public enum GenderType {
        
        Male("男"),
        Female("女"),
        Other("中性");

        private String genderStr;

        private GenderType(String arg0) {
            this.genderStr = arg0;
        }

        @Override
        public String toString() {
            return genderStr;
        }
    }

    GenderType gender() default GenderType.Male;

}

Profile個人資料註解:

/**
 * Created by mingwei on 12/2/16.
 * 基本資料註解
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Profile {
    /**
     * ID
     *
     * @return
     */
    public int id() default -1;

    /**
     * 身高
     *
     * @return
     */
    public int height() default 0;

    /**
     * 籍貫
     *
     * @return
     */
    public String nativePlace() default "";
}

註解元素的預設值

註解元素必須有確定的值,要麼在定義註解的預設值中指定,要麼在使用註解時指定,非基本型別的註解元素的值不可為null。因此, 使用空字串或0作為預設值是一種常用的做法。這個約束使得處理器很難表現一個元素的存在或缺失的狀態,因為每個註解的宣告中,所有元素都存在,並且都具有相應的值,為了繞開這個約束,我們只能定義一些特殊的值,例如空字串或者負數,一次表示某個元素不存在,在定義註解時,這已經成為一個習慣用法。

註解處理器類庫(java.lang.reflect.AnnotatedElement)

註解元素Java使用Annotation介面來代表程式元素前面的註解,該介面是所有Annotation型別的父介面。除此之外,Java在java.lang.reflect 包下新增了AnnotatedElement介面,該介面代表程式中可以接受註解的程式元素,該介面主要有如下幾個實現類:

Class:類定義

Constructor:構造器定義

Field:累的成員變數定義

Method:類的方法定義

Package:類的包定義

當一個Annotation被定義為執行時Annotation後,改註解才是執行時可見的,當class檔案被裝載時被儲存在class檔案中的Annotation才會被虛擬姐讀取。 AnnotatedElement   

介面提供了以下四個方法來訪問Annotation的資訊:

方法1:<T extends Annotation> T getAnnotation(Class<T> annotationClass): 返回改程式元素上存在的、指定型別的註解,如果該型別註解不存在,則返回null。

方法2:Annotation[] getAnnotations():返回該程式元素上存在的所有註解。

方法3:boolean is AnnotationPresent(Class<?extends Annotation> annotationClass):判斷該程式元素上是否包含指定型別的註解,存在則返回true,否則返回false.

方法4:Annotation[] getDeclaredAnnotations():返回直接存在於此元素上的所有註釋。與此介面中的其他方法不同,該方法將忽略繼承的註釋。(如果沒有註釋直接存在於此元素上,則返回長度為零的一個數組。)該方法的呼叫者可以隨意修改返回的陣列;這不會對其他呼叫者返回的陣列產生任何影響。

我們為前面定義好的自定義註解寫一個簡單的處理器:

/**
 * Created by mingwei on 12/2/16.
 */
public class CustomUtils {

    public static void getInfo(Class<?> clazz) {
        String name = "";
        String gender = "";
        String profile = "";
        Field fields[] = clazz.getDeclaredFields();
        for (Field field : fields) {
            if (field.isAnnotationPresent(Name.class)) {
                Name arg0 = field.getAnnotation(Name.class);
                name = name + arg0.value();
                Log.i("Gmw", "name=" + name);
            }
            if (field.isAnnotationPresent(Gender.class)) {
                Gender arg0 = field.getAnnotation(Gender.class);
                gender = gender + arg0.gender().toString();
                Log.i("Gmw", "gender=" + gender);
            }
            if (field.isAnnotationPresent(Profile.class)) {
                Profile arg0 = field.getAnnotation(Profile.class);
                profile = "[id=" + arg0.id() + ",height=" + arg0.height() + ",nativePlace=" + arg0.nativePlace() + "]";
                Log.i("Gmw", "profile=" + profile);
            }
        }
    }

}

使用自定義註解:

/**
 * Created by mingwei on 12/2/16.
 */
public class Person {

    @Name("阿特羅伯斯")
    private String name;

    @Gender(gender = Gender.GenderType.Male)
    private String gender;

    @Profile(id = 1001, height = 180, nativePlace = "CN")
    private String profile;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getGender() {
        return gender;
    }

    public void setGender(String gender) {
        this.gender = gender;
    }

    public String getProfile() {
        return profile;
    }

    public void setProfile(String profile) {
        this.profile = profile;
    }
}

執行:

CustomUtils.getInfo(Person.class);

輸出:

I/Gmw: gender=男
I/Gmw: name=阿特羅伯斯
I/Gmw: profile=[id=1001,height=180,nativePlace=CN]

----------分割線-----------

參考連結:

http://www.cnblogs.com/peida/archive/2013/04/24/3036689.html

https://www.zhihu.com/question/24401191

http://www.open-open.com/lib/view/open1423558996951.html

相關推薦

no