Annotation的分類
注解為JDK1.5引入的新內(nèi)容，調(diào)用形式為@Annotation找田。
注解的本質(zhì)是接口缠诅。
注解不影響Java代碼的執(zhí)行。但在運(yùn)行時(shí)拂封，可以通過(guò)一些手段例如反射，獲取注解的信息鹦蠕，并對(duì)其進(jìn)行處理冒签。
Annotation分為如下3類：
- JDK系統(tǒng)注解
- 元注解
- 自定義注解
JDK系統(tǒng)注解
@Override
@Override注解只能使用在方法上。它用來(lái)標(biāo)識(shí)出該方法是用來(lái)重寫(xiě)或?qū)崿F(xiàn)父類或者接口方法的钟病。例如：
class A {
public void fun1() {}
}
class B extends A {
@Override // 重寫(xiě)A的fun1方法
public void fun1() {}
}
interface I {
void fun2();
}
class C implements I {
@Override // 實(shí)現(xiàn)接口I的fun2方法
public void fun2() {}
}
下面問(wèn)題來(lái)了萧恕，大家會(huì)發(fā)現(xiàn)，如果刪除上面例子中的@Override注解档悠，代碼并不會(huì)有任何錯(cuò)誤廊鸥。那么要這個(gè)注解有什么用呢？
有這么一個(gè)例子辖所，我們寫(xiě)了一個(gè)Student類惰说，需要重寫(xiě)它的toString方法：
class Student {
private String name;
private int age;
// 省略setter和getter
public String tostring() { //這里大家發(fā)現(xiàn)問(wèn)題了嗎？
return "name: " + this.name + " age: " + this.age;
}
}
很不幸的是這里程序員粗心的把toString寫(xiě)成了tostring缘回。但是IDE不會(huì)有任何錯(cuò)誤提示吆视。IDE認(rèn)為我們的意圖是定義一個(gè)新方法tostring，而不是去重寫(xiě)方法toString酥宴。
我們嘗試在錯(cuò)誤的tostring方法上加入override注解：
@Override
public String tostring() {
return "name: " + this.name + " age: " + this.age;
}
編輯器會(huì)有如下錯(cuò)誤提示：
到這里大家一定都意識(shí)到@Override注解的重要性了吧啦吧。
這里總結(jié)一下，如果定義方法的目的就是為了實(shí)現(xiàn)或重寫(xiě)其他方法拙寡，務(wù)必要加上@Override注解授滓。
@Deprecated
如果一個(gè)方法有了更好的替代品，為了兼容性暫時(shí)保留但是不建議其他人繼續(xù)使用需要怎么辦肆糕？這時(shí)候@Deprecated注解派上用場(chǎng)了般堆。調(diào)用被@Deprecated修飾的方法會(huì)得到編輯器的警告，同時(shí)會(huì)被標(biāo)記為刪除線：
@SuppressWarnnings
編譯器很聰明會(huì)自動(dòng)檢查代碼中的問(wèn)題給予我們警告诚啃。接著上面的例子淮摔，如果我們確實(shí)需要調(diào)用一個(gè)被標(biāo)記為deprecated的方法，又不想忍受編輯器的警告始赎，難道就沒(méi)有辦法了嗎和橙？@SupressWarnings可以幫我們這個(gè)忙。
我們發(fā)現(xiàn)加入了@SuppressWarnings注解后造垛，編譯器的告警消失魔招，并且對(duì)deprecated方法的調(diào)用也不會(huì)被標(biāo)記上刪除線。
@FunctionalInterface
該注解為Java 8 之后新增加的注解筋搏，目的是為了配合新增加的lambda表達(dá)式使用仆百。具體Lambda表達(dá)式如何使用在這里暫不介紹，請(qǐng)關(guān)注本人其他的博客奔脐。
Java 8 新增加的Lambda表達(dá)式體現(xiàn)了函數(shù)式編程的思想俄周，本質(zhì)上仍然是一個(gè)匿名內(nèi)部類吁讨，但是該匿名內(nèi)部類中只能有一個(gè)未實(shí)現(xiàn)的方法。
為了約束接口中的抽象方法數(shù)量峦朗，引入了@FunctionalInterface接口
其作用為被該注解修飾的接口建丧，里面的抽象方法有且只能有一個(gè)。如果不符合條件會(huì)給出警告波势。
public class Demo {
public static void main(String[] args) {
MyList<String> myList = new MyList<>();
myList.addItems(Arrays.asList("abc", "def", "ghi"));
// 使用Lambda表達(dá)式
myList.myForEach(s -> {
String uppercaseString = s.toUpperCase();
System.out.println(uppercaseString);
});
}
}
class MyList<T> {
private List<T> list = new ArrayList<>();
public void addItems(List<T> itemList) {
list.addAll(itemList);
}
// 傳入實(shí)現(xiàn)了MyForEachFunction接口的對(duì)象翎朱。使用該方法可以傳入lambda表達(dá)式
public void myForEach(MyForEachFunction<T> fun) {
for (T t : list) {
fun.doForEach(t);
}
}
}
@FunctionalInterface
interface MyForEachFunction<T> {
void doForEach(T t); // 只能有一個(gè)抽象方法
}
元注解
元注解為修飾其他注解的注解，在創(chuàng)建自定義注解的時(shí)候及其有用尺铣。下面我們介紹下JDK中的元注解拴曲。
@Retention
@Retention指明注解是如何被存儲(chǔ)的。其參數(shù)有3個(gè)選項(xiàng)：
- RetentionPolicy.SOURCE 僅在源代碼中出現(xiàn)凛忿，注解會(huì)被編譯器忽略澈灼。
- RetentionPolicy.CLASS 該注解在編譯時(shí)會(huì)被編譯器讀取。但會(huì)被JVM忽略店溢。
- RetentionPolicy.RUNTIME 注解在運(yùn)行時(shí)會(huì)被JVM獲取到叁熔。能夠使用Java的反射API讀取。這個(gè)選項(xiàng)使用的最為廣泛床牧。
@Target
@Target是用來(lái)限制注解使用的范圍荣回。它的參數(shù)是ElementType。下面貼出ElementType的代碼：
public enum ElementType {
/** Class, interface (including annotation type), or enum declaration */
// 用于修飾class戈咳， interface心软，@interface和enum類型聲明
TYPE,
/** Field declaration (includes enum constants) */
// 修飾成員變量，包括enum中的常量
FIELD,
/** Method declaration */
// 方法聲明
METHOD,
/** Formal parameter declaration */
// 參數(shù)聲明著蛙，比如Spring MVC中的@RequestParam
PARAMETER,
/** Constructor declaration */
// 構(gòu)造函數(shù)
CONSTRUCTOR,
/** Local variable declaration */
// 局部變量
LOCAL_VARIABLE,
/** Annotation type declaration */
// 注解類型聲明
ANNOTATION_TYPE,
/** Package declaration */
// 包聲明
PACKAGE,
/**
* Type parameter declaration
*
* @since 1.8
*/
// 用于泛型類型糯累，例如class A<@Annotation T> {}
TYPE_PARAMETER,
/**
* Use of a type
*
* @since 1.8
*/
// 經(jīng)試驗(yàn)，除了package和返回值為void的方法册踩，其他位置都可以使用
TYPE_USE
}
@Documented
@Documented注解表明使用Java Doc工具的時(shí)候，被該注解修飾的注解會(huì)出現(xiàn)在生成的Javadoc中效拭。
@Inherited
標(biāo)記為@Inherited的注解暂吉，修飾的class被其他類繼承之時(shí)，該注解能夠一并繼承過(guò)去缎患。下面以一段代碼為例：
定義一個(gè)annotation
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Inherited //啟用了注解繼承
public @interface MyAnnotation {
}
public class Test {
public static void main(String[] args) {
System.out.println(B.class.isAnnotationPresent(MyAnnotation.class)); //@MyAnnotation修飾的是class A慕的，class B繼承自class A，因此class B是被MyAnnotation修飾的
if (B.class.isAnnotationPresent(MyAnnotation.class)) {
MyAnnotation annotation1 = B.class.getDeclaredAnnotation(MyAnnotation.class);
System.out.println(annotation1); //返回null挤渔。B沒(méi)有直接被MyAnnotation修飾
MyAnnotation annotation2 = B.class.getAnnotation(MyAnnotation.class);
System.out.println(annotation2); //返回@com.paultech.MyAnnotation()肮街。
}
}
}
@MyAnnotation
class A {
}
class B extends A {
}
@Repeatable
@Repeatable表示該注解可以修飾同一元素多次。即能夠像如下這種方式使用：
@Descripor("Hello")
@Descripor("World")
class SomeClass {}
下面介紹下如何定義自己的repeatable注解判导。
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(DoSomethingList.class) //需要指定一個(gè)容器注解
@interface DoSomething {
}
@Retention(RetentionPolicy.RUNTIME)
@interface DoSomethingList {
DoSomething[] value(); // 這里必須為value
}
通過(guò)反射獲取注解：
@DoSomething
@DoSomething //這里使用兩個(gè)DoSomething
public class RepeatableTest {
public static void main(String[] args) {
DoSomething[] declaredAnnotationsByType = RepeatableTest.class.getDeclaredAnnotationsByType(DoSomething.class);
System.out.println(declaredAnnotationsByType.length); // 輸出為2
}
}
自定義注解
Annotation的定義
注解使用@interface 定義嫉父，語(yǔ)法如下：
public @interface MyAnnotation {
// ...屬性定義
}
屬性定義的語(yǔ)法為：
類型 字段名() [default] [defaultValue]
例如：
public @interface MyAnnotation {
String value();
}
使用value作為屬性名比較特殊沛硅，調(diào)用時(shí)可以顯式指定屬性名，也可以不指定：
@MyAnnotation(value = "Hello") // 顯式指定value
class SomeClass {}
@MyAnnotation("world") // 不指定绕辖，默認(rèn)為value屬性
class AnotherClass {}
有一點(diǎn)需要格外注意的是摇肌，屬性定義的字段類型必須為Java基本數(shù)據(jù)類型，再加上String和注解類型本身仪际，或者他們的數(shù)組围小。
@interface Something {
String[] strArr(); // String數(shù)組，合法
int age(); // int類型树碱，合法
Integer someInt(); // 其他引用類型肯适，不合法
Another another(); // 注解類型，合法
}
@interface Another {}
如果定義了數(shù)組類型的屬性成榜，使用該注解時(shí)可以通過(guò)如下語(yǔ)法傳入值：
@MyAnnotation(key = {"Hello", "World"})
class SomeClass {}
@MyAnnotation(key = "Hi Paul") //盡管key是String[]類型框舔，如果只想傳入一個(gè)值，仍然可以通過(guò)這種方式
class Another {}
注解相關(guān)的反射API
上文提到過(guò)伦连，注解被指定為RUNTIME的時(shí)候雨饺，可以通過(guò)Java反射，在運(yùn)行時(shí)獲取到該注解惑淳。
以一段代碼為例：
@SendSomething("Wahaha")
public class GetAnnotationDemo {
public static void main(String[] args) {
// 獲取修飾GetAnnotationDemo的SendSomething類型注解
SendSomething declaredAnnotation = GetAnnotationDemo.class.getDeclaredAnnotation(SendSomething.class);
System.out.println(declaredAnnotation.value()); // 返回Wahaha
}
}
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface SendSomething {
String value() default "defaultValue";
}
以上是注解最簡(jiǎn)單的使用额港。與注解有關(guān)的其他反射方法總結(jié)如下：
| 方法名 | 描述 |
|---|---|
| isAnnotationPresent(A.class) | 是否被A類型注解修飾 |
| getDeclaredAnnotation(A.class) | 獲取類型為A的直接修飾的注解實(shí)例 |
| getDeclaredAnnotationsByType(A.class) | 獲取類型為A的直接修飾的注解實(shí)例, 返回?cái)?shù)組 |
| getDeclaredAnnotations() | 獲取所有直接修飾的注解實(shí)例，返回?cái)?shù)組 |
| getAnnotation(A.class) | 獲取類型為A的注解實(shí)例歧焦，返回?cái)?shù)組 |
| getAnnotationsByType(A.class) | 獲取所有類型為A的注解實(shí)例移斩，返回?cái)?shù)組 |
| getAnnotations() | 獲取所有注解實(shí)例，返回?cái)?shù)組 |
注解的使用場(chǎng)景
在這個(gè)例子中我們要實(shí)現(xiàn)讀取properties文件的內(nèi)容并自動(dòng)注入到class當(dāng)中绢馍。
conf.properties文件：
username=paul
password=123456
@PropertySource("/path/to/conf.properties")
class UserConf {
// 自動(dòng)讀取出username和password
String username;
String password;
}
下面代碼給出了實(shí)現(xiàn)該功能的主要邏輯向瓷。
定義注解：
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface PropertySource {
String value();
}
編寫(xiě)主要邏輯：
PropertyResolver.java
public class PropertyResolver {
public <T> T getProperty(Class<T> propertySourceClass) throws Exception {
T propertySourceBean = propertySourceClass.newInstance();
// 如果propertySourceClass被PropertySource注解修飾
if (propertySourceClass.isAnnotationPresent(PropertySource.class)) {
PropertySource propertySource = propertySourceClass.getDeclaredAnnotation(PropertySource.class);
File propertyFile = new File(propertySource.value());
// 讀取properties文件內(nèi)容到properties
FileReader fileReader = new FileReader(propertyFile);
Properties properties = new Properties();
properties.load(fileReader);
// 裝配屬性
// 獲取propertySourceClass所有的成員變量
Field[] declaredFields = propertySourceClass.getDeclaredFields();
// 獲取屬性文件中所有的key
Set<String> propertyNames = properties.stringPropertyNames();
for (Field declaredField : declaredFields) {
String fieldName = declaredField.getName();
for (propertyName: propertyNames) {
if (fieldName.equals(propertyName)) {
// 如果成員變量不可訪問(wèn)，設(shè)置為能夠訪問(wèn)
if (!declaredField.isAccessible()) {
declaredField.setAccessible(true);
}
// 設(shè)置屬性值
declaredField.set(propertySourceBean, properties.getProperty(propertyName));
break;
}
}
}
}
return propertySourceBean;
}
}
使用自己編寫(xiě)的工具
public static void main(String[] args) {
UserConf userConf = new PropertyResolver().getProperty(UserConf.class);
userConf.username; // "paul"
userConf.password; // "123456"
}
完整代碼實(shí)現(xiàn)請(qǐng)點(diǎn)擊鏈接： https://github.com/paul8263/PropertyResolver
本博客為作者原創(chuàng)舰涌，歡迎大家參與討論和批評(píng)指正猖任。如需轉(zhuǎn)載請(qǐng)注明出處。
參考資料
Oracle Predefined annotation types. https://docs.oracle.com/javase/tutorial/java/annotations/predefined.html
