如何使用 Java 5 的內置注釋
注釋?zhuān)琂2SE 5.0 (Tiger) 中的新功能，將非常需要的元數據工具引入核心 Java 語(yǔ)言。該系列文章分為兩部分，在這第 1 部分中，作者 Brett McLaughlin 解釋了元數據如此有用的原因，向您介紹了 Java 語(yǔ)言中的注釋?zhuān)⒀芯苛?Tiger 的內置注釋。
編程的一個(gè)最新的趨勢，尤其是在 Java 編程方面，是使用 元數據。簡(jiǎn)單地說(shuō)，元數據就是 關(guān)于數據的數據。元數據可以用于創(chuàng )建文檔，跟蹤代碼中的依賴(lài)性，甚至執行基本編譯時(shí)檢查。許多元數據工具，如 XDoclet（請參閱 參考資料），將這些功能添加到核心 Java 語(yǔ)言中，暫時(shí)成為 Java 編程功能的一部分。
直到可以使用 J2SE 5.0（也叫做 Tiger，現在是第二個(gè) beta 版本），核心 Java 語(yǔ)言才最接近具有 Javadoc 方法的元數據工具。您使用特殊的標簽集合來(lái)標記代碼，并執行 javadoc 命令來(lái)將這些標簽轉化成格式化的 HTML 頁(yè)面，該頁(yè)面說(shuō)明標簽所附加到的類(lèi)。然而，Javadoc 是有缺陷的元數據工具，因為除了生成文檔之外，您沒(méi)有固定、實(shí)用、標準化的方式來(lái)將數據用于其他用途。HTML 代碼經(jīng)?；烊氲?Javadoc 輸出中這一事實(shí)甚至更進(jìn)一步降低了其用于任何其他目的的價(jià)值。
Tiger 通過(guò)名為 注釋的新功能將一個(gè)更通用的元數據工具合并到核心 Java 語(yǔ)言中。注釋是可以添加到代碼中的修飾符，可以用于包聲明、類(lèi)型聲明、構造函數、方法、字段、參數和變量。Tiger 包含內置注釋?zhuān)€支持您自己編寫(xiě)的定制注釋。本文將概述元數據的優(yōu)點(diǎn)并向您介紹 Tiger 的內置注釋。本系列文章的 第 2 部分將研究定制注釋。我要感謝 O‘Reilly Media, Inc.，他們非?？犊?允許我在本文中使用我關(guān)于 Tiger 的書(shū)籍的“注釋”一章中的代碼示例。
一般來(lái)說(shuō)，元數據的好處分為三類(lèi)：文檔編制、編譯器檢查和代碼分析。代碼級文檔最常被引用。元數據提供了一種有用的方法來(lái)指明方法是否取決于其他方法，它們是否完整，特定類(lèi)是否必須引用其他類(lèi)，等等。這確實(shí)非常有用，但對于將元數據添加到 Java 語(yǔ)言中來(lái)說(shuō)，文檔編制可能是 最不相關(guān)的理由。Javadoc 已經(jīng)提供了非常容易理解和健壯的方法來(lái)文檔化代碼。另外，當已經(jīng)存在文檔編制工具，并且在大多數時(shí)候都工作得很好時(shí)，誰(shuí)還要編寫(xiě)文檔編制工具？
 |
元數據更重要的優(yōu)點(diǎn)是編譯器可以使用它來(lái)執行基本的編譯時(shí)檢查。例如，您將在本文后面的 Override 注釋中看到 Tiger 引入了一個(gè)這樣的注釋?zhuān)糜谠试S您指定一種方法覆蓋超類(lèi)中的另一種方法。Java 編譯器可以確保在元數據中指明的行為實(shí)際發(fā)生在代碼級別。如果從來(lái)沒(méi)有找出過(guò)這種類(lèi)型的 bug，這樣做似乎有點(diǎn)傻，但是大多數年齡很大的 Java 編程老手都曾經(jīng)花費至少多個(gè)晚上來(lái)查明他們的代碼為什么不能用。當最后認識到方法的參數有錯，且該方法實(shí)際上 沒(méi)有 覆蓋超類(lèi)中的方法時(shí)，您可能更感到難受。使用元數據的工具有助于輕松地查明這種類(lèi)型的錯誤，從而可以節省那些晚上來(lái)看長(cháng)期進(jìn)行的 Halo 聯(lián)賽。
 |
