級別: 初級

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ù)工具。您使用特殊的標簽集合來標記代碼，并執(zhí)行 javadoc 命令來將這些標簽轉(zhuǎn)化成格式化的 HTML 頁面，該頁面說明標簽所附加到的類。然而，Javadoc 是有缺陷的元數(shù)據(jù)工具，因為除了生成文檔之外，您沒有固定、實用、標準化的方式來將數(shù)據(jù)用于其他用途。HTML 代碼經(jīng)常混入到 Javadoc 輸出中這一事實甚至更進一步降低了其用于任何其他目的的價值。

Tiger 通過名為 注釋的新功能將一個更通用的元數(shù)據(jù)工具合并到核心 Java 語言中。注釋是可以添加到代碼中的修飾符，可以用于包聲明、類型聲明、構(gòu)造函數(shù)、方法、字段、參數(shù)和變量。Tiger 包含內(nèi)置注釋，還支持您自己編寫的定制注釋。本文將概述元數(shù)據(jù)的優(yōu)點并向您介紹 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 接口和遠程接口，以及本地接口和本地 home 接口，還有一個實現(xiàn)類。保持所有這些類同步非常困難。但是，元數(shù)據(jù)可以提供這個問題的解決放案。好的工具（還是要提一下 XDoclet）可以管理所有這些依賴性，并確保無“代碼級”連接、但有“邏輯級”捆綁的類保持同步。元數(shù)據(jù)在這里確實可以發(fā)揮它的作用。

回頁首

注釋的基本知識

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

注釋分為三個基本種類：

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

除了通過默認語法向注釋提供值外，還可以在需要傳送多個值時使用名稱-值對。還可以通過花括號為注釋變量提供值數(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ù)組包含三個 TODO 注釋，其中每個注釋都是多值的。逗號分隔每個注釋內(nèi)的值，以及單個數(shù)組內(nèi)的值。非常容易，是吧？

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

當編碼到很晚且輸錯了某些東西時，此注釋類型真的可以發(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 允許包含錯誤類型消息將更好。然后，當用戶使用聲明為過時的方法時，編譯器可以打印消息。該消息可以指明使用方法的結(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
                        }
                        }
                        

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

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

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

回頁首

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. 來自非標準代碼的編譯器警告

清單 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ù)組。此功能為處理錯誤提供了非常靈活的方法，無需進行大量的工作。

回頁首