From Gossip@caterpillar

Java Gossip: 告知編譯器如何處理 annotaion - Retention

java.lang.annotation.Retention可以在您定義Annotation型態時，指示編 譯器如何對待您的自定義 Annotation，預設上編譯器會將Annotation資訊留在class檔案中，但不被虛擬機器讀取，而僅用於編譯器或工具程式運行時提供資訊。

在使用Retention型態時，需要提供java.lang.annotation.RetentionPolicy的列舉型態：
package java.lang.annotation;

public enum RetentionPolicy {
    SOURCE, // 編譯器處理完Annotation資訊後就沒事了
    CLASS, // 編譯器將Annotation儲存於class檔中，預設
    RUNTIME // 編譯器將Annotation儲存於class檔中，可由VM讀入
}

RetentionPolicy為SOURCE的例子是SuppressWarnings，這個資訊的作用僅在告知編譯器抑制警訊，所以不必將這個資訊儲 存於class檔案。

RetentionPolicy為RUNTIME的時機，可像是您使用Java設計一個程式碼分析工具，您要VM讀出Annotation資訊，以在分析 程式中使用，搭配Reflection機制，就可以達到這個目的。

在J2SE 5.0中新增了java.lang.reflect.AnnotatedElement這個介面，當中定義有四個方法：
public Annotation getAnnotation(Class annotationType);
public Annotation[] getAnnotations();
public Annotation[] getDeclaredAnnotations();
public boolean isAnnotationPresent(Class annotationType);
 
Class、Constructor、Field、Method、Package等類別，都實作了 AnnotatedElement這個介面，所以您可以從這些類別的實例上，分別取得標示於其上的Annotation與其資訊，如果 RetentionPolicy為RUNTIME的話。

舉個例子來說，假設您設計了以下的Debug Annotation：
  • Debug.java 
package onlyfun.caterpillar;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

@Retention(RetentionPolicy.RUNTIME)
public @interface Debug {
    String value();
    String name();
}

由於RetentionPolicy為RUNTIME，編譯器在處理Debug Annotation時，會將之編譯至class檔中，並可以VM讀出Annotation資訊，接著我們將Debug用於程式中：
  • SomeObject.java 
package onlyfun.caterpillar;

public class SomeObject {
    @Debug(
       value = "unit",
       name = "debug1"
    )
    public void doSomething() {  
        // ....      
    }
}


可以設計一個工具程式來讀取Annotation資訊：

  • DebugTool.java 
package onlyfun.caterpillar;

import java.lang.annotation.Annotation;
import java.lang.reflect.Method;

public class DebugTool {
    public static void main(String[] args) 
                               throws NoSuchMethodException {
        Class<SomeObject> c = SomeObject.class;

        Method method = c.getMethod("doSomething");
        if(method.isAnnotationPresent(Debug.class)) {
            System.out.println("@Debug is found.");

            Debug debug = method.getAnnotation(Debug.class);
            System.out.println("\tvalue = " + debug.value());
            System.out.println("\tname = " + debug.name());
        }
        else {
            System.out.println("@Debug is not found.");
        }

        Annotation[] annotations = method.getAnnotations();
        for(Annotation annotation : annotations) {
            System.out.println(
                    annotation.annotationType().getName());
        }
    }
}

程式的執行結果如下：
@Debug is found.
        value = unit
        name = debug1
onlyfun.caterpillar.Debug