注解（一種元數(shù)據(jù)形式）提供有關(guān)不屬于程序本身的程序的數(shù)據(jù)，注解對它們注解的代碼的操作沒有直接影響。

注解有許多用途，其中包括：

編譯器的信息 — 編譯器可以使用注解來檢測錯(cuò)誤或抑制警告。

編譯時(shí)和部署時(shí)處理 — 軟件工具可以處理注解信息以生成代碼、XML文件等。

運(yùn)行時(shí)處理 — 可以在運(yùn)行時(shí)檢查某些注解。

本課程介紹了可以使用注解的位置，以及如何應(yīng)用注解，Java平臺(tái)標(biāo)準(zhǔn)版（Java SE API）中提供了哪些預(yù)定義注解類型，類型注解如何與可插拔類型系統(tǒng)結(jié)合使用來編寫具有更強(qiáng)類型檢查的代碼，以及如何實(shí)現(xiàn)重復(fù)注解。

在最簡單的形式中，注解如下所示：

@Entity

符號(hào)字符（@）向編譯器指示后面的內(nèi)容是注解，在以下示例中，注解的名稱為Override：

@Override
void mySuperMethod() { ... }

注解可以包含元素，這些元素可以是命名的，也可以是未命名的，這些元素的值如下：

@Author(
   name = "Benjamin Franklin",
   date = "3/27/2003"
)
class MyClass() { ... }

或：

@SuppressWarnings(value = "unchecked")
void myMethod() { ... }

如果只有一個(gè)名為value的元素，則可以省略該名稱，如：

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

如果注解沒有元素，則可以省略括號(hào)，如前面的@Override示例所示。

也可以在同一聲明上使用多個(gè)注解：

@Author(name = "Jane Doe")
@EBook
class MyClass { ... }

如果注解具有相同的類型，則稱為重復(fù)注解：

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { ... }

從Java SE 8發(fā)行版開始，支持重復(fù)注解，有關(guān)更多信息，請參閱重復(fù)注解。

注解類型可以是Java SE API的java.lang或java.lang.annotation包中定義的類型之一，在前面的示例中，Override和SuppressWarnings是預(yù)定義的Java注解，也可以定義自己的注解類型，上一個(gè)示例中的Author和Ebook注解是自定義注解類型。

注解可以應(yīng)用于聲明：類、字段、方法和其他程序元素的聲明，當(dāng)在聲明中使用時(shí)，按照慣例，每個(gè)注解通常出現(xiàn)在它自己的行上。

從Java SE 8發(fā)行版開始，注解也可以應(yīng)用于類型的使用，這里有些例子：

類實(shí)例創(chuàng)建表達(dá)式：

new @Interned MyObject();

輸入：

myString = (@NonNull String) str;

implements子句：

class UnmodifiableList implements
      @Readonly List<@Readonly T> { ... }

拋出的異常聲明：

void monitorTemperature() throws
      @Critical TemperatureException { ... }

這種形式的注解稱為類型注解，有關(guān)更多信息，請參閱類型注解和可插拔類型系統(tǒng)。

許多注解替換代碼中的注釋。

假設(shè)一個(gè)軟件組通常在每個(gè)類的開頭都帶有注釋，這些注釋提供了重要的信息：

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

}

要使用注解添加相同的元數(shù)據(jù)，必須先定義注解類型，這樣做的語法是：

@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();
}

注解類型定義類似于接口定義，其中關(guān)鍵字interface前面帶有at符號(hào)（@）（@ = AT，如在注解類型中），注解類型是一種接口形式，將在后面的課程中介紹，目前，你不需要了解接口。

前一個(gè)注解定義的主體包含注解類型元素聲明，它看起來很像方法，請注意，他們可以定義可選的默認(rèn)值。

定義注解類型后，你可以使用該類型的注解，并填入值，如下所示：

@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中的信息出現(xiàn)在Javadoc生成的文檔中，必須使用@Documented注解來注解@ClassPreamble定義：

// import this to use @Documented
import java.lang.annotation.*;

@Documented
@interface ClassPreamble {

   // Annotation element definitions
   
}

Java SE API中預(yù)定義了一組注解類型，某些注解類型用于Java編譯器使用，有些注解類型應(yīng)用于其他注解。

java.lang中定義的預(yù)定義注解類型是@Deprecated、@Override和@SuppressWarnings。

@Deprecated：@Deprecated注解表示標(biāo)記已棄用和不應(yīng)該再使用的元素，只要程序使用帶有@Deprecated注解的方法、類或字段，編譯器就會(huì)生成警告。當(dāng)棄用元素時(shí)，也應(yīng)使用Javadoc @deprecated標(biāo)記對其進(jìn)行記錄，如以下示例所示。在Javadoc注釋和注解中使用at符號(hào)（@）并非巧合：它們在概念上是相關(guān)的，另請注意，Javadoc標(biāo)記以小寫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() { }

