java.lang.annotation，接口 Annotation。對於Annotation，是Java5的新特性，JDK5引入了Metadata（元數據）很容易的就能夠調用Annotations。Annotations提供一些本來不屬於程式的數據，比如：一段代碼的作者或者告訴編譯器禁止一些特殊的錯誤。An annotation 對代碼的執行沒有什麼影響。Annotations使用@annotation的形式套用於代碼：類(class),屬性(attribute),方法(method)等等。一個Annotation出現在上面提到的開始位置，而且一般只有一行，也可以包含有任意的參數。
基本介紹
- 中文名：註解
- 外文名：Annotation
- 已實現類：Deprecated,Documented
- 公共接口：public interface Annotation
- 方法摘要：Class<? extends Annotation>
已實現類,方法摘要,方法信息,覆蓋,另請參見,返回,處理器,
已實現類
Deprecated,Documented,Inherited,Override,Retention,SuppressWarnings,Target
public interface Annotation所有 annotation 類型都要擴展的公共接口。注意，手動擴展該公共接口的接口不定義 annotation 類型。還要注意此接口本身不定義 annotation 類型。
對於Annotation，是Java5的新特性，下面是Sun的Tutorial的描述，因為是英文，這裡我翻譯下，希望能夠比較清晰的描述一下Annotation的語法以及思想。Annotation:Release 5.0 of the JDK introduced a metadata facility called annotations. Annotations provide data about a program that is not part of the program,such as naming the author of a piece of code or instructing the compiler to suppress specific errors. An annotation has no effect on how the code performs. Annotations use the form @annotation and may be applied to a program's declarations: its classes,fields,methods,and so on. The annotation appears first and often (by convention) on its own line,and may include optional arguments: JDK5引入了Metadata(元數據)很容易的就能夠調用Annotations.Annotations提供一些本來不屬於程式的數據，比如：一段代碼的作者或者告訴編譯器禁止一些特殊的錯誤。An annotation 對代碼的執行沒有什麼影響。Annotations使用@annotation的形式套用於代碼：類（class），屬性（field），方法（method）等等。一個Annotation出現在上面提到的開始位置，而且一般只有一行，也可以包含有任意的參數。@Author("MyName")class myClass() { }
or @SuppressWarnings("unchecked")void MyMethod() { }
Defining your own annotation is an advanced technique that won't be described here,but there are three built-in annotations that every Java programmer should know: @Deprecated,@Override,and @SuppressWarnings. The following example illustrates all three annotation types,applied to methods:
定義自己的Annotation是一個比較高級的技巧，這裡我們不做討論，這裡我們僅僅討論每一個Java programer都應該知道的內置的annotations:@Deprecated,@Override,and @SuppressWarnings。下面的程式闡述了這三種annotation如何套用於methods。import java.util.List;
class Food {}
class Hay extends Food {}
class Animal {
Food getPreferredFood() {
return null;
} /** * @deprecated document why the method was deprecated */
@Deprecated
static void deprecatedMethod() { }
}
class Horse extends Animal {
Horse() {
return;
}
@Override
Hay getPreferredFood() {
return new Hay();
}
@SuppressWarnings("deprecation")
void useDeprecatedMethod() {
Animal.deprecateMethod(); //deprecation warning - suppressed }}
}
}
@Deprecated The @Deprecated annotation indicates that the marked method should no longer be used. The compiler generates a warning whenever a program uses a deprecated method,class,or variable. When an element is deprecated,it should be documented using the corresponding @deprecated tag,as shown in the preceding example. Notice that the tag starts with a lowercase "d" and the annotation starts with an uppercase "D". In general,you should avoid using deprecated methods — consult the documentation to see what to use instead.
@Deprecated @Deprecated annotation標註一個method不再被使用。編譯器在一個program（程式？）使用了不贊成的方法，類，變數的時候會產生警告（warning）。如果一個元素（element:method,class,or variable）不贊成被使用，應該像前面的例子裡使用相應的@deprecated 標籤，並且注意標籤的首字母是小寫的"d",而annotation是大寫的"D"。一般情況下，我們應該避免使用不贊成使用的方法（deprecated methods），而應該考慮替代的方法。
@Override The @Override annotation informs the compiler that the element is meant to override an element declared in a superclass. In the preceding example,the override annotation is used to indicate that the getPreferredFood method in the Horse class overrides the same method in the Animal class. If a method marked with @Override fails to override a method in one of its superclasses,the compiler generates an error. While it's not required to use this annotation when overriding a method,it can be useful to call the fact out explicitly,especially when the method returns a subtype of the return type of the overridden method. This practice,called covariant return types,is used in the previous example: Animal.getPreferredFood returns a Food instance. Horse.getPreferredFood (Horse is a subclass of Animal) returns an instance of Hay (a subclass of Food). For more information,see Overriding and Hiding Methods.
@Override annotation 告訴編譯器當前元素是重寫（override）自父類的一個元素。在前面的例子中，override annotation用來說明Horse類中的getPreferredFood這個方法重寫（override）自Animal類中相同的方法。如果一個方法被標註了@Override，但是其父類中沒有這個方法時，編譯器將會報錯。但是並不是說我們一定要使用這個annotation，但是它能夠很明顯的給出實際行為，尤其是在方法返回一個被重寫的方法返回類型的子類型的時候。上面的例子中，Animal.getPreferredFood 返回一個 Food實例，Horse.getPreferredFood 返回一個Hay實例，這裡Horse是Animal的子類，Hay是Food的子類。
@SuppressWarnings The @SuppressWarnings annotation tells the compiler to suppress specific warnings that it would otherwise generate. In the previous example,the useDeprecatedMethod calls a deprecated method of Animal. Normally,the compiler generates a warning but,in this case,it is suppressed. Every compiler warning belongs to a category. The Java Language Specification lists two categories: "deprecation" and "unchecked". The "unchecked" warning can occur when interfacing with legacy code written before the advent of generics. To suppress more than one category of warnings,use the following syntax:
@SuppressWarnings annotation 告訴編譯器禁止別的元素產生的特殊的警告（warnings），在前面的例子裡，useDeprecatedMethod調用了Animal的不贊成使用的一個方法。一般情況下，編譯器會給出一個警告（warning），但是在這種情況下，不會產生這個警告，也就是說被suppress。每個編譯器的警告都屬於一個類型。Java Language Specification列出了兩種類型："deprecation" 和 "unchecked"。"unchecked" 警告發生在使用非generic的舊代碼互動的generic collection類時。要禁止不止一種的警告時，則使用下面的語法：@SuppressWarnings({"unchecked","deprecation"})
方法摘要
Class<? extends Annotation> annotationType()
返回此 annotation 的注釋類型。
boolean equals(Object obj)
如果指定的對象表示在邏輯上等效於此接口的注釋，則返回true。
int hashCode()
返回此 annotation 的哈希代碼，具體說明如下：具體說明如下：成員值的哈希代碼取決於其類型：
String toString()
返回此 annotation 的字元串表示形式。
方法信息
equals
boolean equals(Object obj）如果指定的對象表示在邏輯上等效於此接口的注釋，則返回 true。換句話說，如果指定對象是一個與此實例相同的 annotation 類型的實例，即其所有成員都與此實例中所對應的成員相等，則返回 true，具體說明如下：
如果 x == y，則認為值分別為 x 和 y 的兩個對應的基本類型成員相等，除非它們的類型是 float 或 double。
如果 Float.valueOf(x).equals(Float.valueOf(y)) 為真，則認為值分別為 x 和 y 的兩個對應的 float 成員相等。（與 == 運算符不同，NaN 被認為等於其自身，並且 0.0f 不等於 -0.0f。）
如果 Double.valueOf(x).equals(Double.valueOf(y)) 為真，則認為值分別為 x 和 y 的兩個對應的 double 成員相等。（與 == 運算符不同，NaN 被認為等於其自身，並且 0.0 不等於 -0.0。）
如果 x.equals(y) 為真，則認為值分別為 x 和 y 的兩個對應的 String、Class、enum 或 annotation 類型的成員相等。（注意，此定義對於 annotation 類型的成員是遞歸的。）
對於適當重載的 Arrays.equals(long[],long[]），如果 Arrays.equals(x,y) 為真，則認為兩個對應的數組類型的成員 x 和 y 相等。
覆蓋
類 Object 中的 equals
參數：
obj - 要與之比較的引用對象。
返回：
如果指定的對象表示在邏輯上等效於該接口的 annotation，則返回 true，否則返回 false
另請參見
Object.hashCode(),Hashtable
hashCode
int hashCode（）返回此 annotation 的哈希代碼，具體說明如下：
成員值的哈希代碼取決於其類型：
string、enum、class 或 annotation 的成員值 I 的哈希代碼v 是通過調用 v.hashCode() 來計算的。（對於 annotation 成員值，這是一種遞歸定義。）
覆蓋：
類 Object 中的 hashCode
返回：
此 annotation 的哈希代碼。
另請參見：
Object.equals(java.lang.Object),Hashtable
toString
String toString（）返回此 annotation 的字元串表示形式。表示形式的細節取決於實現，但下面的情況是最常見的：
com.acme(first=Alfred,middle=E.,last=Neuman)
覆蓋：
類 Object 中的 toString
返回
此 annotation 的字元串表示形式
annotationType
Class<? extends Annotation> annotationType（）返回此 annotation 的注釋類型。
處理器
通過annotation processing tool（注釋處理工具，簡稱apt），可以處理源碼中的注釋，獲得更靈活的代碼，也將程式設計師從樣板式的編程中解放了出來。
為了使注釋(annotation)中的信息能在運行時(RUNTIME)被程式利用，在創建注釋時，應該給注釋的類名添加@Retention(RetentionPolicy.RUNTIME)注釋。
構建自定義注釋信息處理器與以下API有關：
Mirror API(已過時Deprecated)
javax.annotation.processing
javax.lang.model
javax.lang.model.element
javax.lang.model.type
javax.lang.model.util
