java 註解(翻譯自Java Tutorials)

原文出自 http://www.cnblogs.com/ggjucheng/archive/2012/12/03/2800487.html

英文出自 http://docs.oracle.com/javase/tutorial/java/javaOO/annotations.html

註解為程式提供資料，但是，它不是程式的一部分。它們不會在註解的代碼直接影響應用。

註解有如下的使用

• 編譯器資訊— 編譯器用註解檢測到錯誤或抑制警告。
• 編譯時間和部署時的處理 — 軟體工具可以處理注釋的資訊來產生代碼，XML檔案，等等。
• 運行時處理 — 有些註解是在運行時進行檢查.

註解可以應用到程式聲明的類，欄位，方法，和其他程式元素。

@Author(   name = "Benjamin Franklin",   date = "3/27/2003")class MyClass() { }或@SuppressWarnings(value = "unchecked")void myMethod() { }

如果有一個元素取名為value，那麼這個名字可以被忽略，例如：

@SuppressWarnings("unchecked")void myMethod() { }

如果註解沒有元素，小括弧可以被忽略，例如：

@Overridevoid mySuperMethod() { }

  文檔

許多註解取代了本來已經在代碼中的注釋。

假設傳統的軟體組在每個類的類體的開始，使用注釋提供了重要的資訊：

public class Generation3List extends Generation2List {   // Author: John Doe   // Date: 3/17/2002   // Current revision: 6   // Last modified: 4/12/2004   // By: Jane Doe   // Reviewers: Alice, Bill, Cindy   // class code goes here}

使用註解提供一樣的中繼資料，首先要聲明一個註解類型，文法是：

@interface ClassPreamble {   String author();   String date();   int currentRevision() default 1;   String lastModified() default "N/A";   String lastModifiedBy() default "N/A";   // Note use of array   String[] reviewers();}

註解的聲明，就像在interface聲明前面添加一個@字元(@是AT,即Annotation Type)。註解類型，其實是一種形式的介面，它會覆蓋在後面的課程中。就目前而言，你不需要瞭解介面

註解的聲明的本文，包括註解元素的聲明，看起來很像方法。注意，這裡可以定義可選的預設值。

一旦註解定義好了，就可以在使用註解時，填充註解的值，就像這樣：

@ClassPreamble (   author = "John Doe",   date = "3/17/2002",   currentRevision = 6,   lastModified = "4/12/2004",   lastModifiedBy = "Jane Doe",   // Note array notation   reviewers = {"Alice", "Bob", "Cindy"})public class Generation3List extends Generation2List {// class code goes here}

注意：要讓@ClassPreamble的資訊出現在Javadoc產生的文檔，必須使用@Documented註解定義@ClassPreamble

// import this to use @Documentedimport java.lang.annotation.*;@Documented@interface ClassPreamble {   // Annotation element definitions   }

 

編譯器使用註解

有這麼幾種註解類型通過語言規範預定義：@Deprecated, @Override, @SuppressWarnings。

@Deprecated—@Deprecated註解指示，標識的元素是廢棄的，不應該再使用。編譯器會在任何使用到@Deprecated的類，方法，欄位的程式，產生警告。當元素是廢棄的，它也應該使用Javadoc的@deprecated標識文檔化，，如下面的例子。兩個Javadoc注釋和註解中的“@”符號的使用不是巧合 - 它們是相關的概念上。另外，請注意Javadoc標記開始用小寫字母“D”和註解開始以大寫字母“D”。

   // Javadoc comment follows    /**     * @deprecated     * explanation of why it     * was deprecated     */    @Deprecated    static void deprecatedMethod() { }}@Override—@Override註解通知編譯器，覆蓋父類聲明的元素。   // mark method as a superclass method   // that has been overridden   @Override    int overriddenMethod() { }

 

雖然不要求在覆蓋方法時，必須使用註解，但是它可以避免錯誤。如果一個方法標記為@Override，但是無法正確覆蓋父類的任何方法，編譯器會產生錯誤。

@SuppressWarnings—@SuppressWarnings註解，告訴編譯器，抑制正常情況下會產生的特定的警告。下面的例子，一個廢棄的方法被使用，編譯器正常會產生警告，而這個情況下，這個註解導致警告會被抑制。

   // use a deprecated method and tell    // compiler not to generate a warning   @SuppressWarnings("deprecation")    void useDeprecatedMethod() {        // deprecation warning        // - suppressed        objectOne.deprecatedMethod();    }

每個編譯器的警告屬於一個類別。java語言規範有兩個類別："deprecation" 和"unchecked"。"unchecked" 會在使用以前的寫的泛型的遺留代碼進行互動時，產生警告。抑制更多類別的警告，使用下面的文法：

@SuppressWarnings({"unchecked", "deprecation"})

 

註解處理

註解的更進階使用，包括註解處理，讀一個java程式，根據註解執行一些動作。例如，它可以產生輔助的原始碼，減輕程式員建立的樣板代碼，始終遵循可預測的模式的工作量。為了推動這個工作，JDK 5.0包含了一個註解處理工具，成為apt。在JDK 6.0中，apt是java編譯器的標準的一部分。

運行期使用註解，註解類型本身必須使用@Retention(RetentionPolicy.RUNTIME)註解，例如：

import java.lang.annotation.*; @Retention(RetentionPolicy.RUNTIME)@interface AnnotationForRuntime {   // Elements that give information   // for runtime processing   }