雖然在重寫方法時(shí)不需要使用此注解，但它有助于防止出錯(cuò)，如果使用@Override標(biāo)記的方法無法正確覆蓋其某個(gè)超類中的方法，則編譯器會(huì)生成錯(cuò)誤。

@SuppressWarnings：@SuppressWarnings注解告訴編譯器抑制它將生成的特定警告，在以下示例中，使用了棄用的方法，編譯器通常會(huì)生成警告，但是，在這種情況下，注解會(huì)導(dǎo)致警告被抑制。

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

每個(gè)編譯器警告都屬于一個(gè)類別，Java語言規(guī)范列出了兩個(gè)類別：deprecation和unchecked，當(dāng)在泛型出現(xiàn)之前編寫的遺留代碼接口時(shí)，可能會(huì)發(fā)生unchecked警告，要禁止多種類別的警告，請使用以下語法：

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

@SafeVarargs：@SafeVarargs注解在應(yīng)用于方法或構(gòu)造函數(shù)時(shí)斷言代碼不對其varargs參數(shù)執(zhí)行可能不安全的操作，使用此注解類型時(shí)，與varargs使用相關(guān)的未經(jīng)檢查的警告被抑制。

@FunctionalInterface：Java SE 8中引入的@FunctionalInterface注解，表示類型聲明旨在成為Java語言規(guī)范定義的功能接口。

應(yīng)用于其他注解的注解稱為元注解，java.lang.annotation中定義了幾種元注解類型。

@Retention：@Retention注解指定標(biāo)記的注解的存儲(chǔ)方式：

RetentionPolicy.SOURCE — 標(biāo)記的注解僅保留在源級(jí)別中，并被編譯器忽略。

RetentionPolicy.CLASS — 標(biāo)記的注解在編譯時(shí)由編譯器保留，但Java虛擬機(jī)（JVM）會(huì)忽略。

RetentionPolicy.RUNTIME — 標(biāo)記的注解由JVM保留，因此運(yùn)行時(shí)環(huán)境可以使用它。

@Documented：@Documented注解表明，無論何時(shí)使用指定的注解，都應(yīng)使用Javadoc工具記錄這些元素（默認(rèn)情況下，注解不包含在Javadoc中），有關(guān)更多信息，請參閱Javadoc工具頁面。

@Target：@Target注解標(biāo)記另一個(gè)注解，以限制可以應(yīng)用注解的Java元素類型，目標(biāo)注解指定以下元素類型之一作為其值：

ElementType.ANNOTATION_TYPE可以應(yīng)用于注解類型。

ElementType.CONSTRUCTOR可以應(yīng)用于構(gòu)造函數(shù)。

ElementType.FIELD可以應(yīng)用于字段或?qū)傩浴?/p>

ElementType.LOCAL_VARIABLE可以應(yīng)用于局部變量。

ElementType.METHOD可以應(yīng)用于方法級(jí)注解。

ElementType.PACKAGE可以應(yīng)用于包聲明。

ElementType.PARAMETER可以應(yīng)用于方法的參數(shù)。

ElementType.TYPE可以應(yīng)用于類的任何元素。

@Inherited：@Inherited注解表明注解類型可以從超類繼承（默認(rèn)情況下不是這樣），當(dāng)用戶查詢注解類型并且該類沒有此類型的注解時(shí)，將查詢類的超類以獲取注解類型，此注解僅適用于類聲明。

@Repeatable：Java SE 8中引入的@Repeatable注解表明標(biāo)記的注解可以多次應(yīng)用于相同的聲明或類型使用，有關(guān)更多信息，請參閱重復(fù)注解。

在Java SE 8發(fā)行版之前，注解只能應(yīng)用于聲明，從Java SE 8發(fā)行版開始，注解也可以應(yīng)用于任何類型的使用，這意味著可以在任何使用類型的地方使用注解。使用類型的一些示例包括類實(shí)例創(chuàng)建表達(dá)式(new)、類型轉(zhuǎn)換、implements子句和throws子句，這種注解形式稱為類型注解，注解基礎(chǔ)知識(shí)中提供了幾個(gè)示例。

創(chuàng)建類型注解是為了支持改進(jìn)的Java程序分析，以確保更強(qiáng)的類型檢查，Java SE 8版本不提供類型檢查框架，但它允許你編寫（或下載）類型檢查框架，該框架實(shí)現(xiàn)為與Java編譯器結(jié)合使用的一個(gè)或多個(gè)可插拔模塊。

例如，你希望確保程序中的特定變量永遠(yuǎn)不會(huì)分配給null，你想避免觸發(fā)NullPointerException，你可以編寫自定義插件來檢查此問題，然后，你將修改代碼以注解該特定變量，表明它永遠(yuǎn)不會(huì)被賦值為null，變量聲明可能如下所示：

@NonNull String str;

