深入探討 Android、Java 註解應用：分析註解與 Enum 的差異 | Android APT

public class TestAnnotation {

    public static void main(String... args) {
        TestRxxx(new Integer[]{});
        TestRxxx(new String[]{});
        TestRxxx(R.id.response);
    }

    private static void TestRxxx(@IdRes int id) {

    }
}

--實作--

像是 Android 的輕量級異步執行緒框架 AnsyncTask 就有此用這些

… 有關於 AnsyncTask 解釋請點擊連結了解（Template 設計模式 | 實現與解說 | Android source AsyncTask 微框架）

// AnsyncTask.java

    @WorkerThread
    protected abstract Result doInBackground(Params... params);

    ...
    @MainThread
    protected void onPreExecute() {
    }

    ...
    @SuppressWarnings({"UnusedDeclaration"})
    @MainThread
    protected void onPostExecute(Result result) {
    }

    ...
    @SuppressWarnings({"UnusedDeclaration"})
    @MainThread
    protected void onProgressUpdate(Progress... values) {
    }

    ...
    @SuppressWarnings({"UnusedParameters"})
    @MainThread
    protected void onCancelled(Result result) {
        onCancelled();
    }

--實作--

只要符合 @ColorInt 規範的整數就可以 (以下可以看出 ID 類的標明也是符合，但整數 20 不可以)

public class TestAnnotation {

    public static void main(String... args) {

        ArrayList<Integer> list = new ArrayList<>();
        list.add(1);
        list.add(2);
        list.add(3);
        list.add(4);
        TestSizeInList(list);

        TestSizeOther(1,3,5,6,7,8);

    }

    private static void TestSizeInList(@Size(3) ArrayList<Integer> list) {
    }

    private static void TestSizeOther(@Size(3) int... params) {
    }
}

--實作--

public class TestAnnotation {

    public static void main(String... args) {
        new RichMan(new PoorMan()).wear();
    }
}

abstract class Decorator {
    Decorator() {
    }

    public abstract void wear();
}

class PoorMan extends Decorator {
    @Override
    public void wear() {
        System.out.println("UnderPant");
    }
}

abstract class WorkMan extends Decorator {
    protected Decorator d;

    protected WorkMan(Decorator d) {
        this.d = d;
    }

    @CallSuper
    @Override
    public void wear() {
        d.wear();
    }
}

class RichMan extends WorkMan {
    protected RichMan(Decorator d) {
        super(d);
    }

    @Override
    public void wear() {
        super.wear();
        System.out.println("Jacket");
        System.out.println("Pant");
        System.out.println("T-shirt");
        System.out.println("sock");
        System.out.println("shoes");
    }
}

以　裝飾器模式來說每個實作類都需要呼叫該父類的方法，但使用者有時會忘記呼叫 super() 這時就可以使用，用來提醒使用框架者要記得呼叫父類方法

這種提醒機制並「非強制」，就算使用者不遵從提醒仍可編譯過

--實作--

class MyTestClass {
    enum Level {
        LEVEL_1,
        LEVEL_2,
        LEVEL_3,
        LEVEL_4,
        LEVEL_5,
        LEVEL_6,
    }
}

上面程式碼經過 ASM 反組譯後會變為，每一個成員皆為一個 enum 類，所 佔用空間過大 (Byte 描述 Class 會耗費多一點空間)

InDef 可使用在 IDE 檢查，其階段只保留到 Source，以下是它的源碼

Android 還有 StringDef... 等等可以使用

// 源碼

@Retention(SOURCE)                // 保存到 Source 階段
@Target({ANNOTATION_TYPE})
public @interface IntDef {
    /** Defines the allowed constants for this element */
    int[] value() default {};

    boolean flag() default false;

    boolean open() default false;
}

A. 效能更高：

B. 編譯期檢查：

C. 提高可讀性：

要使用 IntDef 需要自定義一個註解，並且標註該註解作用的區域 @Target，還有它的保留階段 @Retention

class MyTestClass {

    //"1. "
    @Target({ElementType.FIELD, ElementType.PARAMETER})
    @IntDef(value = {LEVEL_1, LEVEL_2, LEVEL_3, LEVEL_4, LEVEL_5})
    @Retention(RetentionPolicy.SOURCE)
    @interface MyLevel {

    }

    public static final int LEVEL_1 = 1;
    public static final int LEVEL_2 = 2;
    public static final int LEVEL_3 = 3;
    public static final int LEVEL_4 = 4;
    public static final int LEVEL_5 = 5;


    public static void main(String []args){
        System.out.println("Hello World");

        setLevel(1111);    //"2. "
        setLevel(3);
        setLevel(LEVEL_3);
    }

    public static void setLevel(@MyLevel int level) {
        System.out.println("level: " + level);
    }
}

A. 使用自定義註解，要標示它作用的區域，如果沒有標示 ElementType.PARAMETER 該註解則不能作用於函式參數

B. 放入非標準的格式編譯仍然可以過，但是寫程式時跳出警告訊息，讓程式更加健壯

其主要目的是處理 泛型 的可變長參數(T...t) ，告編譯器此泛型是安全長參數

可變長參數使用數組儲存，而數組 & 泛型不能很好的混合使用

● 數組 & 泛型 ?　可以使用泛型數組不會有警告

數組：編譯期間就已確定（靜態確認）

泛型：運行時才能確定數據，因此編譯時無法判別其正確性，導致產生警告（動態確認）… 這時我們就可以使用 @SafeVargs 去壓制警告