|
可以證明，任何好的注釋或元數據工具的最好功能就是可以使用額外數據來(lái)分析代碼。在一個(gè)簡(jiǎn)單的案例中，您可能構建代碼目錄，提供必需的輸入類(lèi)型并指明返回類(lèi)型。但是，您可能想，Java 反射具有相同的優(yōu)點(diǎn)；畢竟，可以為所有這些信息內省代碼。這從表面上看似乎是正確的，但是在實(shí)際中通常不使用。許多時(shí)候，方法作為輸入接受的或者作為輸出返回的類(lèi)型實(shí)際上不是該方法想要的類(lèi)型。例如，參數類(lèi)型可能是 Object ，但方法可能僅使用 Integer 。這在好些情況下很容易發(fā)生，比如在方法被覆蓋而超類(lèi)使用常規參數聲明方法時(shí)，還有正在進(jìn)行許多序列化的系統中也容易發(fā)生。在這兩種情況中，元數據可以指示代碼分析工具，雖然參數類(lèi)型是 Object ，但 Integer 才是真正需要的。這類(lèi)分析非常有用，但也不能夸大它的價(jià)值。
在更復雜的情況下，代碼分析工具可以執行所有種類(lèi)的額外任務(wù)。示例 du jour 是 Enterprise JavaBean (EJB) 組件。甚至簡(jiǎn)單 EJB 系統中的依賴(lài)性和復雜性都非常令人吃驚。您具有了 home 接口和遠程接口，以及本地接口和本地 home 接口，還有一個(gè)實(shí)現類(lèi)。保持所有這些類(lèi)同步非常困難。但是，元數據可以提供這個(gè)問(wèn)題的解決放案。好的工具（還是要提一下 XDoclet）可以管理所有這些依賴(lài)性，并確保無(wú)“代碼級”連接、但有“邏輯級”捆綁的類(lèi)保持同步。元數據在這里確實(shí)可以發(fā)揮它的作用。
 |
現在已經(jīng)了解了元數據的好處，我將介紹 Tiger 中的注釋。注釋采用“at”標記形式 ( @ )，后面是注釋名稱(chēng)。然后在需要數據時(shí)，通過(guò) name=value 對向注釋提供數據。每次使用這類(lèi)表示法時(shí)，就是在生成注釋。一段代碼可能會(huì )有 10 個(gè)、50 個(gè)或更多的注釋。不過(guò)，您將發(fā)現多個(gè)注釋都可能使用相同的 注釋類(lèi)型。類(lèi)型是實(shí)際使用的結構，在特定上下文中，注釋本身是該類(lèi)型的具體使用（請參閱側欄 注釋或注釋類(lèi)型？）。
 |
|
注釋分為三個(gè)基本種類(lèi)：
@MarkerAnnotation 是標記注釋。它不包含數據，僅有注釋名稱(chēng)。 @SingleValueAnnotation("my data") 。除了 @ 標記外，這應該與普通的 Java 方法調用很像。 @FullAnnotation(var1="data value 1", var2="data value 2", var3="data value 3") 。 除了通過(guò)默認語(yǔ)法向注釋提供值外，還可以在需要傳送多個(gè)值時(shí)使用名稱(chēng)-值對。還可以通過(guò)花括號為注釋變量提供值數組。清單 1 顯示了注釋中的值數組的示例。
|
清單 1 中的示例并沒(méi)有乍一看那樣復雜。 TODOItems 注釋類(lèi)型有一個(gè)具有值的變量。這里提供的值比較復雜，但 TODOItems 的使用實(shí)際與單一值注釋類(lèi)型相符，只是這里的單一值是數組而已。該數組包含三個(gè) TODO 注釋?zhuān)渲忻總€(gè)注釋都是多值的。逗號分隔每個(gè)注釋內的值，以及單個(gè)數組內的值。非常容易，是吧？
但是我講的可能超前了些。 TODOItems 和 TODO 是 定制注釋，是本系列文章第 2 部分中的主題。但是我想讓您看到，即使復雜注釋?zhuān)ㄇ鍐?1 幾乎是最復雜的注釋?zhuān)┮膊皇欠浅Ａ钊撕ε碌?。當提?Java 語(yǔ)言的標準注釋類(lèi)型時(shí)，將很少看到如此復雜的情況。正如將在下面三個(gè)部分了解到的，Tiger 的基本注釋類(lèi)型的使用都極其簡(jiǎn)單。
 |
