什么是注解
Java Annotation是JDK5.0引入的一種注釋機制，可以為程序的元素（包、類、接口、字段、方法參數、局部變量）加上更直觀的說明，這些說明信息是與程序的業務邏輯無關，大多情況下供指定的工具或框架使用。
Annotation的組成
1、Annotation的架構圖：
分析架構圖：
1個Annotation 和 1個RetentionPolicy關聯。
可以理解為：每1個Annotation對象，都會有唯一的RetentionPolicy屬性。1個Annotation 和 1~n個ElementType關聯。
可以理解為：對于每1個Annotation對象，可以有若干個ElementType屬性。Annotation 有許多實現類，包括：Deprecated, Documented, Inherited, Override等等。
總結：Annotation 的每一個實現類，都和“1個RetentionPolicy關聯”和“1~n個ElementType關聯” 。
2、解析Annotation、ElementType、RetentionPolicy
- Annotation
package java.lang.annotation;
public interface Annotation {
boolean equals(Object obj);
int hashCode();
String toString();
Class<? extends Annotation> annotationType();
}
- ElementType
package java.lang.annotation;
public enum ElementType {
TYPE, /* 類、接口（包括注釋類型）或枚舉聲明 */
FIELD, /* 字段聲明（包括枚舉常量） */
METHOD, /* 方法聲明 */
PARAMETER, /* 參數聲明 */
CONSTRUCTOR, /* 構造方法聲明 */
LOCAL_VARIABLE, /* 局部變量聲明 */
ANNOTATION_TYPE, /* 注釋類型聲明 */
PACKAGE /* 包聲明 */
}
- RetentionPolicy
package java.lang.annotation;
public enum RetentionPolicy {
SOURCE, /* Annotation信息僅存在于編譯器處理期間，編譯器處理完之后就沒有該Annotation信息了 */
CLASS, /* 編譯器將Annotation存儲于類對應的.class文件中。默認行為 */
RUNTIME /* 編譯器將Annotation存儲于class文件中，并且可由JVM讀入 */
}
總結三者之間的關系：
2.1 Annotation 就是個接口
每1個Annotation都與 1個RetentionPolicy關聯，并且與 1～n個ElementType關聯。可以通俗的理解為：每1個Annotation對象，都會有唯一的RetentionPolicy屬性，至于ElementType屬性，則有1~n個。
2.2 ElementType 是Enum枚舉類型，它用來指定Annotation的類型，或者說使用對象的類型
每1個Annotation都與 1～n個ElementType關聯。當Annotation與一個ElementType關聯時，就意味著：Annotation有了一種可以應用的對象。
例如，若一個Annotation對象是METHOD類型，則該Annotation只能用來修飾方法。
2.3 RetentionPolicy 是Enum枚舉類型，它用來指定Annotation的策略。通俗點說，就是不同RetentionPolicy類型的Annotation的作用域不同
每1個Annotation 都只會和 1個RetentionPolicy關聯。
- 若Annotation的類型為 SOURCE，則意味著：Annotation僅存在于編譯器處理期間，編譯器處理完之后，該Annotation就沒用了。
例如，“ @Override ”標志就是一個Annotation。當它修飾一個方法的時候，就意味著該方法覆蓋父類的方法；并且在編譯期間會進行語法檢查！編譯器處理完后，“@Override”就沒有任何作用了。
若Annotation的類型為 CLASS，則意味著：編譯器將Annotation存儲于類對應的.class文件中，它是Annotation的默認行為。
若Annotation的類型為 RUNTIME，則意味著：編譯器將Annotation存儲于class文件中，并且可由JVM讀入。
3、解析java定義的Annotation
理解了上面的3個類的作用之后，我們接下來可以講解Annotation實現類的語法定義了。
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation1 {
}
上面的作用是定義一個Annotation，它的名字是MyAnnotation1。定義了MyAnnotation1之后，我們可以在代碼中通過“@MyAnnotation1”來使用它。其它的，@Documented, @Target, @Retention, @interface都是來修飾MyAnnotation1的。
下面分別說說它們的含義：
-
@interface
使用@interface定義注解時，意味著它實現了java.lang.annotation.Annotation接口，即該注解就是一個Annotation。“定義Annotation時，@interface是必須的。”
注意：它和我們通常的implemented實現接口的方法不同。Annotation接口的實現細節都由編譯器完成。通過@interface定義注解后，該注解不能繼承其他的注解或接口。
-
@Documented
類和方法的Annotation在缺省情況下是不出現在javadoc中的。如果使用@Documented修飾該Annotation，則表示它可以出現在javadoc中。定義Annotation時，@Documented可有可無；若沒有定義，則Annotation不會出現在javadoc中。
-
@Target(ElementType.TYPE)
前面我們說過，ElementType 是Annotation的類型屬性。而@Target的作用，就是來指定Annotation的類型屬性。@Target(ElementType.TYPE) 的意思就是指定該Annotation的類型是ElementType.TYPE。這就意味著，MyAnnotation1是來修飾“類、接口（包括注釋類型）或枚舉聲明”的注解。
定義Annotation時，@Target可有可無。若有@Target，則該Annotation只能用于它所指定的地方；若沒有@Target，則該Annotation可以用于任何地方。
-
@Retention(RetentionPolicy.RUNTIME)
前面我們說過，RetentionPolicy 是Annotation的策略屬性，而@Retention的作用，就是指定Annotation的策略屬性。@Retention(RetentionPolicy.RUNTIME) 的意思就是指定該Annotation的策略是RetentionPolicy.RUNTIME。這就意味著，編譯器會將該Annotation信息保留在.class文件中，并且能被虛擬機讀取。
定義Annotation時，@Retention可有可無。若沒有@Retention，則默認是RetentionPolicy.CLASS。
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進行說明。
3.1 @Deprecated
@Deprecated 的定義如下：
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}
說明：
- @interface -- 它的用來修飾Deprecated，意味著Deprecated實現了java.lang.annotation.Annotation接口；即Deprecated就是一個注解。
- @Documented -- 它的作用是說明該注解能出現在javadoc中。
- @Retention(RetentionPolicy.RUNTIME) -- 它的作用是指定Deprecated的策略是RetentionPolicy.RUNTIME。這就意味著，編譯器會將Deprecated的信息保留在.class文件中，并且能被虛擬機讀取。
- @Deprecated 所標注內容，不再被建議使用。
注意：使用@Deprecated都會出現一橫線，這一橫線是編輯器對@Deprecated的處理。
3.2 @Inherited
@Inherited 的定義如下：
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
說明：
@interface -- 它的用來修飾Inherited，意味著Inherited實現了java.lang.annotation.Annotation接口；即Inherited就是一個注解。
@Documented -- 它的作用是說明該注解能出現在javadoc中。
@Retention(RetentionPolicy.RUNTIME) -- 它的作用是指定Inherited的策略是RetentionPolicy.RUNTIME。這就意味著，編譯器會將Inherited的信息保留在.class文件中，并且能被虛擬機讀取。
@Target(ElementType.ANNOTATION_TYPE) -- 它的作用是指定Inherited的類型是ANNOTATION_TYPE。這就意味著，@Inherited只能被用來標注“Annotation類型”。
-
@Inherited 的含義是，它所標注的Annotation將具有繼承性。
假設，我們定義了某個Annotaion，它的名稱是MyAnnotation，并且MyAnnotation被標注為@Inherited。現在，某個基類使用了MyAnnotation，則此類類具有了注解MyAnnotation；現在，某個子類是繼承了前面的基類，由于MyAnnotation是@Inherited的(具有繼承性)，所以，子類也具有了注解MyAnnotation。
3.3 @SuppressWarnings
@SuppressWarnings 的定義如下：
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
String[] value();
}
說明：
@interface -- 它的用來修飾SuppressWarnings，意味著SuppressWarnings實現了java.lang.annotation.Annotation接口；即SuppressWarnings就是一個注解。
@Retention(RetentionPolicy.SOURCE) -- 它的作用是指定SuppressWarnings的策略是RetentionPolicy.SOURCE。這就意味著，SuppressWarnings信息僅存在于編譯器處理期間，編譯器處理完之后SuppressWarnings就沒有作用了。
-
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE}) -- 它的作用是指定SuppressWarnings的類型同時包括TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE。
TYPE意味著，它能標注“類、接口（包括注釋類型）或枚舉聲明”。
FIELD意味著，它能標注“字段聲明”。
METHOD意味著，它能標注“方法”。
PARAMETER意味著，它能標注“參數”。
CONSTRUCTOR意味著，它能標注“構造方法”。
LOCAL_VARIABLE意味著，它能標注“局部變量”。 String[] value(); 意味著，SuppressWarnings能指定參數
SuppressWarnings 的作用是，讓編譯器對“它所標注的內容”的某些警告保持靜默。例如，"@SuppressWarnings(value={"deprecation", "unchecked"})" 表示對“它所標注的內容”中的 “SuppressWarnings不再建議使用警告”和“未檢查的轉換時的警告”保持沉默
補充：SuppressWarnings 常用的關鍵字的表格:
deprecation -- 使用了不贊成使用的類或方法時的警告
unchecked -- 執行了未檢查的轉換時的警告，例如當使用集合時沒有用泛型 (Generics) 來指定集合保存的類型。
fallthrough -- 當 Switch 程序塊直接通往下一種情況而沒有 Break 時的警告。
path -- 在類路徑、源文件路徑等中有不存在的路徑時的警告。
serial -- 當在可序列化的類上缺少 serialVersionUID 定義時的警告。
finally -- 任何 finally 子句不能正常完成時的警告。
all -- 關于以上所有情況的警告。
4、Annotation 的作用
Annotation 是一個輔助類，它在Junit、Struts、Spring等工具框架中被廣泛使用，在Android平臺上的工具或框架也被廣泛使用，如Retrofit、ButterKnite、Arouter等等。
作用主要有以下幾個方面:
- 生成文檔：通過代碼里標識的元數據生成 javadoc 文檔
- 編譯檢查：通過代碼里標識的元數據讓編譯器在編譯期間進行檢查驗證
- 編譯期動態處理：編譯時通過代碼里標識的元數據動態處理，例如動態生成代碼
- 運行期動態處理：運行時通過代碼里標識的元數據動態處理，例如使用反射注入實例
我們在編程中經常會使用到的Annotation作用有：
4.1 編譯檢查
Annotation具有“讓編譯器進行編譯檢查的作用”。
例如，@SuppressWarnings, @Deprecated和@Override都具有編譯檢查作用。
- 關于@SuppressWarnings和@Deprecated，已經在“第3部分”中詳細介紹過了。這里就不再舉例說明了。
- 若某個方法被 @Override的 標注，則意味著該方法會覆蓋父類中的同名方法。如果有方法被@Override標示，但父類中卻沒有“被@Override標注”的同名方法，則編譯器會報錯。示例如下：
4.2 在反射中使用Annotation
在反射的Class, Method, Field等函數中，有許多于Annotation相關的接口。
這也意味著，我們可以在反射中解析并使用Annotation。
package com.skywang.annotation;
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;
/**
* Annotation在反射函數中的使用示例
*
* @author skywang
* @email kuiwu-wang@163.com
*/
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
String[] value() default "unknown";
}
/**
* Person類。它會使用MyAnnotation注解。
*/
class Person {
/**
* empty()方法同時被 "@Deprecated" 和 “@MyAnnotation(value={"a","b"})”所標注
* (01) @Deprecated，意味著empty()方法，不再被建議使用
* (02) @MyAnnotation, 意味著empty() 方法對應的MyAnnotation的value值是默認值"unknown"
*/
@MyAnnotation
@Deprecated
public void empty(){
System.out.println("\nempty");
}
/**
* sombody() 被 @MyAnnotation(value={"girl","boy"}) 所標注，
* @MyAnnotation(value={"girl","boy"}), 意味著MyAnnotation的value值是{"girl","boy"}
*/
@MyAnnotation(value={"girl","boy"})
public void somebody(String name, int age){
System.out.println("\nsomebody: "+name+", "+age);
}
}
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);
}
}
}
4.3 根據Annotation生成幫助文檔
通過給Annotation注解加上@Documented標簽，能使該Annotation標簽出現在javadoc中。
4.4 能夠幫忙查看查看代碼
通過@Override, @Deprecated等，我們能很方便的了解程序的大致結構。
另外，我們也可以通過自定義Annotation來實現一些功能。
Reference:Java Annotation認知
