Java基礎元註解基本原理範例詳解

2023-01-18 14:01:02

元註解

是負責對其它註解進行說明的註解，自定義註解時可以使用元註解。Java 5 定義了 4 個註解，分別是 @Documented、@Target、@Retention 和 @Inherited。Java 8 又增加了 @Repeatable 和 @Native 兩個註解。這些註解都可以在 java.lang.annotation 包中找到。下面主要介紹每個元註解的作用及使用。

@Documented

@Documented 是一個標記註解，沒有成員變數。用 @Documented 註解修飾的註解類會被 JavaDoc 工具提取成檔案。預設情況下，JavaDoc 是不包括註解的，但如果宣告註解時指定了 @Documented，就會被 JavaDoc 之類的工具處理，所以註解型別資訊就會被包括在生成的幫助檔案中。

IDEA Documented 檔案生成

Tools -> Generate JavaDoc

@Target

@Target 註解用來指定一個註解的使用範圍，即被 @Target 修飾的註解可以用在什麼地方。@Target 註解有一個成員變數（value）用來設定適用目標，value 是 java.lang.annotation.ElementType 列舉型別的陣列，下表為 ElementType 常用的列舉常數。

型別	適用目標
TYPE	用於類、介面（包括註解型別）或 enum 宣告
FIELD	用於成員變數（包括列舉常數）
METHOD	用於方法
PARAMETER	用於方法引數
CONSTRUCTOR	用於構造器
LOCAL_VARIABLE	用於區域性變數
ANNOTATION_TYPE	用於註解
PACKAGE	用於包
TYPE_PARAMETER	用來型別引數（JDK 1.8新增）
TYPE_USE	能標註任何型別名稱（JDK 1.8新增）

@Retention

@Retention 描述註解的生命週期，也就是該註解被保留的時間長短。@Retention 註解中的成員變數（value）用來設定保留策略，value 是 java.lang.annotation.RetentionPolicy 列舉型別。

RetentionPolicy 有 3 個列舉常數，如下所示：

SOURCE：在原始檔中有效（即原始檔保留）；
CLASS：在 class 檔案中有效（即 class 保留）；
RUNTIME：在執行時有效（即執行時保留）；

生命週期大小排序為 SOURCE < CLASS < RUNTIME，前者能使用的地方後者一定也能使用。

如果需要在執行時去動態獲取註解資訊，那隻能用 RUNTIME 註解，如 @Documented 註解；如果要在編譯時進行一些預處理操作，比如生成一些輔助程式碼，就用 CLASS 註解，如 @NonNull 註解；如果只是做一些檢查性的操作，則可選用 SOURCE 註解，如 @Override 和 @SuppressWarnings 註解。

@Inherited

@Inherited 是一個標記註解，用來指定該註解可以被繼承。使用 @Inherited 註解的 Class 類，表示這個註解可以被用於該 Class 類的子類。就是說如果某個類使用了被 @Inherited 修飾的註解，則其子類將自動具有該註解。

範例

建立一個自定義註解，程式碼如下所示：

@Target({ ElementType.TYPE })
@Inherited
@Retention(RetentionPolicy.RUNTIME)
public @interface MyInherited {
}

測試類程式碼如下：

@MyInherited
public class TestA {
    public static void main(String[] args) {
        System.out.println(TestA.class.getAnnotation(MyInherited.class));
        System.out.println(TestB.class.getAnnotation(MyInherited.class));
        System.out.println(TestC.class.getAnnotation(MyInherited.class));
    }
}
class TestB extends TestA {
}
class TestC extends TestB {
}

執行結果為：

@MyInherited()
@MyInherited()
@MyInherited()

@Repeatable

@Repeatable 是 Java 8 新增，它允許在相同的程式元素中重複註解，在需要對同一種註解多次使用時，往往需要藉助該註解。Java 8 版本以前，同一個程式元素前最多隻能有一個相同型別的註解，如果需要在同一個元素前使用多個相同型別的註解，則必須使用註解“容器”。

範例

Java 8 之前的相同型別的註解做法：

public @interface Roles {
    Role[] roles();
}
public @interface Role {
    String roleName();
}
public class RoleTest {
    @Roles(roles = {@Role(roleName = "roleA"), @Role(roleName = "roleB")})
    public String doString(){
        return "MingYue Repeatable 測試";
    }
}

Java 8 之後增加了重複註解，使用方式如下：

public @interface Roles {
    Role[] value();
}
@Repeatable(Roles.class)
public @interface Role {
    String roleName();
}
public class RoleTest {
    @Role(roleName = "roleA")
    @Role(roleName = "roleB")
    public String doString(){
        return "MingYue Repeatable 測試";
    }
}

兩者不同的地方是，建立重複註解 Role 時加上了 @Repeatable 註解，指向儲存註解 Roles，這樣在使用時就可以直接重複使用 Role 註解。