級別: 初級

Brett McLaughlin, 作者/編者, O‘Reilly Media, Inc

2004 年 9 月 01 日

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

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

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

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

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

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

編譯器檢查

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

代碼分析

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

回頁首

注釋的基本知識

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

注釋分為三個基本種類：

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

除了通過默認(rèn)語法向注釋提供值外,，還可以在需要傳送多個值時使用名稱-值對,。還可以通過花括號為注釋變量提供值數(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 中的示例并沒有乍一看那樣復(fù)雜,。 TODOItems 注釋類型有一個具有值的變量。這里提供的值比較復(fù)雜,，但 TODOItems 的使用實(shí)際與單一值注釋類型相符,，只是這里的單一值是數(shù)組而已。該數(shù)組包含三個 TODO 注釋,，其中每個注釋都是多值的,。逗號分隔每個注釋內(nèi)的值，以及單個數(shù)組內(nèi)的值。非常容易,，是吧,？

但是我講的可能超前了些。 TODOItems 和 TODO 是 定制注釋,，是本系列文章第 2 部分中的主題,。但是我想讓您看到，即使復(fù)雜注釋（清單 1 幾乎是最復(fù)雜的注釋）也不是非常令人害怕的,。當(dāng)提到 Java 語言的標(biāo)準(zhǔn)注釋類型時，將很少看到如此復(fù)雜的情況,。正如將在下面三個部分了解到的,，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 應(yīng)該很容易理解,。 @Override 注釋對兩個方法進(jìn)行了注釋 — toString() 和 hashCode() ,，來指明它們覆蓋 OverrideTester 類的超類 ( java.lang.Object ) 中的方法的版本,。開始這可能看起來沒什么作用，但它實(shí)際上是非常好的功能,。如果不覆蓋這些方法,，根本 無法 編譯此類。該注釋還確保當(dāng)您將 toString() 弄亂時,，至少還有某種指示,，即應(yīng)該確保 hashCode() 仍舊匹配。

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

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

缺少的功能 在單一值注釋類型中，如果 Deprecated 允許包含錯誤類型消息將更好,。然后,，當(dāng)用戶使用聲明為過時的方法時，編譯器可以打印消息,。該消息可以指明使用方法的結(jié)果如何重要,，說明何時將停止方法，甚至建議備用方法,?？赡?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
                        }
                        }
                        

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

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

注意需要開啟編譯器警告,，就像是必須向 Java 編譯器指明想要普通的聲明為過時警告?？梢允褂孟铝袃蓚€標(biāo)記之一和 javac 命令： -deprecated 或新的 -Xlint:deprecated 標(biāo)記。

回頁首

SuppressWarnings 注釋

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

                        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. 來自非標(biāo)準(zhǔn)代碼的編譯器警告

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

回頁首