● 註解 @SafeVargs 只能宣告在 static or final 的函數

public class TestProblemOfGeneric {

    public static void main(String[] args) {
        List<String> list1 = new ArrayList<>();
        List<String> list2 = new ArrayList<>();

        //"2. "
        FixList.add2List(list1, "Pan", "Kyle", "Alien");
        FixList.add2List(list2, "One", "Two", "Three");

        List<List<String>> list3 = new ArrayList<>();
        //"3-1. "
        FixList.add2List(list3, list1, list2);
        //"3-2. "
        FixList.TestMethod(Arrays.asList("Hello!"), 
                           Arrays.asList("World!"));
    }

}

class FixList {
    public static <T> void add2List(List<T> list, T...data) {
        for(T t : data) {
            list.add(t);
        }
    }

    //"1. "
    public static void TestMethod(List<String>...list) {
        Object[] o = list;
        //"4. "
        o[0] = Arrays.asList(new Integer(123));
        String str = list[0].get(0);
        System.out.println("Test: " + str);
    }
}

A. ... 代表可變的參數長度，編譯器會將其變成 數組，也就是說 List<String>...list 可以看做 List<String>[]

B. 一般類型可正常轉為可變長度，再轉為數組

C. Java 不允許泛型類類型的數組 (無法確認數據類型，會發出警告)，使用 @SafeVarargs 使其安全使用 (確定不會錯誤時再添加這個註解)

D. 如果沒有 @SafeVarargs 註解壓住錯誤的話，IDE 會警告發生 HashPollution 錯誤（想了結詳情情點擊連結）

// Sample 1
@interface HelloWorld {

}

@HelloWorld
class MyAnnotation {

}

// Sample 2 in Android
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.FIELD)
public @interface MyAnnotation {
    @IdRes int id();
}

@MyAnnotation(id = R.id.sample_text)
TextView tv;

A. @Retention (註解保留期間)（Java 1.5 加入）

B. @Target (目標)：註解所修飾的對象範圍（Java 1.5 加入）

@Target({
    ElementType.ANNOTATION_TYPE, 
    ElementType.CONSTRUCTOR, 
    ElementType.TYPE}
)

C. @Documented（Java 1.5 加入）

D. @Inherited (繼承)（Java 1.5 加入）

E. @Repeatable (重複)（Java 1.8 加入）

而註解中的 value 是一個特殊的屬性，value 不需要指定

public @interface MyAnnnotation {
    // value 接收 String 類型參數
    String value();    

    // StrArray 接收 string array 類型
    String[] StrArray();  // 需要指定
}

● 基礎類型：byte, short, int, long, float, double, char, boolean

● 特殊類型：Class、enum、interface

//"1. "　使用預設質、或指定
@MyAnnnotation(id=10, name="ABC", getEnum = MyEnum.THREE)
class ToDo {
}

interface MyInterface {
}

enum MyEnum {
    ONE, TWO, THREE
}

@interface MyAnnnotation {
    int id() default -1; 
    String name() default "";

    //"2. "　不能設定方法
    //void setAddress(String addr);		 

    Class<?> get() default Todo.class;
    MyEnum getEnum() default MyEnum.ONE;

    enum TestEnum {
        ONE, TWO, THREE
    }

    interface Test {

    }
}

A. 建立一個 MyAnnotation 的註解，並用元注解標註 SOURCE、FIELD

package com.oo.jnidemo;    // 之後會使用到

...

@Retention(RetentionPolicy.SOURCE)    // 只保存在源碼階段
@Target(ElementType.FIELD)
public @interface MyAnnotation {
    @IdRes int id();
}

B. 新建 Java or Kotlin Library (File > New > New Module...)，並取名為 annotations

apply plugin: 'java-library'

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation project(':annotations')
}

sourceCompatibility = "7"
targetCompatibility = "7"

//"a. "
@SupportedAnnotationTypes("com.oo.jnidemo.MyAnnotation")
public class MyAnnotationProcess extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
        //"b. "
        Messager messager = processingEnv.getMessager();
        messager.printMessage(Diagnostic.Kind.NOTE, "!!!======== Annotation Processor ========!!!");

        return false;
    }
}

C. 註冊「註解處理器」，就像是 Activity 要在 AndroidManifest；註解處理器也要註冊，有兩種方法 手動 & 自動：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation project(':annotations')
    // new
    compileOnly 'com.google.auto.service:auto-service:1.0-rc4'
    annotationProcessor 'com.google.auto.service:auto-service:1.0-rc2'
}

// 自動註冊時，Processor.class 這是固定寫法 
@AutoService(Processor.class)

// 代表了該註解處理器會處理這個註解 (包名 + 全類名)
@SupportedAnnotationTypes("xxx.yyy.zzz")

// 指定 JDK 編譯版本
@SupportedSourceVersion(SourceVersion.RELEASE_7)

// 接收的參數
@SupportedOptions({"xxx", "yyy"})

public class ClassProcessor extends AbstractProcessor {

    @Override
    public synchronized void init(ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
    }

    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment roundEnvironment) {
        ...
    }
}

D. 使用註解：使用的主工程項目中，添加要使用的 project 依賴（這個 project 就是我們在上面寫的註解處理器），之後主工程在編譯時，指定的註解就會被分析

dependencies {
    ...

    implementation project(':annotations')  // 註解
    annotationProcessor project(':processor')    // 註解處理器
}

public class MainActivity extends AppCompatActivity {

    @MyAnnotation(id = R.id.sample_text)
    TextView tv;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }