詳解Java註解教程及自定義註解
自Java5.0版本引入註解之後,它就成為了Java平臺中非常重要的一部分。開發過程中,我們也時常在應用程式碼中會看到諸如@Override,@Deprecated這樣的註解。這篇文章中,我將向大家講述到底什麼是註解,為什麼要引入註解,註解是如何工作的,如何編寫自定義的註解(通過例子),什麼情況下可以使用註解以及最新註解和ADF(應用開發框架)。這會花點兒時間,所以為自己準備一杯咖啡,讓我們來進入註解的世界吧。
什麼是註解?
用一個詞就可以描述註解,那就是元資料,即一種描述資料的資料。所以,可以說註解就是原始碼的元資料。比如,下面這段程式碼:
@Override public String toString() { return "This is String Representation of current object."; }
上面的程式碼中,我重寫了toString()方法並使用了@Override註解。但是,即使我不使用@Override註解標記程式碼,程式也能夠正常執行。那麼,該註解表示什麼?這麼寫有什麼好處嗎?事實上,@Override告訴編譯器這個方法是一個重寫方法(描述方法的元資料),如果父類中不存在該方法,編譯器便會報錯,提示該方法沒有重寫父類中的方法。如果我不小心拼寫錯誤,例如將toString()寫成了toStrring(){double r},而且我也沒有使用@Override註解,那程式依然能編譯執行。但執行結果會和我期望的大不相同。現在我們瞭解了什麼是註解,並且使用註解有助於閱讀程式。
Annotation是一種應用於類、方法、引數、變數、構造器及包宣告中的特殊修飾符。它是一種由JSR-175標準選擇用來描述元資料的一種工具。
為什麼要引入註解?
使用Annotation之前(甚至在使用之後),XML被廣泛的應用於描述元資料。不知何時開始一些應用開發人員和架構師發現XML的維護越來越糟糕了。他們希望使用一些和程式碼緊耦合的東西,而不是像XML那樣和程式碼是鬆耦合的(在某些情況下甚至是完全分離的)程式碼描述。如果你在Google中搜索“XML vs. annotations”,會看到許多關於這個問題的辯論。最有趣的是XML配置其實就是為了分離程式碼和配置而引入的。上述兩種觀點可能會讓你很疑惑,兩者觀點似乎構成了一種迴圈,但各有利弊。下面我們通過一個例子來理解這兩者的區別。
假如你想為應用設定很多的常量或引數,這種情況下,XML是一個很好的選擇,因為它不會同特定的程式碼相連。如果你想把某個方法宣告為服務,那麼使用Annotation會更好一些,因為這種情況下需要註解和方法緊密耦合起來,開發人員也必須認識到這點。
另一個很重要的因素是Annotation定義了一種標準的描述元資料的方式。在這之前,開發人員通常使用他們自己的方式定義元資料。例如,使用標記interfaces,註釋,transient關鍵字等等。每個程式設計師按照自己的方式定義元資料,而不像Annotation這種標準的方式。
目前,許多框架將XML和Annotation兩種方式結合使用,平衡兩者之間的利弊。
Annotation是如何工作的?怎麼編寫自定義的Annotation?
在講述這部分之前,建議你首先下載Annotation的示例程式碼AnnotationsSample.zip 。下載之後放在你習慣使用的IDE中,這些程式碼會幫助你更好的理解Annotation機制。
編寫Annotation非常簡單,可以將Annotation的定義同介面的定義進行比較。我們來看兩個例子:一個是標準的註解@Override,另一個是使用者自定義註解@MethodInfo。
對於@Override註釋你可能有些疑問,它什麼都沒做,那它是如何檢查在父類中有一個同名的函式呢。當然,不要驚訝,我是逗你玩的。@Override註解的定義不僅僅只有這麼一點程式碼。這部分內容很重要,我不得不再次重複:Annotations僅僅是元資料,和業務邏輯無關。理解起來有點困難,但就是這樣。如果Annotations不包含業務邏輯,那麼必須有人來實現這些邏輯。元資料的使用者來做這個事情。Annotations僅僅提供它定義的屬性(類/方法/包/域)的資訊。Annotations的使用者(同樣是一些程式碼)來讀取這些資訊並實現必要的邏輯。
當我們使用Java的標註Annotations(例如@Override)時,JVM就是一個使用者,它在位元組碼層面工作。到這裡,應用開發人員還不能控制也不能使用自定義的註解。因此,我們講解一下如何編寫自定義的Annotations。
我們來逐個講述編寫自定義Annotations的要點。上面的例子中,你看到一些註解應用在註解上。
J2SE5.0版本在 java.lang.annotation提供了四種元註解,專門註解其他的註解:
- @Documented –註解是否將包含在JavaDoc中
- @Retention –什麼時候使用該註解
- @Target? –註解用於什麼地方
- @Inherited – 是否允許子類繼承該註解
@Documented–一個簡單的Annotations標記註解,表示是否將註解資訊新增在java文件中。
@Retention– 定義該註解的生命週期。
RetentionPolicy.SOURCE – 在編譯階段丟棄。這些註解在編譯結束之後就不再有任何意義,所以它們不會寫入位元組碼。@Override, @SuppressWarnings都屬於這類註解。
RetentionPolicy.CLASS – 在類載入的時候丟棄。在位元組碼檔案的處理中有用。註解預設使用這種方式。
RetentionPolicy.RUNTIME– 始終不會丟棄,執行期也保留該註解,因此可以使用反射機制讀取該註解的資訊。我們自定義的註解通常使用這種方式。
@Target – 表示該註解用於什麼地方。如果不明確指出,該註解可以放在任何地方。以下是一些可用的引數。需要說明的是:屬性的註解是相容的,如果你想給7個屬性都添加註解,僅僅排除一個屬性,那麼你需要在定義target包含所有的屬性。
- ElementType.TYPE:用於描述類、介面或enum宣告
- ElementType.FIELD:用於描述例項變數
- ElementType.METHOD
- ElementType.PARAMETER
- ElementType.CONSTRUCTOR
- ElementType.LOCAL_VARIABLE
- ElementType.ANNOTATION_TYPE 另一個註釋
- ElementType.PACKAGE 用於記錄java檔案的package資訊
@Inherited – 定義該註釋和子類的關係
那麼,註解的內部到底是如何定義的呢?Annotations只支援基本型別、String及列舉型別。註釋中所有的屬性被定義成方法,並允許提供預設值。
建立Java自定義註解建立自定義註解和建立一個介面相似,但是註解的interface關鍵字需要以@符號開頭。我們可以為註解宣告方法。我們先來看看註解的例子,然後我們將討論他的一些特性。
package com.journaldev.annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Documented
@Target(ElementType.METHOD)
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface MethodInfo{
String author() default 'Pankaj';
String date();
int revision() default 1;
String comments();
}
註解方法不能帶有引數;
註解方法返回值型別限定為:基本型別、String、Enums、Annotation或者是這些型別的陣列;
註解方法可以有預設值;
註解本身能夠包含元註解,元註解被用來註解其它註解。
我們來看一個java內建註解使用的例子參照上邊提到的自定義註解。
package com.journaldev.annotations;
import java.io.FileNotFoundException;
import java.util.ArrayList;
import java.util.List;
public class AnnotationExample {
public static void main(String[] args) {
}
@Override
@MethodInfo(author = 'Pankaj', comments = 'Main method', date = 'Nov 17 2012', revision = 1)
public String toString() {
return 'Overriden toString method';
}
@Deprecated
@MethodInfo(comments = 'deprecated method', date = 'Nov 17 2012')
public static void oldMethod() {
System.out.println('old method, don't use it.');
}
@SuppressWarnings({ 'unchecked', 'deprecation' })
@MethodInfo(author = 'Pankaj', comments = 'Main method', date = 'Nov 17 2012', revision = 10)
public static void genericsTest() throws FileNotFoundException {
List l = new ArrayList();
l.add('abc');
oldMethod();
}
}
相信這個例子可以不言自明並能展示在不同場景下的應用。
Java註解解析
我們將使用反射技術來解析java類的註解。那麼註解的RetentionPolicy應該設定為RUNTIME否則java類的註解資訊在執行過程中將不可用那麼我們也不能從中得到任何和註解有關的資料。
package com.journaldev.annotations;
import java.lang.annotation.Annotation;
import java.lang.reflect.Method;
public class AnnotationParsing {
public static void main(String[] args) {
try {
for (Method method : AnnotationParsing.class
.getClassLoader()
.loadClass(('com.journaldev.annotations.AnnotationExample'))
.getMethods()) {
// checks if MethodInfo annotation is present for the method
if (method.isAnnotationPresent(com.journaldev.annotations.MethodInfo.class)) {
try {
// iterates all the annotations available in the method
for (Annotation anno : method.getDeclaredAnnotations()) {
System.out.println('Annotation in Method ''+ method + '' : ' + anno);
}
MethodInfo methodAnno = method.getAnnotation(MethodInfo.class);
if (methodAnno.revision() == 1) {
System.out.println('Method with revision no 1 = '+ method);
}
} catch (Throwable ex) {
ex.printStackTrace();
}
}
}
} catch (SecurityException | ClassNotFoundException e) {
e.printStackTrace();
}
}
}
執行上面程式將輸出:
Annotation in Method 'public java.lang.String com.journaldev.annotations.AnnotationExample.toString()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=Main method, date=Nov 17 2012)
Method with revision no 1 = public java.lang.String com.journaldev.annotations.AnnotationExample.toString()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @java.lang.Deprecated()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.oldMethod()' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=1, comments=deprecated method, date=Nov 17 2012)
Method with revision no 1 = public static void com.journaldev.annotations.AnnotationExample.oldMethod()
Annotation in Method 'public static void com.journaldev.annotations.AnnotationExample.genericsTest() throws java.io.FileNotFoundException' : @com.journaldev.annotations.MethodInfo(author=Pankaj, revision=10, comments=Main method, date=Nov 17 2012)
註解用例
註解的功能很強大,Spring和Hebernate這些框架在日誌和有效性中大量使用了註解功能。註解可以應用在使用標記介面的地方。不同的是標記介面用來定義完整的類,但你可以為單個的方法定義註釋,例如是否將一個方法暴露為服務。
在最新的servlet3.0中引入了很多新的註解,尤其是和servlet安全相關的註解。
HandlesTypes –該註解用來表示一組傳遞給ServletContainerInitializer的應用類。
HttpConstraint – 該註解代表所有HTTP方法的應用請求的安全約束,和ServletSecurity註釋中定義的HttpMethodConstraint安全約束不同。
HttpMethodConstraint – 指明不同型別請求的安全約束,和ServletSecurity 註解中描述HTTP協議方法型別的註釋不同。
MultipartConfig –該註解標註在Servlet上面,表示該Servlet希望處理的請求的 MIME 型別是 multipart/form-data。
ServletSecurity 該註解標註在Servlet繼承類上面,強制該HTTP協議請求遵循安全約束。
WebFilter – 該註解用來宣告一個Server過濾器;
WebInitParam – 該註解用來宣告Servlet或是過濾器的中的初始化引數,通常配合 @WebServlet 或者 @WebFilter 使用。
WebListener –該註解為Web應用程式上下文中不同型別的事件宣告監聽器。
WebServlet –該註解用來宣告一個Servlet的配置。
ADF (應用程式框架)和註解
現在我們開始討論文章的最後一部分了。應用程式框架,被稱為ADF,由Oracle開發用來建立Oracle融合應用。我們已經瞭解了註解的優缺點,也知道如何編寫自定義的註解,但我們應該將註解應用在ADF的哪部分呢?ADF是否提供了一些樸素的註解?很好的問題,確實在ADF中大量使用註解有一些限制。之前提到的應用框架如Spring和Hibernate使用AOP(面向側面的程式設計)。在AOP中,框架提供了一種機制,在事件的預處理和後續處理中注入程式碼。例如:你有一個鉤子用來在方法執行之前和之後新增程式碼,所以你可以在這些地方編寫你的使用者程式碼。ADF不使用AOP。如果我們有任何註解的用例可用,我們可能需要通過繼承的方式實現。