Tiger 的第一個(gè)內置注釋類(lèi)型是 Override 。 Override 應該僅用于方法（不用于類(lèi)、包聲明或其他構造）。它指明注釋的方法將覆蓋超類(lèi)中的方法。清單 2 顯示了簡(jiǎn)單的示例。 清單 2. 操作中的 Override 注釋
|
清單 2 應該很容易理解。 @Override 注釋對兩個(gè)方法進(jìn)行了注釋 — toString() 和 hashCode() ，來(lái)指明它們覆蓋 OverrideTester 類(lèi)的超類(lèi) ( java.lang.Object ) 中的方法的版本。開(kāi)始這可能看起來(lái)沒(méi)什么作用，但它實(shí)際上是非常好的功能。如果不覆蓋這些方法，根本 無(wú)法 編譯此類(lèi)。該注釋還確保當您將 toString() 弄亂時(shí)，至少還有某種指示，即應該確保 hashCode() 仍舊匹配。
當編碼到很晚且輸錯了某些東西時(shí)，此注釋類(lèi)型真的可以發(fā)揮很大的作用，如清單 3 中所示。
|
在清單 3 中， hashCode() 錯誤地輸入為 hasCode() 。注釋指明 hasCode() 應該覆蓋方法。但是在編譯中， javac 將發(fā)現超類(lèi) ( java.lang.Object ) 沒(méi)有名為 hasCode() 的方法可以覆蓋。因此，編譯器將報錯，如圖 1 中所示。
圖 1. 來(lái)自 Override 注釋的編譯器警告
|
|
這個(gè)便捷的小功能將幫助快速捕獲打字稿。
|
下一個(gè)標準注釋類(lèi)型是 Deprecated 。與 Override 一樣， Deprecated 是標記注釋。正如您可能期望的，可以使用 Deprecated 來(lái)對不應再使用的方法進(jìn)行注釋。與 Override 不一樣的是， Deprecated 應該與正在聲明為過(guò)時(shí)的方法放在同一行中（為什么這樣？說(shuō)實(shí)話(huà)我也不知道），如清單 4 中所示。 清單 4. 使用 Deprecated 注釋
|
單獨編譯此類(lèi)時(shí)，不會(huì )發(fā)生任何不同。但是如果通過(guò)覆蓋或調用來(lái)使用聲明為過(guò)時(shí)的方法，編譯器將處理注釋?zhuān)l(fā)現不應該使用該方法，并發(fā)出錯誤消息，如圖 2 中所示。
圖 2. 來(lái)自 Deprecated 注釋的編譯器警告
注意需要開(kāi)啟編譯器警告，就像是必須向 Java 編譯器指明想要普通的聲明為過(guò)時(shí)警告?？梢允褂孟铝袃蓚€(gè)標記之一和 javac 命令： -deprecated 或新的 -Xlint:deprecated 標記。
|
從 Tiger “免費”獲得的最后一個(gè)注釋類(lèi)型是 SuppressWarnings 。發(fā)現該類(lèi)型的作用應該不難，但是 為什么該注釋類(lèi)型如此重要通常不是很明顯。它實(shí)際上是 Tiger 的所有新功能的副功能。例如，以泛型為例；泛型使所有種類(lèi)的新類(lèi)型安全操作成為可能，特別是當涉及 Java 集合時(shí)。然而，因為泛型，當使用集合而 沒(méi)有 類(lèi)型安全時(shí)，編譯器將拋出警告。這對于針對 Tiger 的代碼有幫助，但它使得為 Java 1.4.x 或更早版本編寫(xiě)代碼非常麻煩。將不斷地收到關(guān)于根本無(wú)關(guān)的事情的警告。如何才能使編譯器不給您增添麻煩？
SupressWarnings 可以解決這個(gè)問(wèn)題。 SupressWarnings 與 Override 和 Deprecated 不同， 是具有變量的 — 所以您將單一注釋類(lèi)型與該變量一起使用?？梢砸灾禂到M來(lái)提供變量，其中每個(gè)值指明要阻止的一種特定警告類(lèi)型。請看清單 5 中的示例，這是 Tiger 中通常會(huì )產(chǎn)生錯誤的一些代碼。
|
圖 3 顯示了清單 5 中代碼的編譯結果。
清單 6 通過(guò)使用 SuppressWarnings 注釋消除了這種問(wèn)題。
|
非常簡(jiǎn)單，是吧？?jì)H需要找到警告類(lèi)型（圖 3 中顯示為“unchecked”），并將其傳送到 SuppressWarnings 中。
SuppressWarnings 中變量的值采用數組，使您可以在同一注釋中阻止多個(gè)警告。例如， @SuppressWarnings(value={"unchecked", "fallthrough"}) 使用兩個(gè)值的數組。此功能為處理錯誤提供了非常靈活的方法，無(wú)需進(jìn)行大量的工作。
|
雖然這里看到的語(yǔ)法可能都是新的，但您應該知道注釋非常容易理解和使用。也就是說(shuō)，與 Tiger 一起提供的標準注釋相當簡(jiǎn)單，可以添加許多功能。元數據正日益變得有幫助，您肯定會(huì )提出非常適用于自己的應用程序的注釋類(lèi)型。在本系列文章的第 2 部分，我將詳細說(shuō)明 Tiger 對編寫(xiě)自己的注釋類(lèi)型的支持。您將了解如何創(chuàng )建 Java 類(lèi)以及將其定義為注釋類(lèi)型，如何使編譯器識別您的注釋類(lèi)型，以及如何使用該類(lèi)型對代碼進(jìn)行注釋。我甚至會(huì )更深入地說(shuō)明奇異但有用的對注釋進(jìn)行注釋的任務(wù)。您將快速熟悉 Tiger 中的這一新構造。
|
聯(lián)系客服
