已實現類
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 成員值,這是一種遞歸定義。)
數組成員值的哈希代碼是通過基於該值調用 Arrays.hashCode 的適當重載來計算的。(各種基本類型和對象引用類型分別對應一個重載。)
覆蓋:
類 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