背景知識(shí)：
從JDK5開始提供名為Annotation（注釋）的功能，它被定義為JSR-175規(guī)范。注釋是以“@注釋名”在代碼中存在的，還可以添加一些參數(shù)值，例如：@SuppressWarnings(value="unchecked")。注釋可以附加在package, class, method, field等上面，相當(dāng)于給它們添加了額外的輔助信息，我們可以通過反射機(jī)制編程實(shí)現(xiàn)對(duì)這些元數(shù)據(jù)的訪問。如果沒有外部解析工具等對(duì)其加以解析和處理的情況，本身不會(huì)對(duì)Java的源代碼或class文件等產(chǎn)生任何影響，也不會(huì)對(duì)它們的執(zhí)行產(chǎn)生任何影響。
元數(shù)據(jù)的作用，大致可分為三種：編寫文檔，通過代碼里標(biāo)識(shí)的元數(shù)據(jù)生成文檔；代碼分析，通過代碼里標(biāo)識(shí)的元數(shù)據(jù)對(duì)代碼進(jìn)行分析；編譯檢查，通過代碼里標(biāo)識(shí)的元數(shù)據(jù)讓編譯器能實(shí)現(xiàn)基本的編譯檢查。
JDK5內(nèi)置的基本注釋
JDK5內(nèi)置了一些常用的注釋，可以在編譯時(shí)幫我們捕獲部分編譯錯(cuò)誤，及提示信息，下面介紹下這些注釋的用法：
1、@Override定義在java.lang.Override中，此注釋只適用于修辭方法，表示一個(gè)方法聲明打算重寫超類中的另一個(gè)方法聲明。如果方法利用此注釋類型進(jìn)行注解但沒有重寫超類方法，則編譯器會(huì)生成一條錯(cuò)誤消息。例如我們?yōu)槟愁愔貙憈oString()方法卻寫成了tostring()，并且我們?yōu)樵摲椒ㄌ砑恿?#64;Override注釋；代碼如下：
|
public class OverrideDemo {
@Override
public String tostring() {
return super.toString();
}
}
|
在編譯時(shí)，會(huì)提示以下錯(cuò)誤信息：
|
OverrideTest.java:4: 方法未覆蓋其父類的方法
@Override
^1 錯(cuò)誤
|
2、@Deprecated定義在java.lang.Deprecated中，此注釋可用于修辭方法、屬性、類，表示不鼓勵(lì)程序員使用這樣的元素，通常是因?yàn)樗芪ｋU(xiǎn)或存在更好的選擇。在使用不被贊成的程序元素或在不被贊成的代碼中執(zhí)行重寫時(shí)，編譯器會(huì)發(fā)出警告。使用@Deprecated的示例代碼如下：
|
public class DeprecatedDemo {
public static void main(String[] args) {
DeprecatedClass.DeprecatedMethod();
}
}
class DeprecatedClass {
@Deprecated
public static void DeprecatedMethod() {
// TODO
}
}
|
在編譯時(shí)，會(huì)得到以下提示信息：
|
注意：DeprecatedDemo.java 使用或覆蓋了已過時(shí)的 API。
注意：要了解詳細(xì)信息，請(qǐng)使用 -Xlint:deprecation 重新編譯。
|
如果在編譯時(shí)添加-Xlint:deprecation參數(shù)，我們能更清楚的看到該警告的詳細(xì)信息，如下：
|
DeprecatedDemo.java:6: 警告：[deprecation] SomeClass 中的 DeprecatedMethod() 已過時(shí)
SomeClass.DeprecatedMethod();
^1 警告
|
要注意@Deprecated與@deprecated的區(qū)別，@deprecated是為了生成文檔的需要，例如：
|
class DeprecatedClass {
/**
* @deprecated 此方法已過時(shí)，不建議使用
*/
@Deprecated
public static void DeprecatedMethod() {
// TODO
}
}
|
3、@SuppressWarnings定義在java.lang.SuppressWarnings中，用來抑制編譯時(shí)的警告信息。與前兩個(gè)注釋有所不同，你需要添加一個(gè)參數(shù)才能正確使用，這些參數(shù)值都是已經(jīng)定義好了的，我們選擇性的使用就好了，參數(shù)如下：
|
參數(shù)
|
說明
|
|
deprecation
|
使用了過時(shí)的類或方法時(shí)的警告
|
|
unchecked
|
執(zhí)行了未檢查的轉(zhuǎn)換時(shí)的警告，例如當(dāng)使用集合時(shí)沒有用泛型 (Generics) 來指定集合保存的類型
|
|
fallthrough
|
當(dāng) Switch 程序塊直接通往下一種情況而沒有 Break 時(shí)的警告
|
|
path
|
在類路徑、源文件路徑等中有不存在的路徑時(shí)的警告
|
|
serial
|
當(dāng)在可序列化的類上缺少 serialVersionUID 定義時(shí)的警告
|
|
finally
|
任何 finally 子句不能正常完成時(shí)的警告
|
|
all
|
關(guān)于以上所有情況的警告
|
通過上面的表格，你應(yīng)該了解到每個(gè)參數(shù)的用意了，下面我就以一個(gè)常用的參數(shù)unchecked為例，為你展示如何使用@SuppressWarnings注釋，示例代碼如下：
|
import java.util.List;
import java.util.ArrayList;
public class SuppressWarningsDemo {
public static List cache = new ArrayList();
//@SuppressWarnings(value = "unchecked")
public void add(String data) {
cache.add(data);
}
}
|
當(dāng)我們不使用@SuppressWarnings注釋時(shí)，編譯器就會(huì)有如下提示：
|
注意：SuppressWarningsDemo.java 使用了未經(jīng)檢查或不安全的操作。
注意：要了解詳細(xì)信息，請(qǐng)使用 -Xlint:unchecked 重新編譯。
|
下面我們?nèi)サ?#64;SuppressWarnings(value="unchecked")這一行的注釋符“//”，它會(huì)屏蔽編譯時(shí)的警告信息，這也就是它所要達(dá)到的目的。
另外，由于@SuppressWarnings注釋只有一個(gè)參數(shù)，并且參數(shù)名為value，所以我們可以將上面一句注釋簡寫為@SuppressWarnings("unchecked")；
同時(shí)參數(shù)value可以取多個(gè)值如：@SuppressWarnings(value={"unchecked", "deprecation"})
或@SuppressWarnings({"unchecked", "deprecation"})。
自定義Annotation注釋
1、注釋annotation與接口的異同：
因?yàn)閍nnotation類型是一個(gè)非凡的接口，所以它與接口之間存在著某些差異：
A. Annotation類型使用關(guān)鍵字@interface而不是interface，這個(gè)關(guān)鍵字聲明隱含了一個(gè)信息，它是繼承了java.lang.annotation.Annotation接口，并非聲明了一個(gè)interface。
B. Annotation類型的方法定義是獨(dú)特的、受限制的，方法必須聲明為無參數(shù)、無異常拋出的。這些方法定義了annotation的成員：方法名成為了成員名，而方法返回值成為了成員的類型。而方法返回值類型必須為primitive類型、Class類型、枚舉類型、annotation類型或者由前面類型之一作為元素的一維數(shù)組。方法的后面可以使用default和一個(gè)默認(rèn)數(shù)值來聲明成員的默認(rèn)值，null不能作為成員默認(rèn)值，這與我們?cè)诜莂nnotation類型中定義方法有很大不同。
C. Annotation類型又與接口有著近似之處，它們可以定義常量、靜態(tài)成員類型（比如枚舉類型定義）。Annotation類型也可以如接口一般被實(shí)現(xiàn)或者繼承。
2、自定義注釋的實(shí)例：
下面，我們將看到如何定義annotation類型的例子。它展示了annotation類型聲明以及@interface與interface之間的不同：
|
import java.lang.annotation.*;
/**
* 使用annotation來描述那些被標(biāo)注的成員是不穩(wěn)定的，需要更改
*/
public @interface Unstable {
}
|
下面的另一個(gè)例子只定義了一個(gè)成員。并通過將這個(gè)成員命名為value，使我們可以方便的使用這種annotation的快捷聲明方式：
|
/**
* 使用Author這個(gè)annotation定義在程序中指出代碼的作者
*/
public @interface Author {
/** 返回作者名 */
String value();
}
|
以下的例子更加復(fù)雜。Reviews annotation類型只有一個(gè)成員，但是這個(gè)成員的類型是復(fù)雜的：由Review annotation組成的數(shù)組。Review annotation類型有3個(gè)成員：枚舉類型成員grade、表示Review名稱的字符串類型成員Reviewer、具有默認(rèn)值的字符串類型成員 Comment。
|
/**
* Reviews annotation類型只有一個(gè)成員，
* 但是這個(gè)成員的類型是復(fù)雜的：由Review annotation組成的數(shù)組
*/
@Retention(RetentionPolicy.RUNTIME)
public @interface Reviews {
Review[] value();
}
/**
* Review annotation類型有3個(gè)成員：
* 枚舉類型成員grade、
* 表示Review名稱的字符串類型成員Reviewer、
* 具有默認(rèn)值的字符串類型成員Comment。
*/
public @interface Review {
// 內(nèi)嵌的枚舉類型
public static enum Grade { EXCELLENT, SATISFACTORY, UNSATISFACTORY };
// 下面的方法定義了annotation的成員
Grade grade();
String reviewer();
String comment() default "";
}
|
最后，我們來定義一個(gè)annotation方法用于羅列出類運(yùn)行中所有的unchecked異常。這個(gè) annotation類型將一個(gè)數(shù)組作為了唯一的成員。數(shù)組中的每個(gè)元素都是異常類。為了加強(qiáng)對(duì)未檢查的異常（此類異常都是在運(yùn)行時(shí)拋出）進(jìn)行報(bào)告，我們可以在代碼中對(duì)異常的類型進(jìn)行限制：
|
public @interface UncheckedExceptions {
Class<? extends RuntimeException>[] value();
}
|
Meta-Annotation類型：
Annotation 類型可以被它們自己所標(biāo)注。Java5.0定義了4個(gè)標(biāo)準(zhǔn)的meta-annotation類型，分別是：Target、Retention、Documented、Inherited，它們被用來提供對(duì)其它annotation類型作說明。 這些類型和它們所支持的類在java.lang.annotation包中可以找到。
@Target的用法：指示注釋類型所適用的程序元素的種類。如果注釋類型聲明中不存在 Target 元注釋，則聲明的類型可以用在任一程序元素上。如果存在這樣的元注釋，則編譯器強(qiáng)制實(shí)施指定的使用限制。例如，以下這個(gè)注釋只能用來聲明方法：
@Target(ElementType.METHOD)
public @interface MyAnnotation {
...
}
|
java.lang.annotation.ElementType是一個(gè)枚舉類型，它具有以下定義：
|
ElementType值
|
說明
|
|
ElementType.ANNOTATION_TYPE
|
應(yīng)用于注釋類型聲明
|
|
ElementType.CONSTRUCTOR
|
構(gòu)造方法聲明
|
|
ElementType.FIELD
|
應(yīng)用于字段聲明（包括枚舉常量）
|
|
ElementType.LOCAL_VARIABLE
|
應(yīng)用于局部變量聲明
|
|
ElementType.METHOD
|
應(yīng)用于方法聲明
|
|
ElementType.PACKAGE
|
應(yīng)用于包聲明
|
|
ElementType.PARAMETER
|
應(yīng)用于參數(shù)聲明
|
|
ElementType.TYPE
|
應(yīng)用于類、接口（包括注釋類型）或枚舉聲明
|
@Retention的用法：指示注釋類型的注釋要保留多久。如果注釋類型聲明中不存在 Retention 注釋，則保留策略默認(rèn)為 RetentionPolicy.CLASS，例如：
@ Retention(RetentionPolicy.CLASS)
public @interface MyAnnotation {
...
}
|
java.lang.annotation.RetentionPolicy是一個(gè)枚舉類型，它具有以下定義：
|
RetentionPolicy值
|
說明
|
|
RetentionPolicy.CLASS
|
編譯器將把注釋記錄在類文件中，但在運(yùn)行時(shí) VM 不需要保留注釋
|
|
RetentionPolicy.RUNTIME
|
編譯器將把注釋記錄在類文件中，在運(yùn)行時(shí) VM 將保留注釋，因此可以反射性地讀取
|
|
RetentionPolicy.SOURCE
|
編譯器要丟棄的注釋
|
@Documented的用法：指示某一類型的注釋將通過 javadoc 和類似的默認(rèn)工具進(jìn)行文檔化。應(yīng)使用此類型來注釋這些類型的聲明：其注釋會(huì)影響由其客戶端注釋的元素的使用。如果類型聲明是用 Documented 來注釋的，則其注釋將成為注釋元素的公共 API 的一部分。Documented是一個(gè)沒有成員的注釋。
@Inherited的用法：指示注釋類型自動(dòng)被子類繼承。 Inherited也是一個(gè)沒有成員的注釋。
注意，如果使用@Inherited注釋類以外的任何事物都是無效的。還要注意，此元注釋僅對(duì)從超類繼承注釋有效；對(duì)已實(shí)現(xiàn)接口的注釋無效。