注釋，J2SE 5.0 (Tiger) 中的新功能，將非常需要的元數據工具引入核心 Java 語言。該系列文章分為兩部分，在這第 1 部分中，作者 Brett McLaughlin 解釋了元數據如此有用的原因，向您介紹了 Java 語言中的注釋，并研究了 Tiger 的內置注釋。

編程的一個最新的趨勢，尤其是在 Java 編程方面，是使用 元數據 。簡單地說，元數據就是 關于 數據的數據。元數據可以用于創建文檔，跟蹤代碼中的依賴性，甚至執行基本編譯時檢查。許多元數據工具，如 XDoclet（請參閱 參考資料 ），將這些功能添加到核心 Java 語言中，暫時成為 Java 編程功能的一部分。

直到可以使用 J2SE 5.0（也叫做 Tiger，現在是第二個 beta 版本），核心 Java 語言才最接近具有 Javadoc 方法的元數據工具。您使用特殊的標簽集合來標記代碼，并執行 javadoc 命令來將這些標簽轉化成格式化的 HTML 頁面，該頁面說明標簽所附加到的類。然而，Javadoc 是有缺陷的元數據工具，因為除了生成文檔之外，您沒有固定、實用、標準化的方式來將數據用于其他用途。HTML 代碼經常混入到 Javadoc 輸出中這一事實甚至更進一步降低了其用于任何其他目的的價值。

Tiger 通過名為 注釋 的新功能將一個更通用的元數據工 具合并到核心 Java 語言中。注釋是可以添加到代碼中的修飾符，可以用于包聲明、類型聲明、構造函數、方法、字段、參數和變量。Tiger 包含內置注釋，還支持您自己編寫的定制注釋。本文將概述元數據的優點并向您介紹 Tiger 的內置注釋。本系列文章的 第 2 部分 將研究定制注釋。我要感謝 O'Reilly Media, Inc.，他們非常慷慨地 允許我在本文中使用我關于 Tiger 的書籍的“注釋”一章中的代碼示例（請參閱 參考資料 ）。

元數據的價值

不要漏掉本系列的另一部分 一定要閱讀本系列的“ 第 2 部分 ”，該部分研究了定制注釋。

編譯器檢查

JSR 175 JSR 175， Java 編程語言的元數據工具 ，為將元數據合并到核心 Java 語言中提供了正式理由和說明（請參閱 參考資料 ）。根據 JSR，注釋“不直接影響程序的語義。然而，開發和部署工具可以讀取這些注釋，并以某種形式處理這些注釋，可能生成其他 Java 編程語言源文件、XML 文檔或要與包含注釋的程序一起使用的其他構件。”

代碼分析

在 更復雜的情況下，代碼分析工具可以執行所有種類的額外任務。示例 du jour 是 Enterprise JavaBean (EJB) 組件。甚至簡單 EJB 系統中的依賴性和復雜性都非常令人吃驚。您具有了 home 接口和遠程接口，以及本地接口和本地 home 接口，還有一個實現類。保持所有這些類同步非常困難。但是，元數據可以提供這個問題的解決放案。好的工具（還是要提一下 XDoclet）可以管理所有這些依賴性，并確保無“代碼級”連接、但有“邏輯級”捆綁的類保持同步。元數據在這里確實可以發揮它的作用。

回頁首

注釋的基本知識

注釋或注釋類型？ 是否對什么是注釋與什么是注釋類型感到迷惑？了解這個的最簡單方法就是對比所熟悉的 Java 語言概念來想。可以定義一個類（例如 Person ），則在 JVM 中將總是僅有該類的一個版本（假設沒有進行麻煩的類路徑設置）。然而，在任何給定時間，可能會使用該類的 10 個或 20 個 實例 。仍然是只有一個 Person 類，但是它以不同的方式使用多次。注釋類型和注釋也是這樣。注釋類型類似于類，注釋類似于該類的實例。

注釋分為三個基本種類：

• 標記注釋 沒有變量。注釋顯示簡單，由名稱標識，沒有提供其他數據。例如， @MarkerAnnotation 是標記注釋。它不包含數據，僅有注釋名稱。
  
  
• 單一值注釋 與標記注釋類似，但提供一段數據。因為僅提供很少的一點數據，所以可以使用快捷語法（假設注釋類型接受此語法）： @SingleValueAnnotation("my data") 。除了 @ 標記外，這應該與普通的 Java 方法調用很像。
  
  
• 完整注釋 有多個數據成員。因此，必須使用更完整的語法（注釋不再像普通的 Java 方法）： @FullAnnotation(var1="data value 1", var2="data value 2", var3="data value 3") 。

除了通過默認語法向注釋提供值外，還可以在需要傳送多個值時使用名稱-值對。還可以通過花括號為注釋變量提供值數組。清單 1 顯示了注釋中的值數組的示例。

            @TODOItems({    // Curly braces indicate an array of values is being supplied
            

              @TODO(
            

                severity=TODO.CRITICAL,
            

                item="Add functionality to calculate the mean of the student's grades",
            

                assignedTo="Brett McLaughlin"
            

              ),
            

              @TODO(
            

                severity=TODO.IMPOTANT,
            

                item="Print usage message to screen if no command-line flags specified",
            

                assignedTo="Brett McLaughlin"
            

              ),
            

              @TODO(
            

                severity=TODO.LOW,
            

                item="Roll a new website page with this class's new features",
            

                assignedTo="Jason Hunter"
            

              )
            

            })
            

          

