一小時搞明白自定義註解(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
@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