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

編程的一個(gè)最新的趨勢(shì)，尤其是在 Java 編程方面，是使用 元數(shù)據(jù) 。簡(jiǎn)單地說(shuō)，元數(shù)據(jù)就是 關(guān)于 數(shù)據(jù)的數(shù)據(jù)。元數(shù)據(jù)可以用于創(chuàng)建文檔，跟蹤代碼中的依賴性，甚至執(zhí)行基本編譯時(shí)檢查。許多元數(shù)據(jù)工具，如 XDoclet（請(qǐng)參閱 參考資料 ），將這些功能添加到核心 Java 語(yǔ)言中，暫時(shí)成為 Java 編程功能的一部分。

直到可以使用 J2SE 5.0（也叫做 Tiger，現(xiàn)在是第二個(gè) beta 版本），核心 Java 語(yǔ)言才最接近具有 Javadoc 方法的元數(shù)據(jù)工具。您使用特殊的標(biāo)簽集合來(lái)標(biāo)記代碼，并執(zhí)行 javadoc 命令來(lái)將這些標(biāo)簽轉(zhuǎn)化成格式化的 HTML 頁(yè)面，該頁(yè)面說(shuō)明標(biāo)簽所附加到的類。然而，Javadoc 是有缺陷的元數(shù)據(jù)工具，因?yàn)槌松晌臋n之外，您沒(méi)有固定、實(shí)用、標(biāo)準(zhǔn)化的方式來(lái)將數(shù)據(jù)用于其他用途。HTML 代碼經(jīng)常混入到 Javadoc 輸出中這一事實(shí)甚至更進(jìn)一步降低了其用于任何其他目的的價(jià)值。

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

元數(shù)據(jù)的價(jià)值

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

編譯器檢查

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

代碼分析

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

回頁(yè)首

注釋的基本知識(shí)

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

注釋分為三個(gè)基本種類：

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

除了通過(guò)默認(rèn)語(yǔ)法向注釋提供值外，還可以在需要傳送多個(gè)值時(shí)使用名稱-值對(duì)。還可以通過(guò)花括號(hào)為注釋變量提供值數(shù)組。清單 1 顯示了注釋中的值數(shù)組的示例。

            @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 中的示例并沒(méi)有乍一看那樣復(fù)雜。 TODOItems 注釋類型有一個(gè)具有值的變量。這里提供的值比較復(fù)雜，但 TODOItems 的使用實(shí)際與單一值注釋類型相符，只是這里的單一值是數(shù)組而已。該數(shù)組包含三個(gè) TODO 注釋，其中每個(gè)注釋都是多值的。逗號(hào)分隔每個(gè)注釋內(nèi)的值，以及單個(gè)數(shù)組內(nèi)的值。非常容易，是吧？

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

回頁(yè)首

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 應(yīng)該很容易理解。 @Override 注釋對(duì)兩個(gè)方法進(jìn)行了注釋 — toString() 和 hashCode() ，來(lái)指明它們覆蓋 OverrideTester 類的超類 ( java.lang.Object ) 中的方法的版本。開始這可能看起來(lái)沒(méi)什么作用，但它實(shí)際上是非常好的功能。如果不覆蓋這些方法，根本 無(wú)法 編譯此類。該注釋還確保當(dāng)您將 toString() 弄亂時(shí)，至少還有某種指示，即應(yīng)該確保 hashCode() 仍舊匹配。

當(dāng)編碼到很晚且輸錯(cuò)了某些東西時(shí)，此注釋類型真的可以發(fā)揮很大的作用，如清單 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() 錯(cuò)誤地輸入為 hasCode() 。注釋指明 hasCode() 應(yīng)該覆蓋方法。但是在編譯中， javac 將發(fā)現(xiàn)超類 ( java.lang.Object ) 沒(méi)有名為 hasCode() 的方法可以覆蓋。因此，編譯器將報(bào)錯(cuò)，如圖 1 中所示。

圖 1. 來(lái)自 Override 注釋的編譯器警告

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

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

回頁(yè)首

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
            

              }
            

            }
            

          

單獨(dú)編譯此類時(shí)，不會(huì)發(fā)生任何不同。但是如果通過(guò)覆蓋或調(diào)用來(lái)使用聲明為過(guò)時(shí)的方法，編譯器將處理注釋，發(fā)現(xiàn)不應(yīng)該使用該方法，并發(fā)出錯(cuò)誤消息，如圖 2 中所示。

圖 2. 來(lái)自 Deprecated 注釋的編譯器警告

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

回頁(yè)首

SuppressWarnings 注釋

SupressWarnings 可以解決這個(gè)問(wèn)題。 SupressWarnings 與 Override 和 Deprecated 不同， 是 具有變量的 — 所以您將單一注釋類型與該變量一起使用。可以以值數(shù)組來(lái)提供變量，其中每個(gè)值指明要阻止的一種特定警告類型。請(qǐng)看清單 5 中的示例，這是 Tiger 中通常會(huì)產(chǎn)生錯(cuò)誤的一些代碼。

            public void nonGenericsMethod() {
            

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

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

            }
            

          

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

圖 3. 來(lái)自非標(biāo)準(zhǔn)代碼的編譯器警告

清單 6 通過(guò)使用 SuppressWarnings 注釋消除了這種問(wèn)題。

            @SuppressWarings(value={"unchecked"})
            

            public void nonGenericsMethod() {
            

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

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

            }
            

          

非常簡(jiǎn)單，是吧？?jī)H需要找到警告類型（圖 3 中顯示為“unchecked”），并將其傳送到 SuppressWarnings 中。

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

注釋 向 Java 代碼中添加元數(shù)據(jù)