Java Annotation Example

使用步驟：
步驟1. 定義註文型態(Annotation type)
1. Annotation type 的宣告類似 interface 的宣告，使用 "@" 記號後接 interface 關鍵字和中括號 "｛｝"，中括號內
的members 可以是 methods、enums、variables、或 inner classes/interfaces 等。

2. 註文中的 members
A. methods 宣告
(1) method declaration 用來定義 Annotation type 的 element。
(2) method declaration 不能有任何的參數或 throws 子句。
(3) return type 只能限定為 primitives、String、class、enums、Annotations、或這些型別的陣列。
(4) method 可以有預設值(default values)，使用關鍵字 default 設定。
(5) method 存取權限不能為 protected、或 private。
B. enums(或稱 enumeration)
enums 的預設存取權限為 public。
enums 可用來作為 Annotation type 的預設值。

3. Annotation type 內沒有任何的 elements 稱為 marker Annotation type。
marker Annotation 在使用的時候，其後面的小括號(parenthes)可以省略。

4. 用來對 Annotation type 做註文的 Annotations 稱為 meta-Annotations。
meta-Annotation 的種類：
A. @Target --定義在 java.lang.Annotation.Target
此種 meta-Annotation 使用在 java.lang.Annotation.ElementType 列舉中定義的 constants，以 "@Target"
指明Annotation type 適用之處，如只用於 fields、或 constructors 等 。
B. @Retention --定義在 java.lang.Annotation.Retention
使用在 java.lang.Annotation.RetentionPolicy 列舉中定義的 constants，以 " "@Retention" 告知編譯器如何
處理Annotation，處理方式有：
(1) RetentionPolicy.RUNTIME --編譯過的 class 檔案內會保留 Annotations，並在 class 載入時讀取註文。
(2) RetentionPolicy.CLASS --編譯過的 class 檔案內會保留 Annotations，但在 runtime 時會忽略註文，為
預設行為。
(3) RetentionPolicy.SOURCE --編譯過後的 class 檔案會移除 Annotations。
C. @Documented　 --定義在 java.lang.Annotation.Documented
屬於 marker Annotations，表示 Annotation 應出現在 Javadoc 中。預設情況下，Annotations 不會寫入
Javadoc檔案內。
須配合 @Retention 指明 RetentionPolicy.RUNTIME 兩者一起使用。
D. @Inherited --定義在 java.lang.Annotation.Inherited
設定基底類別內的 Annotation type 會被衍生類別自動繼承。預設值為不繼承。
當 annotated type 使用在類別上時，設定 @Inherited 才有作用；且 @Inherited 的作用只及於類別被繼
承，若為介面的實作則無作用。不過實際上試驗結果@Inherited好像沒有作用！？

範例： 定義 Annotation type

public @interface MyAT ｛
　int myid();
　String myname() default "[unassigned]"; 
　String mybirthday() default "[unimplemented]"; 
｝

範例： meta-Annotations

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Test ｛　｝

範例： meta-Annotations

import java.lang.Annotation.Documented;
import java.lang.Annotation.Retention;
import java.lang.Annotation.RetentionPolicy;

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation ｛　｝

步驟2. 使用註文(Annotation)
1. Annotation 是一種特別形式的 modifier，可用在一般 modifiers(如 public、static、或 final)能用的地方。
2. Annotations 應放在一般 modifiers 的前面。
3. Annotations 的組成：
由 "@" 符號，後面加上 Annotation type 名稱和小括號 "( )" 組成，括號內為成對的
"element=value"，以 "=" 等號指派 element 的值為 value，多組 "element-value" 以 "," 逗號間隔，其中 values
必須是常數(compile-time constants)。要傳遞多組的 value 給 element，須使用陣列的方式。
4. 如果註文型態僅包含一個元素，且該元素的名字為 value 時，則在使用此種注文型態時候，元素的名字和等號可以省
略；若元素名稱不是 value，則不能省略。

範例：

@interface MyAT1 ｛
　　String myAuthor() ; 
　　String myDate() ; 
｝
public class MyClass ｛
　　@MyAT1( myAuthor = "Ken", myDate = "4/1/1964")
　　public static void MyMethod( ) ｛ ... ｝
　　// ......
｝

範例：

public @interface MyMarkerAT ｛　｝ 　// Marker AAnnotation Type
@MyMarkerAT public class MyClass ｛ 　// 省略 marker Annotations 後的小括號
　　... 
｝

範例：

@interface Copyright ｛ String value(); ｝

@Copyright("2002 Moon Macrosystems, Inc") 
public class MyClass ｛ ... ｝