java 註解,從名字上看是註釋,解釋。但功能卻不僅僅是註釋那麼簡單。註解(Annotation) 爲我們在代碼中添加信息提供了一種形式化的方法,是我們可以在稍後 某個時刻方便地使用這些數據(通過 解析註解 來使用這些數據),常見的作用有以下幾種:
- 生成文檔。這是最常見的,也是java 最早提供的註解。常用的有@see @param @return 等
- 跟蹤代碼依賴性,實現替代配置文件功能。比較常見的是spring 2.5 開始的基於註解配置。作用就是減少配置。現在的框架基本都使用了這種配置來減少配置文件的數量。
- 在編譯時進行格式檢查。如@override 放在方法前,如果你這個方法並不是覆蓋了超類方法,則編譯時就能檢查出。
包 java.lang.annotation 中包含所有定義自定義註解所需用到的原註解和接口。如接口 java.lang.annotation.Annotation 是所有註解繼承的接口,並且是自動繼承,不需要定義時指定,類似於所有類都自動繼承Object。
該包同時定義了四個元註解,Documented,Inherited,Target(作用範圍,方法,屬性,構造方法等),Retention(生命範圍,源代碼,class,runtime)。下面將在實例中逐個講解他們的作用,及使用方法。
建第一個註解 : TestA.java
package annotation.test;
/**
*@interface用來聲明一個註解,其中的每一個方法實際上是聲明瞭一個配置參數。
*方法的名稱就是參數的名稱,返回值類型就是參數的類型。
*可以通過default來聲明參數的默認值。
*在這裏可以看到@Retention和@Target這樣的元註解,用來聲明註解本身的行爲。
*@Retention用來聲明註解的保留策略,有CLASS、RUNTIME和SOURCE這三種,
*分別表示註解保存在類文件、JVM運行時刻和源代碼中。
*只有當聲明爲RUNTIME的時候,才能夠在運行時刻通過反射API來獲取到註解的信息。
*@Target用來聲明註解可以被添加在哪些類型的元素上,如類型、方法和域等。
*就可以定義一個註解了,它將自動繼承Annotation
*/
public @interface TestA {
//這裏定義了一個空的註解,它能幹什麼呢。我也不知道,但他能用。 後面有補充
}
在下面這個程序中使用它:UserAnnotation.java
package annotation.test;
import java.util.HashMap;
import java.util.Map;
/**
* 這個類專門用來測試註解使用
* @author tmser
*/
@TestA //使用了類註解
public class UserAnnotation {
@TestA //使用了類成員註解
private Integer age;
@TestA //使用了構造方法註解
public UserAnnotation(){
}
@TestA //使用了類方法註解
public void a(){
@TestA //使用了局部變量註解
Map m = new HashMap(0);
}
public void b(@TestA Integer a){ //使用了方法參數註解
}
}
編譯沒有報錯,ok,一個註解實驗完成。這個註解也太簡單了吧,好像什麼信息也不能傳遞。別急下面就來一步步完善它,也該四位元註解依次開始上場了。
四個元註解分別是:@Target,@Retention,@Documented,@Inherited ,再次強調下元註解是java API提供,是專門用來定義註解的註解,其作用分別如下。
@Target :
表示該註解用於什麼地方,可能的值在枚舉類 ElemenetType 中,包括:
ElemenetType.CONSTRUCTOR 構造器聲明
ElemenetType.FIELD 域聲明(包括 enum 實例)
ElemenetType.LOCAL_VARIABLE 局部變量聲明
ElemenetType.METHOD 方法聲明
ElemenetType.PACKAGE 包聲明
ElemenetType.PARAMETER 參數聲明
ElemenetType.TYPE 類,接口(包括註解類型)或enum聲明
@Retention :
表示在什麼級別保存該註解信息。可選的參數值在枚舉類型 RetentionPolicy 中,包括:
RetentionPolicy.SOURCE 註解將被編譯器丟棄
RetentionPolicy.CLASS 註解在class文件中可用,但會被VM丟棄
RetentionPolicy.RUNTIME VM將在運行期也保留註釋,因此可以通過反射機制讀取註解的信息。
@Documented : 將此註解包含在 javadoc 中 ,它代表着此註解會被javadoc工具提取成文檔。在doc文檔中的內容會因爲此註解的信息內容不同而不同。相當與@see,@param 等。
@Inherited : 在您定義註解後並使用於程序代碼上時,預設上父類別中的註解並不會被繼承至子類別中,您可以在定義註解時加上java.lang.annotation.Inherited 限定的Annotation,這讓您定義的Annotation型別被繼承下來。注意註解繼承只針對class 級別註解有效(這段建議看完全文後在來回顧)。 多說無益,下面就一步步從零開始建一個我們自己的註解。
學習最忌好高騖遠,我們就一個一個來實驗。第一個:@Target,動手在前面我們編寫的註解上加上元註解。
修改註解類 : TestA.java
package annotation.test;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
/*
* 定義註解 Test
* 首先使用ElementType.TYPE
*/
@Target(ElementType.PACKAGE)
public @interface TestA {
}
ctrl+ s 保存,今天電腦比較給力,我們的測試類那邊立馬出現了一堆錯誤,除了類註解。我想到這,聰明的你立刻明白了這個元註解的意義了。是不是想當然的偷起懶來了。?難道還有意外?細心的朋友應該發現了,我們的測試類少了一個屬性沒用,就是ElemenetType.PACKAGE。在我們的註解加上這個屬性的元註解後,我們測試程序的元註解全部陣亡,不對,還有一個沒加呢,好加上。package 包,想當然是加載 package 前面。即
@TestA package annotation.test;
什麼也報錯。這就搞不明白了,不加在這加哪去呢。我也不知道了,不過這是編譯錯誤,我們的eclipse 將錯誤給我們指出了,就是
Package annotations must be in file package-info.java ,e 文雖然不好,但這個簡單的還是難不倒幾個人的,package 註解必須定義在 package-info.java 中。package-info 又是什麼東西,好了爲節省你們的時間幫你百度好了,傳送門。ok,到此 target 元註解就全部完成了。
第二個元註解: @Retention 參數 RetentionPolicy。有了前面的經驗這個註解理解起來就簡單多了,並且幸運的是這個註解還沒有特殊的屬性值。
簡單演示下如何使用:TestA.java
package annotation.test;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
/*
* 定義註解 Test
* 首先使用ElementType.TYPE
* 運行級別定爲 運行時,以便後面測試解析
*/
@Target(ElementType.PACKAGE)
@Retention(RetentionPolicy.RUNTIME)
public @interface TestA {
}
第三和第四個元註解就不再舉例了。比較簡單,也沒有值,相信看過上面的解釋也就清楚了。下面我們還是繼續來深入的探討下註解的使用。上面的例子都非常簡單,註解連屬性都沒有。ok,下面我們就來定義一個有屬性的註解,並在例子程序中獲取都註解中定義的值。
開始之前將下定義屬性的規則:
@interface用來聲明一個註解,其中的每一個方法實際上是聲明瞭一個配置參數。方法的名稱就是參數的名稱,返回值類型就是參數的類型(返回值類型只能是基本類型、Class、String、enum)。可以通過default來聲明參數的默認值。
TestA.java
package annotation.test;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* 定義註解 Test <br>
* 爲方便測試:註解目標爲類 方法,屬性及構造方法<br>
* 註解中含有三個元素 id ,name和 gid; <br>
* id 元素 有默認值 0 <br>
*/
@Target({ElementType.TYPE,ElementType.METHOD,ElementType.FIELD,ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
public @interface TestA {
String name() ;
int id() default 0;
Class<Long> gid();
}
下面改下我們的測試類:UserAnnotation.java
1 package annotation.test;
2
3 import java.util.HashMap;
4 import java.util.Map;
7 /**
8 * 這個類專門用來測試註解使用
9 */
10
11 @TestA(name="type",gid=Long.class)
12 // 使用了類註解
13 public class UserAnnotation {
16 @TestA(name="param",id=1,gid=Long.class) // 使用了類成員註解
17 private Integer age;
18
19 @TestA(name="construct",id=2,gid=Long.class)// 使用了構造方法註解
20 public UserAnnotation() {
22 }
23
24 @TestA(name="public method", id=3, gid=Long.class)// 使用了 public 方法註解
25 public void a() {
26 Map<String, String> m = new HashMap<String, String>(0);
27 }
28
29 @TestA(name="protected method", id=4, gid=Long.class)//protected 方法註解
30 protected void b() {
31 Map<String, String> m = new HashMap<String, String>(0);
32 }
33
34 @TestA(name="private method " , id = 5, gid=Long.class) // private 方法註解
35 private void c(){
36 Map<String, String> m = new HashMap<String, String>(0);
37 }
38
39 public void b(Integer a){
41 }
42 }
下面到了最重要的一步了,就是如何讀取我們在類中定義的註解。只要讀取出來了使用的話就簡單了。
package annotation.test;
import java.lang.annotation.Annotation;
import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
public class ParseAnnotation {
/**
* 簡單打印出UserAnnotation 類中所使用到的類註解
* 該方法只打印了 Type 類型的註解
* @throws ClassNotFoundException
*/
public static void parseTypeAnnotation() throws ClassNotFoundException{
Class clazz = Class.forName("annotation.test.UserAnnotation");
Annotation[] annotations = clazz.getAnnotations();
for (Annotation annotation : annotations) {
TestA testA = (TestA) annotation;
System.out.println("type name = "+clazz.getName() + " | id = " + testA.id() + " | name = " + testA.name() + " | gid = " + testA.gid());
}
}
/**
* 簡單打印出UserAnnotation 類中所使用到的方法註解
* 該方法只打印了 Method 類型的註解
* @throws ClassNotFoundException
*/
public static void parseMethodAnnotation() throws ClassNotFoundException{
Method[] methods = UserAnnotation.class.getDeclaredMethods();
for (Method method : methods) {
/*
* 判斷方法中是否有指定註解類型的註解
*/
boolean hasAnnotation = method.isAnnotationPresent(TestA.class);
if(hasAnnotation){
TestA annotation = method.getAnnotation(TestA.class);
System.out.println("method name = " + method.getName() + " | id = " +
annotation.id() + " | description = " + annotation.name() + " | gid = " + annotation.gid());
}
}
}
/**
* 簡單打印出UserAnnotation 類中所使用到的構造方法註解
* 該方法只打印了 構造方法 類型的註解
* @throws ClassNotFoundException
*/
public static void parseConstructAnnotation() throws ClassNotFoundException{
Constructor[] constructors = UserAnnotation.class.getConstructors();
for (Constructor constructor : constructors) {
/*
* 判斷構造方法中是否有指定註解類型的註解
*/
boolean hasAnnotation = constructor.isAnnotationPresent(TestA.class);
if(hasAnnotation){
/*
* 根據註解類型返回方法的指定類型註解
*/
TestA annotation = (TestA) constructor.getAnnotation(TestA.class);
System.out.println("constructor = " + constructor.getName()
+ " | id = " + annotation.id() + " | description = "
+ annotation.name() + " | gid= "+annotation.gid());
}
}
}
/**
* 簡單打印出UserAnnotation 類中所使用到的字段註解
* 該方法只打印了 Method 類型的註解
* @throws ClassNotFoundException
*/
public static void parseFieldAnnotation() throws ClassNotFoundException{
Field[] fields = UserAnnotation.class.getDeclaredFields();
for (Field field : fields) {
boolean hasAnnotation = field.isAnnotationPresent(TestA.class);
if(hasAnnotation){
TestA annotation = field.getAnnotation(TestA.class);
System.out.println("Field = " + field.getName()
+ " | id = " + annotation.id() + " | description = "
+ annotation.name() + " | gid= "+annotation.gid());
}
}
}
public static void main(String[] args) throws ClassNotFoundException {
System.out.println("------------------------------解析Type註解----------------------------------------------------------");
parseTypeAnnotation();
System.out.println("------------------------------解析Method註解-------------------------------------------------------");
parseMethodAnnotation();
System.out.println("------------------------------解析構造方法(Construct)註解------------------------------------------");
parseConstructAnnotation();
System.out.println("------------------------------解析字段(Field)註解-----------------------------------------------------");
parseFieldAnnotation();
}
}
先別說話,運行:
------------------------------解析Type註解---------------------------------------------------------- |
看到了吧,我們定義的註解都完整的輸出了,你要使用哪個,直接拿去用就好了。
爲了不讓這篇文章打開太慢,我省略了參數註解的解析。其實都大同小異。
另外,我也沒有舉使用例子。因爲我認爲好的教程是講的詳細的同時,還會留有擴展。如果我全部寫出來,而你只是學習的話,那基本不會自己去動腦了,而是複製粘貼運行一遍完事。
最後提醒下:
1. 要用好註解,必須熟悉java 的反射機制,從上面的例子可以看出,註解的解析完全依賴於反射。
2. 不要濫用註解。平常我們編程過程很少接觸和使用註解,只有做設計,且不想讓設計有過多的配置時。