當(dāng)你編譯代碼（包括命令行中的NonNull模塊）時(shí)，編譯器會(huì)在檢測到潛在問題時(shí)輸出警告，允許你修改代碼以避免錯(cuò)誤，在更正代碼以移除所有警告后，程序運(yùn)行時(shí)不會(huì)發(fā)生此特定錯(cuò)誤。

你可以使用多個(gè)類型檢查模塊，其中每個(gè)模塊檢查不同類型的錯(cuò)誤，通過這種方式，你可以在Java類型系統(tǒng)的基礎(chǔ)上構(gòu)建，在你希望的時(shí)間和位置添加特定的檢查。

通過明智地使用類型注解和可插拔類型檢查器，你可以編寫更強(qiáng)大且更不容易出錯(cuò)的代碼。

在許多情況下，你不必編寫自己的類型檢查模塊，有第三方為你完成了這項(xiàng)工作，例如，你可能希望利用華盛頓大學(xué)創(chuàng)建的Checker Framework，該框架包括NonNull模塊、正則表達(dá)式模塊和互斥鎖模塊，有關(guān)更多信息，請參閱Checker Framework。

在某些情況下，你希望將相同的注解應(yīng)用于聲明或類型用途，從Java SE 8發(fā)行版開始，重復(fù)注解使你可以執(zhí)行此操作。

例如，你正在編寫代碼以使用計(jì)時(shí)器服務(wù)，該服務(wù)使你能夠在給定時(shí)間或某個(gè)計(jì)劃上運(yùn)行方法，類似于UNIX cron服務(wù)，現(xiàn)在你要設(shè)置一個(gè)計(jì)時(shí)器來運(yùn)行一個(gè)方法doPeriodicCleanup，在該月的最后一天和每個(gè)星期五晚上11點(diǎn)運(yùn)行，要設(shè)置要運(yùn)行的計(jì)時(shí)器，請創(chuàng)建一個(gè)@Schedule注解并將其應(yīng)用于doPeriodicCleanup方法兩次，第一次使用指定月份的最后一天，第二次使用指定星期五晚上11點(diǎn)，如下面的代碼示例所示：

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }

前面的示例將注解應(yīng)用于方法，你可以在使用標(biāo)準(zhǔn)注解的任何位置重復(fù)注解，例如，你有一個(gè)用于處理未授權(quán)訪問異常的類，你可以使用一個(gè)@Alert注解為管理者注解該類，為管理員注解另一個(gè)注解：

@Alert(role="Manager")
@Alert(role="Administrator")
public class UnauthorizedAccessException extends SecurityException { ... }

出于兼容性原因，重復(fù)注解存儲(chǔ)在由Java編譯器自動(dòng)生成的容器注解中，為了使編譯器執(zhí)行此操作，代碼中需要兩個(gè)聲明。

注解類型必須使用@Repeatable元注解進(jìn)行標(biāo)記，以下示例定義自定義@Schedule可重復(fù)注解類型：

@Repeatable(Schedules.class)
public @interface Schedule {
  String dayOfMonth() default "first";
  String dayOfWeek() default "Mon";
  int hour() default 12;
}

@Repeatable元注解的值（在括號(hào)中）是Java編譯器生成的用于存儲(chǔ)重復(fù)注解的容器注解的類型，在此示例中，包含注解類型是Schedules，因此重復(fù)@Schedule注解存儲(chǔ)在@Schedules注解中。

將相同的注解應(yīng)用于聲明而不首先聲明它是可重復(fù)的，這會(huì)導(dǎo)致編譯時(shí)錯(cuò)誤。

包含注解類型必須具有帶數(shù)組類型的value元素，數(shù)組類型的組件類型必須是可重復(fù)的注解類型，包含注解類型的Schedules的聲明如下：

public @interface Schedules {
    Schedule[] value();
}

Reflection API中有幾種可用于檢索注解的方法，返回單個(gè)注解的方法（例如AnnotatedElement.getAnnotation(Class)）的行為未更改，因?yàn)槿绻嬖谒埱箢愋偷囊粋€(gè)注解，它們僅返回單個(gè)注解，如果存在多個(gè)所請求類型的注解，則可以通過首先獲取其容器注解來獲取它們，通過這種方式，遺留代碼繼續(xù)工作。Java SE 8中引入了其他方法，它們掃描容器注解以一次返回多個(gè)注解，例如AnnotatedElement.getAnnotationsByType(Class)，有關(guān)所有可用方法的信息，請參閱AnnotatedElement類規(guī)范。

設(shè)計(jì)注解類型時(shí)，必須考慮該類型注解的基數(shù)，現(xiàn)在可以使用注解零次、一次，或者，如果注解的類型標(biāo)記為@Repeatable，則不止一次，通過使用@Target元注解，還可以限制注解類型的使用位置。例如，你可以創(chuàng)建只能在方法和字段上使用的可重復(fù)注解類型，仔細(xì)設(shè)計(jì)注解類型非常重要，以確保使用注解的程序員發(fā)現(xiàn)它盡可能靈活和強(qiáng)大。