Annotation英文單詞翻譯過來就是註釋註解的意思,實際上它乾的活也確實如此.我們在使用IDE時經常會看見一些@return,@param等樣子的註釋,實際上它就是一種annotation.這裏估計大家都有一個共識,就是無論annotation怎麼使用,它都不會改變程序最終的運行結果,這就是annotaion的特性了.那麼annotation具體有什麼作用呢?我們又該來怎麼使用它呢?
也許大家會注意到,過時的方法往往會帶有一條刪除線,比如
new Date().toLocaleString();
又或者我們寫的一個類如以下片段:
@Override
public String toString(){ return null; }
@Override
public void overrideTest(){ }
實際上,這時IDE會報錯或者警告,但實際上這個類拿去編譯,甚至運行都會毫無問題.但是它如何知道就錯了呢?這就歸功於Annotation註解了.編譯器此時通過反射來獲取這個方法的Annotation,通過Annotation來確認這個方法究竟是幹嘛用的.比如註釋是Override,那麼它就會繼續去檢查父類是否有這個方法可以讓子類來重寫.如果沒有,那麼開發環境就報錯.
實際上還有很多類似的用法,生成doc文檔就是最常見的用法之一.那麼對Annotation有了初步的瞭解後我們接下來就可以介紹一下Annotation了.
Annotation的作用域
SOURCE代表的是這個Annotation類型的信息只會保留在程序源碼裏，源碼如果經過了編譯之後，Annotation的數據就會消失,並不會保留在編譯好的.class文件裏面。
ClASS的意思是這個Annotation類型的信息保留在程序源碼裏,同時也會保留在編譯好的.class文件裏面,在執行的時候，並不會把這一些信息加載到虛擬機(JVM)中去.注意一下，當你沒有設定一個Annotation類型的Retention值時，系統默認值是CLASS.
RUNTIME,表示在源碼、編譯好的.class文件中保留信息，在執行的時候會把這一些信息加載到JVM中去的．
以上三個範圍都是在RetentionPolicy枚舉中定義好的.
public enum RetentionPolicy {
SOURCE,
CLASS,
RUNTIME
}
但是我們具體申明的時候不是直接使用這個枚舉,因爲是註釋申明,所以只能使用註釋的方式,所以jdk又把這個枚舉封裝成了一個註釋@Retention,這個註釋源碼如下
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
RetentionPolicy value();
}
那,這裏可以看到, Annotation可以自己給自己定義使用的,有點奇怪吧…
Annotation的運作範圍
一個annotation不是想在哪用就在哪用的,就好比java中方法必須寫到類裏面一樣,annotation也有自己的定義範圍,規定一個annotation在哪些地方可以去使用他.具體的範圍有如下幾個:
TYPE,
FIELD,
METHOD
PARAMETER
CONSTRUCTOR
LOCAL_VARIABLE
ANNOTATION_TYPE
PACKAGE
這幾個名字不言而喻,type:申明的類型,field:字段, method:方法...等等,這裏就不一一解釋
好無疑問,這裏jdk同樣包裝好了,用的是以一個ElementType枚舉類型
public enum ElementType {
TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR,
LOCAL_VARIABLE, ANNOTATION_TYPE,PACKAGE
}
爲了annotation使用有包裝了一個名爲Target的annotation類型.源碼如下:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
ElementType[] value();
}
上面都找到兩種annotation都提及一個@Documented,@Documented的目的就是讓這一個Annotation類型的信息能夠顯示在javaAPI說明文檔上;沒有添加的話，使用javadoc生成API文檔的時候就會找不到這一個類型生成的信息.
JDK5自帶的幾個Annotation:
@Deprecated用於修飾已經過時的方法；
@Override用於修飾此方法覆蓋了父類的方法（而非重載）；
@SuppressWarnings用於通知java編譯器禁止特定的編譯警告。
以下介紹關於Annotation的用法語法及使用了:
1。類型聲明方式：
通常，應用程序並不是必須定義annotation類型，但是定義annotation類型並非難事。Annotation類型聲明於一般的接口聲明極爲類似，區別只在於它在interface關鍵字前面使用“@”符號。
annotation類型的每個方法聲明定義了一個annotation類型成員，但方法聲明不必有參數或者異常聲明；方法返回值的類型被限制在以下的範圍：primitives、String、Class、enums、annotation和前面類型的數組；方法可以有默認值。
下面是一個簡單的annotation類型聲明：
清單1:
/**
* Describes the Request-For-Enhancement(RFE) that led
* to the presence of the annotated API element.
*/
public @interface RequestForEnhancement {
int id();
String synopsis();
String engineer() default "[unassigned]";
String date(); default "[unimplemented]";
}
代碼中只定義了一個annotation類型RequestForEnhancement。
annotation到底能起什麼作用呢？
1， 編譯工具或其他工具可以根據被附加在代碼裏的annotation信息自動生成配置文件或文檔等外部文件。
比如，sun公司就提供了apt（Annotation Processing Tool）工具，apt工具是一個可以處理annotation的命令行工具，apt提供了在編譯期針對源代碼級別的解析，並可以在解析時生成新的源代碼和其他文件，同時還可以對生成的源代碼進行編譯。
2， 其他程序可以在運行時動態解析將要被執行的程序裏的annotation信息，並根據被附加的annotation信息來執行不同的操作。
比如，EJB3規範就比較廣泛地使用了annotation特性。比如只要在POJO爲class註明@Stateless註釋，EJB容器便會根據此annotation把該POJO註冊爲無狀態的Session Bean。EJB3使用了annotation大大地簡化了EJB的開發和配置過程。我們會在其他文章裏專門介紹EJB Annotation的原理與使用方法，這裏不做詳述。
本文通過一個簡單地例子來說明怎麼在運行期動態解析annotation。Apt工具的使用我們會在近期其他文章裏對其加以介紹。
比如，我們定義了MyAnnotation3註釋：
MyAnnotation3.java
import java.lang.annotation.Annotation;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation3 {
public String value();
public String[] multiValues();
int number() default 0;
}
上面定義了一個名爲MyAnnotation3的註釋。
我們再定義一個GetMyAnnotation類，該類使用了MyAnnotation3註釋：
GetMyAnnotation.java：
import java.lang.annotation.Annotation;
import java.lang.reflect.Field;
import java.lang.reflect.Method;
import javax.ejb.EJB;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import com.test.annotation.MyAnnotation3;
// 爲GetMyAnnotation類附加MyAnnotation3 註釋
@MyAnnotation3(value = "Class GetMyAnnotation", multiValues = {"1","2"})
public class GetMyAnnotation {
// 爲testField1屬性附加MyAnnotation3 註釋
@MyAnnotation3(value = "call testField1", multiValues={"1"}, number = 1)
private String testField1;
// 爲testMethod1方法附加MyAnnotation3 註釋
@MyAnnotation3(value = "call testMethod1", multiValues={"1", "2"}, number = 1)
public void testMethod1() {
}
@Deprecated
@MyAnnotation3(value = "call testMethod2", multiValues={"3", "4", "5"})
public void testMethod2() {
}
}
上面的例子GetMyAnnotation非常簡單，裏面沒有任何功能，但是分別爲類（class），屬性（field），方法（method）申明（附加）了MyAnnotation3 註釋。
下面我們用程序TestMyAnnotation3對GetMyAnnotation裏MyAnnotation3註釋進行解析。
運行時解析annotation
TestMyAnnotation3.java
public static void main(String[] args) {
System.out.println("--Class Annotations--");
if (GetMyAnnotation.class.isAnnotationPresent(MyAnnotation3.class)) {
System.out.println("[GetMyAnnotation].annotation:");
MyAnnotation3 classAnnotation = GetMyAnnotation.class.getAnnotation(MyAnnotation3.class);
printMyAnnotation3(classAnnotation);
}
System.out.println("--Fields Annotations--");
Field [] fields = GetMyAnnotation.class.getDeclaredFields();
for (Field field : fields) {
if (field.isAnnotationPresent(MyAnnotation3.class)) {
System.out.println("[GetMyAnnotation." + field.getName() + "].annotation:");
MyAnnotation3 fieldAnnotation = field.getAnnotation(MyAnnotation3.class);
printMyAnnotation3(fieldAnnotation);
}
}
System.out.println("--Methods Annotations--");
Method[] methods = GetMyAnnotation.class.getDeclaredMethods();
for (Method method : methods) {
System.out.println("[GetMyAnnotation." + method.getName() + "].annotation:");
if (method.isAnnotationPresent(MyAnnotation3.class)) {
MyAnnotation3 methodAnnotation = method.getAnnotation(MyAnnotation3.class);
printMyAnnotation3(methodAnnotation);
}
}
}
private static void printMyAnnotation3(MyAnnotation3 annotation3) {
if (annotation3 == null) {
return;
}
System.out.println("{value=" + annotation3.value());
String multiValues = "";
for (String value: annotation3.multiValues()) {
multiValues += "," + value;
}
System.out.println("multiValues=" + multiValues);
System.out.println("number=" + annotation3.number() + "}");
}
}
輸出：
[GetMyAnnotation].annotation:
{value=Class GetMyAnnotation
multiValues=,1,2
number=0}
--Fields Annotations--
[GetMyAnnotation.testField1].annotation:
{value=call testField1
multiValues=,1
number=1}
--Methods Annotations--
[GetMyAnnotation.testMethod1].annotation:
{value=call testMethod1
multiValues=,1,2
number=1}
[GetMyAnnotation.testMethod2].annotation:
{value=call testMethod2
multiValues=,3,4,5
number=0}
JDK1.5以後的版本提供的跟annotation有關的接口：
boolean isAnnotationPresent(Class<? extends Annotation> annotationClass);
<T extends Annotation> T getAnnotation(Class<T> annotationClass);
Annotation[] getAnnotations();
Annotation[] getDeclaredAnnotations();
}
該接口主要用來取得附加在類（class），構造方法（constructor），屬性（field），方法（method），包（package）上的annotation信息。
JDK1.5與此有關的幾個類都實現了AnnotatedElement接口：
java.lang.reflect.Class,
java.lang.reflect.Constructor,
java.lang.reflect.Field,
java.lang.reflect.Method,
java.lang.reflect.Package
所以可以利用反射（reflection）功能在程序裏動態解析附加的annotation信息。
總結：
本文通過舉例簡單地說明了怎麼動態解析annotation，大家可以舉一反三，利用Java的annotation特性，完成更復雜功能等。