清單 1 中的示例并沒有乍一看那樣復雜。 TODOItems 注釋類型有一個具有值的變量。這里提供的值比較復雜，但 TODOItems 的使用實際與單一值注釋類型相符，只是這里的單一值是數組而已。該數組包含三個 TODO 注釋，其中每個注釋都是多值的。逗號分隔每個注釋內的值，以及單個數組內的值。非常容易，是吧？

但是我講的可能超前了些。 TODOItems 和 TODO 是 定制注釋 ， 是本系列文章第 2 部分中的主題。但是我想讓您看到，即使復雜注釋（清單 1 幾乎是最復雜的注釋）也不是非常令人害怕的。當提到 Java 語言的標準注釋類型時，將很少看到如此復雜的情況。正如將在下面三個部分了解到的，Tiger 的基本注釋類型的使用都極其簡單。

回頁首

Override 注釋

            package com.oreilly.tiger.ch06;
            

            public class OverrideTester {
            

              public OverrideTester() { }
            

              @Override
            

              public String toString() {
            

                return super.toString() + " [Override Tester Implementation]";
            

              }
            

              @Override
            

              public int hashCode() {
            

                return toString().hashCode();
            

              }
            

            }
            

          

清單 2 應該很容易理解。 @Override 注釋對兩個方法進行了注釋 — toString() 和 hashCode() ，來指明它們覆蓋 OverrideTester 類的超類 ( java.lang.Object ) 中的方法的版本。開始這可能看起來沒什么作用，但它實際上是非常好的功能。如果不覆蓋這些方法，根本 無法 編譯此類。該注釋還確保當您將 toString() 弄亂時，至少還有某種指示，即應該確保 hashCode() 仍舊匹配。

當編碼到很晚且輸錯了某些東西時，此注釋類型真的可以發揮很大的作用，如清單 3 中所示。

            package com.oreilly.tiger.ch06;
            

            public class OverrideTester {
            

              public OverrideTester() { }
            

              @Override
            

              public String toString() {
            

                return super.toString() + " [Override Tester Implementation]";
            

              }
            

              @Override
            

            public int hasCode() {
            

                return toString().hashCode();
            

              }
            

            }
            

          

在清單 3 中， hashCode() 錯誤地輸入為 hasCode() 。注釋指明 hasCode() 應該覆蓋方法。但是在編譯中， javac 將發現超類 ( java.lang.Object ) 沒有名為 hasCode() 的方法可以覆蓋。因此，編譯器將報錯，如圖 1 中所示。

圖 1. 來自 Override 注釋的編譯器警告

缺少的功能 在單一值注釋類型中，如果 Deprecated 允許包含錯誤類型消息將更好。然后，當用戶使用聲明為過時的方法時，編譯器可以打印消息。該消息可以指明使用方法的結果如何重要，說明何時將停止方法，甚至建議備用方法。可能 J2SE 的下一版本（“Mustang”，他們這樣命名）將提供這種功能。

這個便捷的小功能將幫助快速捕獲打字稿。

回頁首

Deprecated 注釋

            package com.oreilly.tiger.ch06;
            

            public class DeprecatedClass {
            

              @Deprecated public void doSomething() {
            

                // some code
            

              }
            

              public void doSomethingElse() {
            

                // This method presumably does what doSomething() does, but better
            

              }
            

            }
            

          

單獨編譯此類時，不會發生任何不同。但是如果通過覆蓋或調用來使用聲明為過時的方法，編譯器將處理注釋，發現不應該使用該方法，并發出錯誤消息，如圖 2 中所示。

圖 2. 來自 Deprecated 注釋的編譯器警告

注意需要開啟編譯器警告，就像是必須向 Java 編譯器指明想要普通的聲明為過時警告。可以使用下列兩個標記之一和 javac 命令： -deprecated 或新的 -Xlint:deprecated 標記。

回頁首

SuppressWarnings 注釋

SupressWarnings 可以解決這個問題。 SupressWarnings 與 Override 和 Deprecated 不同， 是 具有變量的 — 所以您將單一注釋類型與該變量一起使用。可以以值數組來提供變量，其中每個值指明要阻止的一種特定警告類型。請看清單 5 中的示例，這是 Tiger 中通常會產生錯誤的一些代碼。

            public void nonGenericsMethod() {
            

              List wordList = new ArrayList();    // no typing information on the List
            

              wordList.add("foo");                // causes error on list addition
            

            }
            

          

圖 3 顯示了清單 5 中代碼的編譯結果。

圖 3. 來自非標準代碼的編譯器警告

清單 6 通過使用 SuppressWarnings 注釋消除了這種問題。

            @SuppressWarings(value={"unchecked"})
            

            public void nonGenericsMethod() {
            

              List wordList = new ArrayList();    // no typing information on the List
            

              wordList.add("foo");                // causes error on list addition
            

            }
            

          

非常簡單，是吧？僅需要找到警告類型（圖 3 中顯示為“unchecked”），并將其傳送到 SuppressWarnings 中。

SuppressWarnings 中變量的值采用數組，使您可以在同一注釋中阻止多個警告。例如， @SuppressWarnings(value={"unchecked", "fallthrough"}) 使用兩個值的數組。此功能為處理錯誤提供了非常靈活的方法，無需進行大量的工作。

注釋 向 Java 代碼中添加元數據