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() { }

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

@Override
void 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 @Documented
import 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
   
}