Java 註解(Annotation)又稱 Java 標註,是 JDK5.0 引入的一種註釋機制。
Java 語言中的類、方法、變量、參數和包等均可以被標註。和 Javadoc 不一樣,Java 標註能夠經過反射獲取標註內容。在編譯器生成類文件時,標註能夠被嵌入到字節碼中。Java 虛擬機能夠保留標註內容,在運行時能夠獲取到標註內容 。 固然它也支持自定義 Java 標註。html
網上不少關於 Java Annotation 的文章,看得人眼花繚亂。Java Annotation 原本很簡單的,結果說的人沒說清楚;弄的看的人更加迷糊。java
我按照本身的思路,對 Annotation 進行了整理。理解 Annotation 的關鍵,是理解 Annotation 的語法和用法,對這些內容,我都進行了詳細說明;理解 Annotation 的語法和用法以後,再看 Annotation 的框架圖,可能有更深入體會。廢話就說這麼多,下面開始對 Annotation 進行說明。若您發現文章中存在錯誤或不足的地方,但願您能指出!編程
內置的註解
Java 定義了一套註解,共有 7 個,3 個在 java.lang 中,剩下 4 個在 java.lang.annotation 中。架構
做用在代碼的註解是框架
@Override - 檢查該方法是不是重載方法。若是發現其父類,或者是引用的接口中並無該方法時,會報編譯錯誤。
@Deprecated - 標記過期方法。若是使用該方法,會報編譯警告。
@SuppressWarnings - 指示編譯器去忽略註解中聲明的警告。
做用在其餘註解的註解(或者說 元註解)是:eclipse
@Retention - 標識這個註解怎麼保存,是隻在代碼中,仍是編入class文件中,或者是在運行時能夠經過反射訪問。
@Documented - 標記這些註解是否包含在用戶文檔中。
@Target - 標記這個註解應該是哪一種 Java 成員。
@Inherited - 標記這個註解是繼承於哪一個註解類(默認 註解並無繼承於任何子類)
從 Java 7 開始,額外添加了 3 個註解:ide
@SafeVarargs - Java 7 開始支持,忽略任何使用參數爲泛型變量的方法或構造函數調用產生的警告。
@FunctionalInterface - Java 8 開始支持,標識一個匿名函數或函數式接口。
@Repeatable - Java 8 開始支持,標識某註解能夠在同一個聲明上使用屢次。
一、Annotation 架構函數
從中,咱們能夠看出:工具
(01) 1 個 Annotation 和 1 個 RetentionPolicy 關聯。code
能夠理解爲:每1個Annotation對象,都會有惟一的RetentionPolicy屬性。
(02) 1 個 Annotation 和 1~n 個 ElementType 關聯。
能夠理解爲:對於每 1 個 Annotation 對象,能夠有若干個 ElementType 屬性。
(03) Annotation 有許多實現類,包括:Deprecated, Documented, Inherited, Override 等等。
Annotation 的每個實現類,都 "和 1 個 RetentionPolicy 關聯" 而且 " 和 1~n 個 ElementType 關聯"。
下面,我先介紹框架圖的左半邊(以下圖),即 Annotation, RetentionPolicy, ElementType;而後在就 Annotation 的實現類進行舉例說明。
二、Annotation 組成部分
java Annotation 的組成中,有 3 個很是重要的主幹類。它們分別是:
Annotation.java
package java.lang.annotation;
public interface Annotation {
boolean equals(Object obj); int hashCode(); String toString(); Class<? extends Annotation> annotationType();
}
ElementType.java
package java.lang.annotation;
public enum ElementType {
TYPE, /* 類、接口(包括註釋類型)或枚舉聲明 */
FIELD, /* 字段聲明(包括枚舉常量) */ METHOD, /* 方法聲明 */ PARAMETER, /* 參數聲明 */ CONSTRUCTOR, /* 構造方法聲明 */ LOCAL_VARIABLE, /* 局部變量聲明 */ ANNOTATION_TYPE, /* 註釋類型聲明 */ PACKAGE /* 包聲明 */
}
RetentionPolicy.java
package java.lang.annotation;
public enum RetentionPolicy {
SOURCE, /* Annotation信息僅存在於編譯器處理期間,編譯器處理完以後就沒有該Annotation信息了 */
CLASS, /* 編譯器將Annotation存儲於類對應的.class文件中。默認行爲 */ RUNTIME /* 編譯器將Annotation存儲於class文件中,而且可由JVM讀入 */
}
說明:
(01) Annotation 就是個接口。
"每 1 個 Annotation" 都與 "1 個 RetentionPolicy" 關聯,而且與 "1~n 個 ElementType" 關聯。能夠通俗的理解爲:每 1 個 Annotation 對象,都會有惟一的 RetentionPolicy 屬性;至於 ElementType 屬性,則有 1~n 個。
(02) ElementType 是 Enum 枚舉類型,它用來指定 Annotation 的類型。
"每 1 個 Annotation" 都與 "1~n 個 ElementType" 關聯。當 Annotation 與某個 ElementType 關聯時,就意味着:Annotation有了某種用途。例如,若一個 Annotation 對象是 METHOD 類型,則該 Annotation 只能用來修飾方法。
(03) RetentionPolicy 是 Enum 枚舉類型,它用來指定 Annotation 的策略。通俗點說,就是不一樣 RetentionPolicy 類型的 Annotation 的做用域不一樣。
"每 1 個 Annotation" 都與 "1 個 RetentionPolicy" 關聯。
a) 若 Annotation 的類型爲 SOURCE,則意味着:Annotation 僅存在於編譯器處理期間,編譯器處理完以後,該 Annotation 就沒用了。 例如," @Override" 標誌就是一個 Annotation。當它修飾一個方法的時候,就意味着該方法覆蓋父類的方法;而且在編譯期間會進行語法檢查!編譯器處理完後,"@Override" 就沒有任何做用了。
b) 若 Annotation 的類型爲 CLASS,則意味着:編譯器將 Annotation 存儲於類對應的 .class 文件中,它是 Annotation 的默認行爲。
c) 若 Annotation 的類型爲 RUNTIME,則意味着:編譯器將 Annotation 存儲於 class 文件中,而且可由JVM讀入。
這時,只須要記住"每 1 個 Annotation" 都與 "1 個 RetentionPolicy" 關聯,而且與 "1~n 個 ElementType" 關聯。學完後面的內容以後,再回頭看這些內容,會更容易理解。
三、java 自帶的 Annotation
理解了上面的 3 個類的做用以後,咱們接下來能夠講解 Annotation 實現類的語法定義了。
1)Annotation 通用定義
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation1 {
}
說明:
上面的做用是定義一個 Annotation,它的名字是 MyAnnotation1。定義了 MyAnnotation1 以後,咱們能夠在代碼中經過 "@MyAnnotation1" 來使用它。 其它的,@Documented, @Target, @Retention, @interface 都是來修飾 MyAnnotation1 的。下面分別說說它們的含義:
(01) @interface
使用 @interface 定義註解時,意味着它實現了 java.lang.annotation.Annotation 接口,即該註解就是一個Annotation。
定義 Annotation 時,@interface 是必須的。
注意:它和咱們一般的 implemented 實現接口的方法不一樣。Annotation 接口的實現細節都由編譯器完成。經過 @interface 定義註解後,該註解不能繼承其餘的註解或接口。
(02) @Documented
類和方法的 Annotation 在缺省狀況下是不出如今 javadoc 中的。若是使用 @Documented 修飾該 Annotation,則表示它能夠出如今 javadoc 中。
定義 Annotation 時,@Documented 無關緊要;若沒有定義,則 Annotation 不會出如今 javadoc 中。
(03) @Target(ElementType.TYPE)
前面咱們說過,ElementType 是 Annotation 的類型屬性。而 @Target 的做用,就是來指定 Annotation 的類型屬性。
@Target(ElementType.TYPE) 的意思就是指定該 Annotation 的類型是 ElementType.TYPE。這就意味着,MyAnnotation1 是來修飾"類、接口(包括註釋類型)或枚舉聲明"的註解。
定義 Annotation 時,@Target 無關緊要。如有 @Target,則該 Annotation 只能用於它所指定的地方;若沒有 @Target,則該 Annotation 能夠用於任何地方。
(04) @Retention(RetentionPolicy.RUNTIME)
前面咱們說過,RetentionPolicy 是 Annotation 的策略屬性,而 @Retention 的做用,就是指定 Annotation 的策略屬性。
@Retention(RetentionPolicy.RUNTIME) 的意思就是指定該 Annotation 的策略是 RetentionPolicy.RUNTIME。這就意味着,編譯器會將該 Annotation 信息保留在 .class 文件中,而且能被虛擬機讀取。
定義 Annotation 時,@Retention 無關緊要。若沒有 @Retention,則默認是 RetentionPolicy.CLASS。
2)java自帶的Annotation
經過上面的示例,咱們能理解:@interface 用來聲明 Annotation,@Documented 用來表示該 Annotation 是否會出如今 javadoc 中, @Target 用來指定 Annotation 的類型,@Retention 用來指定 Annotation 的策略。
理解這一點以後,咱們就很容易理解 java 中自帶的 Annotation 的實現類,即 Annotation 架構圖的右半邊。以下圖:
java 經常使用的 Annotation:
@Deprecated -- @Deprecated 所標註內容,再也不被建議使用。
@Override -- @Override 只能標註方法,表示該方法覆蓋父類中的方法。
@Documented -- @Documented 所標註內容,能夠出如今javadoc中。
@Inherited -- @Inherited只能被用來標註「Annotation類型」,它所標註的Annotation具備繼承性。
@Retention -- @Retention只能被用來標註「Annotation類型」,並且它被用來指定Annotation的RetentionPolicy屬性。
@Target -- @Target只能被用來標註「Annotation類型」,並且它被用來指定Annotation的ElementType屬性。
@SuppressWarnings -- @SuppressWarnings 所標註內容產生的警告,編譯器會對這些警告保持靜默。
因爲 "@Deprecated 和 @Override" 相似,"@Documented, @Inherited, @Retention, @Target" 相似;下面,咱們只對 @Deprecated, @Inherited, @SuppressWarnings 這 3 個 Annotation 進行說明。
2.1) @Deprecated
@Deprecated 的定義以下:
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}
說明:
(01) @interface -- 它的用來修飾 Deprecated,意味着 Deprecated 實現了 java.lang.annotation.Annotation 接口;即 Deprecated 就是一個註解。 (02) @Documented -- 它的做用是說明該註解能出如今 javadoc 中。
(03) @Retention(RetentionPolicy.RUNTIME) -- 它的做用是指定 Deprecated 的策略是 RetentionPolicy.RUNTIME。這就意味着,編譯器會將Deprecated 的信息保留在 .class 文件中,而且能被虛擬機讀取。
(04) @Deprecated 所標註內容,再也不被建議使用。
例如,若某個方法被 @Deprecated 標註,則該方法再也不被建議使用。若是有開發人員試圖使用或重寫被 @Deprecated 標示的方法,編譯器會給相應的提示信息。示例以下:
DeprecatedTest.java
import java.util.Date;
import java.util.Calendar;
public class DeprecatedTest {
// @Deprecated 修飾 getString1(),表示 它是建議不被使用的函數
@Deprecated
private static void getString1(){
System.out.println("Deprecated Method");
}
private static void getString2(){ System.out.println("Normal Method"); } // Date是日期/時間類。java已經不建議使用該類了 private static void testDate() { Date date = new Date(113, 8, 25); System.out.println(date.getYear()); } // Calendar是日期/時間類。java建議使用Calendar取代Date表示"日期/時間" private static void testCalendar() { Calendar cal = Calendar.getInstance(); System.out.println(cal.get(Calendar.YEAR)); } public static void main(String[] args) { getString1(); getString2(); testDate(); testCalendar(); }
}
說明:
上面是 eclipse 中的截圖,比較類中 "getString1() 和 getString2()" 以及 "testDate() 和 testCalendar()" 。
(01) getString1() 被 @Deprecated 標註,意味着建議再也不使用 getString1(); 因此 getString1() 的定義和調用時,都會一橫線。這一橫線是eclipse() 對 @Deprecated 方法的處理。
getString2() 沒有被 @Deprecated 標註,它的顯示正常。
(02) testDate() 調用了 Date 的相關方法,而 java 已經建議再也不使用 Date 操做日期/時間。所以,在調用 Date的API 時,會產生警告信息,途中的 warnings。
testCalendar() 調用了 Calendar 的 API 來操做日期/時間,java 建議用 Calendar 取代 Date。所以,操做 Calendar 不回產生 warning。
2.2) @Inherited
@Inherited 的定義以下:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
說明:
(01) @interface -- 它的用來修飾 Inherited,意味着 Inherited 實現了 java.lang.annotation.Annotation 接口;即 Inherited 就是一個註解。
(02) @Documented -- 它的做用是說明該註解能出如今 javadoc 中。
(03) @Retention(RetentionPolicy.RUNTIME) -- 它的做用是指定 Inherited 的策略是 RetentionPolicy.RUNTIME。這就意味着,編譯器會將 Inherited 的信息保留在 .class 文件中,而且能被虛擬機讀取。
(04) @Target(ElementType.ANNOTATION_TYPE) -- 它的做用是指定 Inherited 的類型是 ANNOTATION_TYPE。這就意味着,@Inherited 只能被用來標註 "Annotation 類型"。
(05) @Inherited 的含義是,它所標註的Annotation將具備繼承性。
假設,咱們定義了某個 Annotaion,它的名稱是 MyAnnotation,而且 MyAnnotation 被標註爲 @Inherited。如今,某個類 Base 使用了
MyAnnotation,則 Base 具備了"具備了註解 MyAnnotation";如今,Sub 繼承了 Base,因爲 MyAnnotation 是 @Inherited的(具備繼承性),因此,Sub 也 "具備了註解 MyAnnotation"。
@Inherited 的使用示例:
InheritableSon.java
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
/**
@Inheritable
class InheritableFather
{
public InheritableFather() {
// InheritableBase是否具備 Inheritable Annotation
System.out.println("InheritableFather:"+InheritableFather.class.isAnnotationPresent(Inheritable.class));
}
}
/**
InheritableSon 類只是繼承於 InheritableFather,
*/
public class InheritableSon extends InheritableFather
{
public InheritableSon() {
super(); // 調用父類的構造函數
// InheritableSon類是否具備 Inheritable Annotation
System.out.println("InheritableSon:"+InheritableSon.class.isAnnotationPresent(Inheritable.class));
}
public static void main(String[] args)
{
InheritableSon is = new InheritableSon();
}
}
運行結果:
InheritableFather:true
InheritableSon:true
如今,咱們對 InheritableSon.java 進行修改:註釋掉 "Inheritable 的 @Inherited 註解"。
InheritableSon.java
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
/**
@Inheritable
class InheritableFather
{
public InheritableFather() {
// InheritableBase是否具備 Inheritable Annotation
System.out.println("InheritableFather:"+InheritableFather.class.isAnnotationPresent(Inheritable.class));
}
}
/**
InheritableSon 類只是繼承於 InheritableFather,
*/
public class InheritableSon extends InheritableFather
{
public InheritableSon() {
super(); // 調用父類的構造函數
// InheritableSon類是否具備 Inheritable Annotation
System.out.println("InheritableSon:"+InheritableSon.class.isAnnotationPresent(Inheritable.class));
}
public static void main(String[] args)
{
InheritableSon is = new InheritableSon();
}
}
運行結果:
InheritableFather:true
InheritableSon:false
對比上面的兩個結果,咱們發現:當註解 Inheritable 被 @Inherited 標註時,它具備繼承性。不然,沒有繼承性。
2.3) @SuppressWarnings
@SuppressWarnings 的定義以下:
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
String[] value();
}
說明:
(01) @interface -- 它的用來修飾 SuppressWarnings,意味着 SuppressWarnings 實現了 java.lang.annotation.Annotation 接口;即 SuppressWarnings 就是一個註解。
(02) @Retention(RetentionPolicy.SOURCE) -- 它的做用是指定 SuppressWarnings 的策略是 RetentionPolicy.SOURCE。這就意味着,SuppressWarnings 信息僅存在於編譯器處理期間,編譯器處理完以後 SuppressWarnings 就沒有做用了。
(03) @Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE}) -- 它的做用是指定 SuppressWarnings 的類型同時包括TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE。
TYPE 意味着,它能標註"類、接口(包括註釋類型)或枚舉聲明"。
FIELD 意味着,它能標註"字段聲明"。
METHOD 意味着,它能標註"方法"。
PARAMETER 意味着,它能標註"參數"。
CONSTRUCTOR 意味着,它能標註"構造方法"。
LOCAL_VARIABLE 意味着,它能標註"局部變量"。
(04) String[] value(); 意味着,SuppressWarnings 能指定參數
(05) SuppressWarnings 的做用是,讓編譯器對"它所標註的內容"的某些警告保持靜默。例如,"@SuppressWarnings(value={"deprecation", "unchecked"})" 表示對"它所標註的內容"中的 "SuppressWarnings 再也不建議使用警告"和"未檢查的轉換時的警告"保持沉默。示例以下:
SuppressWarningTest.java
import java.util.Date;
public class SuppressWarningTest {
//@SuppressWarnings(value={"deprecation"}) public static void doSomething(){ Date date = new Date(113, 8, 26); System.out.println(date); } public static void main(String[] args) { doSomething(); }
}
說明:
(01) 左邊的圖中,沒有使用 @SuppressWarnings(value={"deprecation"}) , 而 Date 屬於 java 再也不建議使用的類。所以,調用 Date 的 API 時,會產生警告。而右邊的途中,使用了 @SuppressWarnings(value={"deprecation"})。所以,編譯器對"調用 Date 的 API 產生的警告"保持沉默。
補充:SuppressWarnings 經常使用的關鍵字的表格
deprecation -- 使用了不同意使用的類或方法時的警告
unchecked -- 執行了未檢查的轉換時的警告,例如當使用集合時沒有用泛型 (Generics) 來指定集合保存的類型。
fallthrough -- 當 Switch 程序塊直接通往下一種狀況而沒有 Break 時的警告。
path -- 在類路徑、源文件路徑等中有不存在的路徑時的警告。
serial -- 當在可序列化的類上缺乏 serialVersionUID 定義時的警告。
finally -- 任何 finally 子句不能正常完成時的警告。
all -- 關於以上全部狀況的警告。
四、Annotation 的做用
Annotation 是一個輔助類,它在 Junit、Struts、Spring 等工具框架中被普遍使用。
咱們在編程中常常會使用到的 Annotation 做用有:
1)編譯檢查
Annotation 具備"讓編譯器進行編譯檢查的做用"。
例如,@SuppressWarnings, @Deprecated 和 @Override 都具備編譯檢查做用。
(01) 關於 @SuppressWarnings 和 @Deprecated,已經在"第3部分"中詳細介紹過了。這裏就再也不舉例說明了。
(02) 若某個方法被 @Override 的標註,則意味着該方法會覆蓋父類中的同名方法。若是有方法被 @Override 標示,但父類中卻沒有"被 @Override 標註"的同名方法,則編譯器會報錯。示例以下:
OverrideTest.java
public class OverrideTest {
/** * toString() 在java.lang.Object中定義; * 所以,這裏用 @Override 標註是對的。 */ @Override public String toString(){ return "Override toString"; } /** * getString() 沒有在OverrideTest的任何父類中定義; * 可是,這裏卻用 @Override 標註,所以會產生編譯錯誤! */ @Override public String getString(){ return "get toString"; } public static void main(String[] args) { }
}
上面是該程序在 eclipse 中的截圖。從中,咱們能夠發現 "getString()" 函數會報錯。這是由於 "getString() 被 @Override 所標註,但在OverrideTest 的任何父類中都沒有定義 getString1() 函數"。
"將 getString() 上面的 @Override註釋掉",便可解決該錯誤。
2) 在反射中使用 Annotation
在反射的 Class, Method, Field 等函數中,有許多於 Annotation 相關的接口。
這也意味着,咱們能夠在反射中解析並使用 Annotation。
AnnotationTest.java
import java.lang.annotation.Annotation;
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
import java.lang.reflect.Method;
/**
/**
Person類。它會使用MyAnnotation註解。
*/
class Person {
public class AnnotationTest {
public static void main(String[] args) throws Exception { // 新建Person Person person = new Person(); // 獲取Person的Class實例 Class<Person> c = Person.class; // 獲取 somebody() 方法的Method實例 Method mSomebody = c.getMethod("somebody", new Class[]{String.class, int.class}); // 執行該方法 mSomebody.invoke(person, new Object[]{"lily", 18}); iteratorAnnotations(mSomebody); // 獲取 somebody() 方法的Method實例 Method mEmpty = c.getMethod("empty", new Class[]{}); // 執行該方法 mEmpty.invoke(person, new Object[]{}); iteratorAnnotations(mEmpty); } public static void iteratorAnnotations(Method method) { // 判斷 somebody() 方法是否包含MyAnnotation註解 if(method.isAnnotationPresent(MyAnnotation.class)){ // 獲取該方法的MyAnnotation註解實例 MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class); // 獲取 myAnnotation的值,並打印出來 String[] values = myAnnotation.value(); for (String str:values) System.out.printf(str+", "); System.out.println(); } // 獲取方法上的全部註解,並打印出來 Annotation[] annotations = method.getAnnotations(); for(Annotation annotation : annotations){ System.out.println(annotation); } }
}
運行結果:
somebody: lily, 18
girl, boy,
@com.skywang.annotation.MyAnnotation(value=[girl, boy])
empty
unknown,
@com.skywang.annotation.MyAnnotation(value=[unknown])
@java.lang.Deprecated()
3) 根據 Annotation 生成幫助文檔
經過給 Annotation 註解加上 @Documented 標籤,能使該 Annotation 標籤出如今 javadoc 中。
4) 可以幫忙查看查看代碼
經過 @Override, @Deprecated 等,咱們能很方便的瞭解程序的大體結構。
另外,咱們也能夠經過自定義 Annotation 來實現一些功能。
原文地址:https://www.cnblogs.com/skywang12345/p/3344137.html