Tips

做一個終身學(xué)習(xí)的人。

主要介紹以下內(nèi)容：

如何棄用API

@deprecate Javadoc標簽和@Deprecation注解在棄用的API中的角色

用于生成棄用警告的詳細規(guī)則

在JDK 9中更新@Deprecation注解

JDK 9中的新的棄用警告

如何使用@SuppressWarnings注解來抑制JDK 9中的不同類型的棄用警告

如何使用jdeprscan靜態(tài)分析工具來掃描編譯的代碼庫，以查找已棄用的JDK API的用法

一. 什么是棄用

Java中的棄用是提供有關(guān)API生命周期的信息的一種方式。 可以棄用模塊，包，類型，構(gòu)造函數(shù)，方法，字段，參數(shù)和局部變量。 當(dāng)棄用API時，要告訴其用戶：

不要使用API，因為它存在風(fēng)險。

API已經(jīng)遷移，因為存在API的更好的替代方案。

API已經(jīng)遷移，因為API將在以后的版本中被刪除。

二. 如何棄用API

JDK有兩個用于棄用API的結(jié)構(gòu)：

@deprecated Javadoc標簽

@Deprecated注解

@deprecated Javadoc標簽已添加到JDK 1.1中，它允許使用豐富的HTML文本格式功能指定關(guān)于棄用的詳細信息。JDK 5.0中添加了java.lang.Deprecated注解類型，并且可以在已被棄用的API元素上使用。 在JDK 9之前，注解不包含任何元素。 它在運行時保留。

@deprecated標簽和@Deprecated注解應(yīng)該一起使用。 兩者都應(yīng)該存在或兩者都不存在。 @Deprecation注解不允許指定棄用的描述，因此必須使用@deprecated標簽來提供描述。

Tips

在API元素上使用@deprecated標簽(而不是@Deprecated注解)會生成編譯器警告。 在JDK 9之前，需要使用-Xlint：dep-ann編譯器標志來查看這些警告。

下面包含F(xiàn)ileCopier類的聲明。 假設(shè)這個類作為類庫遷移的一部分。 該類使用@Deprecation注解表示棄用。 它的Javadoc使用@deprecated標簽來提供不推薦使用的詳細信息，例如不推薦使用的時間，它的替換和刪除通知。 在JDK 9之前，@Deprecated注解類型不包含任何元素，因此必須使用Javadoc中已棄用的API的@deprecated標簽提供有關(guān)棄用的所有詳細信息。 請注意，Javadoc中使用的@since標簽表示FileCopier類自該庫的版本1.2以來已經(jīng)存在，而@deprecated標簽表示該類自版本1.4以來已被棄用。

// FileCopier.java

package com.jdojo.deprecation;

import java.io.File;

/**

* The class consists of static methods that can be used to

* copy files and directories.

*

* @deprecated Deprecated since 1.4. Not safe to use. Use the

* java.nio.file.Files class instead. This class

* will be removed in a future release of this library.

*

* @since 1.2

*/

@Deprecated

public class FileCopier {

// No direct instantiation supported.

private FileCopier() {

}

/**

* Copies the contents of src to dst.

* @param src The source file

* @param dst The destination file

* @return true if the copy is successfully,

* false otherwise.

*/

public static boolean copy(File src, File dst) {

// More code goes here

return true;

}

// More methods go here

}

Javadoc工具將@deprecated標簽的內(nèi)容移動到生成的Javadoc中的頂部，以引起讀者的注意。 當(dāng)不被棄用的代碼使用不推薦使用的API時，編譯器會生成警告。 請注意，使用@Deprecated注解標注API不會生成警告；但是，使用已經(jīng)使用@Deprecated注解標注的API。 如果在類本身之外使用FileCopier類，則會收到關(guān)于使用不推薦使用的類的編譯器警告。

三. JDK 9中@Deprecated注解的更新

假設(shè)編譯了代碼并將其部署到生產(chǎn)環(huán)境中。如果升級了JDK版本或包含舊應(yīng)用程序使用的新的已棄用的API的庫/框架，則不會收到任何警告，并且將錯過從不推薦使用的API遷移的機會。必須重新編譯代碼以接收警告。沒有任何掃描和分析編譯代碼(例如JAR文件)的工具，并報告使用已棄用的API。更壞的情況是，從舊版本中刪除不推薦使用的API，而舊的編譯代碼會收到意外的運行時錯誤。當(dāng)他們查看不贊成使用的元素Javadoc時，開發(fā)人員也感到困惑 —— 當(dāng)API被廢棄時，無法表達何種方式，以及在將來的版本中是否會刪除已棄用的API。所有可以做的是在文本中將這些信息指定為@deprecated標簽的一部分。 JDK 9嘗試通過增強@Deprecated注解來解決這些問題。注解在JDK 9中已增加兩個新元素：since和forRemoval。

在JDK 9之前，注解的聲明如下：

@Documented

@Retention(RetentionPolicy.RUNTIME)

@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})

public @interface Deprecated {

}

在JDK 9中，棄用注解的聲明更改為以下內(nèi)容：

@Documented

@Retention(RetentionPolicy.RUNTIME)

@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, MODULE, PARAMETER, TYPE})

public @interface Deprecated {

String since() default "";

boolean forRemoval() default false;

}

兩個新元素都具有指定的默認值，因此注解的現(xiàn)有使用不會有問題。 since元素指定已注解的API元素已被棄用的版本。 它是一個字符串，將遵循與JDK版本方案相同的版本命名約定，例如“9”。 它默認為空字符串。 請注意，JDK 9沒有向@Deprecated注解類型添加元素，以指定不推薦的描述。 這是由于兩個原因：

注解在運行時保留。 向注解添加描述性文本將添加到運行時內(nèi)存。

描述性文字不能只是純文本。 例如，它需要提供一個鏈接來替代已棄用的API。 現(xiàn)有的@deprecated Javadoc標簽已經(jīng)提供了這個功能。

forRemoval元素表示注解的API元素在將來的版本中被刪除，應(yīng)該遷移API。 它默認為false。

Tips

元素上的@since Javadoc標簽表示何時添加了API元素，而@Deprecated注解的since元素表示API元素已被棄用。

在JDK 9之前，棄用警告是基于API元素及其使用場景(use-site)上使用@Deprecated注解的問題，如下所示。 當(dāng)在沒有棄用的使用場景使用不推薦使用的API元素時，會發(fā)出警告。 如果聲明及其使用場景都已棄用，則不會發(fā)出任何警告。 可以通過使用@SuppressWarnings("deprecation")注解標示用戶場景來抑制棄用警告。

API Use-Site

API Declaration Site

API Declaration Site

Empty

Not Deprecated

Deprecated

Not Deprecated

N

W

Deprecate

N

N

N = No warning,

W = Warning

在@Deprecation注解類型中添加forRemoval元素增加了多于五個用例。 當(dāng)forRemoval設(shè)置為false時，不推薦使用API，則將這種棄用稱為普通棄用，在這種情況下發(fā)出的警告稱為普通棄用警告。 當(dāng)forRemoval設(shè)置為true時，不推薦使用API，則將這種棄用稱為終止棄用，并且在這種情況下發(fā)出的警告稱為終止棄用警告或刪除警告。

API Use-Site

API Declaration Site

API Declaration Site

API Declaration Site

Empty

Not Deprecated

Ordinarily Deprecated

TerminallyDeprecated

Not Deprecated

N

OW

RW

Ordinarily Deprecated

N

N

RW

Terminally Deprecated

N

N

RW

N = No warning,

OW = Ordinary deprecation warning,

RW = Removal deprecation warning

為了實現(xiàn)向后兼容，如果代碼在JDK 8中生成了棄用警告，它將繼續(xù)在JDK 9中生成普通的棄用警告。如果API已經(jīng)被終止使用，其使用場景將生成刪除警告，而不考慮使用場景狀態(tài)。

在JDK 9中，在一個情況下發(fā)出的警告，其API和其使用場景都被最終棄用，這些警告需要一點解釋。 API和使用它的代碼都已被棄用，并且將來都會被刪除，所以在這種情況下要發(fā)出警告是什么意思？ 這樣做是為了涵蓋最終棄用的API及其使用場景在兩個不同的代碼庫中并獨立維護的情況。 如果使用場景代碼庫存活超過了API代碼庫，則用場景將會收到意外的運行時錯誤，因為它使用的API不再存在。用場景發(fā)出警告將提供一個機會，以防在用場景的代碼去掉之前，來計劃替代最終棄用的API。

四. 抑制棄用警告

介紹JDK 9中的removal警告已添加了一個新的用例來抑制棄用警告。 在JDK 9之前，可以通過使用@SuppressWarnings("deprecation")注解標示使用場景來抑制所有棄用警告。 考慮以下幾種情況：

在JDK 8中，棄用的API和使用場景會抑制棄用警告。

在JDK 9中，API的棄用從普通的棄用變?yōu)樽罱K棄用。

由于JDK 8中抑制了棄用警告，所以在JDK 9中使用場景的編譯沒有問題。

API被刪除，并且使用場景收到意外的運行時錯誤，而不會在之前接收到任何刪除警告。

為了涵蓋這種情況，當(dāng)使用@SuppressWarnings("deprecation")，JDK 9不會抑制刪除警告。 它只抑制普通的棄用警告。 要抑制刪除警告，需要使用@SuppressWarnings("removal")。 如果要抑制普通和刪除的棄用警告，則需要使用@SuppressWarnings({“deprecation”, "removal"})。

五. 一個棄用API示例

在本節(jié)中，展示棄用API的所有用例，使用棄用使用的API，并通過一個簡單的示例來抑制警告。 在該示例中，對方法標示為棄用的，并使用它們來生成編譯時警告。 但是，不限于僅棄用方法。 對這些方法的注解可以更好地了解預(yù)期的行為。 下面包含一個Box類的代碼。 該類包含三種方法 —— 沒有棄用的方法，普通的棄用方法和最終棄用的方法。 編譯Box類不會生成任何廢棄警告，因為該類不使用任何已棄用的API，而是包含過時的API。

// Box.java

package com.jdojo.deprecation;

/**

* This class is used to demonstrate how to deprecate APIs.

*/

public class Box {

/**

* Not deprecated

*/

public static void notDeprecated() {

System.out.println("notDeprecated...");

}

/**

* Deprecated ordinarily.

* @deprecated Do not use it.

*/

@Deprecated(since="2")

public static void deprecatedOrdinarily() {

System.out.println("deprecatedOrdinarily...");

}

/**

* Deprecated terminally.

* @deprecated It will be removed in a future release.

* Migrate your code.

*/

@Deprecated(since="2", forRemoval=true)

public static void deprecatedTerminally() {

System.out.println("deprecatedTerminally...");

}

}

下面包含BoxTest類的代碼。 該類使用Box類的所有方法。 BoxTest類中的幾種方法已經(jīng)被普遍和最終棄用了。 m4X()的方法，其中X是數(shù)字，顯示如何抑制棄用警告。

// BoxTest.java

package com.jdojo.deprecation;

public class BoxTest {

/**

* API: Not deprecated

* Use-site: Not deprecated

* Deprecation warning: No warning

*/

public static void m11() {

Box.notDeprecated();

}

/**

* API: Ordinarily deprecated

* Use-site: Not deprecated

* Deprecation warning: No warning

*/

public static void m12() {

Box.deprecatedOrdinarily();

}

/**

* API: Terminally deprecated

* Use-site: Not deprecated

* Deprecation warning: Removal warning

*/

public static void m13() {

Box.deprecatedTerminally();

}

/**

* API: Not deprecated

* Use-site: Ordinarily deprecated

* Deprecation warning: No warning

* @deprecated Dangerous to use.

*/

@Deprecated(since="1.1")

public static void m21() {

Box.notDeprecated();

}

/**

* API: Ordinarily deprecated

* Use-site: Ordinarily deprecated

* Deprecation warning: No warning

* @deprecated Dangerous to use.

*/

@Deprecated(since="1.1")

public static void m22() {

Box.deprecatedOrdinarily();

}

/**

* API: Terminally deprecated

* Use-site: Ordinarily deprecated

* Deprecation warning: Removal warning

* @deprecated Dangerous to use.

*/

@Deprecated(since="1.1")

public static void m23() {

Box.deprecatedTerminally();

}

/**

* API: Not deprecated

* Use-site: Terminally deprecated

* Deprecation warning: No warning

* @deprecated Going away.

*/

@Deprecated(since="1.1", forRemoval=true)

public static void m31() {

Box.notDeprecated();

}

/**

* API: Ordinarily deprecated

* Use-site: Terminally deprecated

* Deprecation warning: No warning

* @deprecated Going away.

*/

@Deprecated(since="1.1", forRemoval=true)

public static void m32() {

Box.deprecatedOrdinarily();

}

/**

* API: Terminally deprecated

* Use-site: Terminally deprecated

* Deprecation warning: Removal warning

* @deprecated Going away.

*/

@Deprecated(since="1.1", forRemoval=true)

public static void m33() {

Box.deprecatedTerminally();

}

/**

* API: Ordinarily and Terminally deprecated

* Use-site: Not deprecated

* Deprecation warning: Ordinary and removal warnings

*/

public static void m41() {

Box.deprecatedOrdinarily();

Box.deprecatedTerminally();

}

/**

* API: Ordinarily and Terminally deprecated

* Use-site: Not deprecated

* Deprecation warning: Ordinary warnings

*/

@SuppressWarnings("deprecation")

public static void m42() {

Box.deprecatedOrdinarily();

Box.deprecatedTerminally();

}

/**

* API: Ordinarily and Terminally deprecated

* Use-site: Not deprecated

* Deprecation warning: Removal warnings

*/

@SuppressWarnings("removal")

public static void m43() {

Box.deprecatedOrdinarily();

Box.deprecatedTerminally();

}

/**

* API: Ordinarily and Terminally deprecated

* Use-site: Not deprecated

* Deprecation warning: Removal warnings

*/

@SuppressWarnings({"deprecation", "removal"})

public static void m44() {

Box.deprecatedOrdinarily();

Box.deprecatedTerminally();

}

}

需要使用-Xlint：deprecation編譯器標志來編譯BoxTest類，因此編譯會發(fā)出棄用警告。 請注意，以下命令在一行上輸入，而不是兩行。

C:\Java9Revealed\com.jdojo.deprecation\src>javac

-Xlint:deprecation

-d ..\build\classes com\jdojo\deprecation\BoxTest.java

輸出結(jié)果為：

com\jdojo\deprecation\BoxTest.java:20: warning: [deprecation] deprecatedOrdinarily() in Box has been deprecated

Box.deprecatedOrdinarily();

^

com\jdojo\deprecation\BoxTest.java:29: warning: [removal] deprecatedTerminally() in Box has been deprecated and marked for removal

Box.deprecatedTerminally();

^

com\jdojo\deprecation\BoxTest.java:62: warning: [removal] deprecatedTerminally() in Box has been deprecated and marked for removal

Box.deprecatedTerminally();

^

com\jdojo\deprecation\BoxTest.java:95: warning: [removal] deprecatedTerminally() in Box has been deprecated and marked for removal

Box.deprecatedTerminally();

^

com\jdojo\deprecation\BoxTest.java:105: warning: [deprecation] deprecatedOrdinarily() in Box has been deprecated

Box.deprecatedOrdinarily();

^

com\jdojo\deprecation\BoxTest.java:106: warning: [removal] deprecatedTerminally() in Box has been deprecated and marked for removal

Box.deprecatedTerminally();

^

com\jdojo\deprecation\BoxTest.java:117: warning: [removal] deprecatedTerminally() in Box has been deprecated and marked for removal

Box.deprecatedTerminally();

^

com\jdojo\deprecation\BoxTest.java:127: warning: [deprecation] deprecatedOrdinarily() in Box has been deprecated

Box.deprecatedOrdinarily();

^

8 warnings

···

六. 靜態(tài)分析棄用的API

棄用警告是編譯時警告。 如果部署的應(yīng)用程序的編譯代碼開始使用通常已棄用的API或生成運行時錯誤，一旦有效的API已被終止使用并被刪除，那么將不會收到任何警告。 在JDK 9之前，必須重新編譯源代碼，以便在升級JDK或其他庫/框架時查看廢棄用警告。 JDK 9通過提供一個jdeprscan的靜態(tài)分析工具來改善這種情況，該工具可用于掃描已編譯的代碼，以查看所使用的已棄用的API列表。 目前，該工具報告了僅JDK中棄用 API。 如果編譯的代碼使用其他庫中不棄用的API，例如Spring或Hibernate或自己的庫，則此工具將不會報告這些。

jdeprscan工具位于JDK_HOME\bin目錄中。 使用該工具的一般語法如下：

jdeprscan [options] {dir|jar|class}

這里，[options]是零個或多個選項的列表。 可以指定一個空格分隔目錄，JAR或完全限定類名的列表作為要掃描的參數(shù)。 可用選項如下：

-l, --list

--class-path

--for-removal

--release <6|7|8|9>

-v, --verbose

--version

--full-version

-h, --help

--list選項列出了Java SE中的一些棄用的API。 當(dāng)使用此選項時，不應(yīng)指定編譯類的位置的參數(shù)。

--class-path指定在掃描期間用于查找依賴類的類路徑。

--for-removal選項將掃描或列表限制為只被棄用去除的那些API。 它只能在版本值為9或更高版本中使用，因為@Deprecated注解類型在JDK 9之前不包含forRemoval元素。

--release選項指定Java SE版本，在掃描期間提供一組棄用的API。 例如，要在JDK 6中列出所有已棄用的API，工具將如下所示：

jdeprscan --list --release 6

--verbose選項在掃描過程中打印其他消息。

--version和--full-version選項分別打印jdeprscan工具的縮寫和完整版本。

--help選項打印有關(guān)jdeprscan工具的詳細幫助消息。

下面包含JDeprScanTest類的代碼。 代碼很簡單。 它只是編譯，而不是運行。 運行它不會產(chǎn)生任何有趣的輸出。 它創(chuàng)建兩個線程。 一個線程使用Thread類的stop()方法停止，另一個線程使用Thread類的destroy()方法進行銷毀。 從JDK 1.2和JDK 1.5開始，stop()和destroy()方法為普通棄用。 JDK 9已經(jīng)最終棄用了destroy()方法，而繼續(xù)保持stop()方法作為普通棄用。 在下面的例子中使用這個類。

// JDeprScanTest.java

package com.jdojo.deprecation;

public class JDeprScanTest {

public static void main(String[] args) {

Thread t = new Thread(() -> System.out.println("Test"));

t.start();

t.stop();

Thread t2 = new Thread(() -> System.out.println("Test"));

t2.start();

t2.destroy();

}

}

以下命令打印JDK 9中所有已棄用的API的列表。它將打印一個長列表。 該命令需要幾秒鐘才能開始打印結(jié)果，因為它掃描整個JDK。

C:\Java9Revealed>jdeprscan --list

輸出的結(jié)果為：

@Deprecated java.lang.ClassLoader

javax.tools.ToolProvider.getSystemToolClassLoader()

...

The following command prints all terminally deprecated APIs in JDK 9. That is, it prints all deprecated APIs that have been marked for removal in a future release:

C:\Java9Revealed>jdeprscan --list --for-removal

...

@Deprecated(since="9", forRemoval=true) class java.lang.Compiler

...

The following command prints the list of all APIs deprecated in JDK 8:

C:\Java9Revealed>jdeprscan --list --release 8

@Deprecated class javax.swing.text.TableView.TableCell

...

以下命令打印java.lang.Thread類使用的已棄用API的列表。

C:\Java9Revealed>jdeprscan java.lang.Thread

輸出的結(jié)果為：

class java/lang/Thread uses deprecated method java/lang/Thread::resume()V

請注意，之前的命令不會打印Thread類中已棄用的API列表。 相反，它打印使用棄用的API的Thread類中的API列表。

七. 動態(tài)分析棄用的API

jdeprscan工具是一個靜態(tài)分析工具，因此它將跳過動態(tài)使用的棄用API。 例如，可以使用反射來調(diào)用已棄用的方法，這個工具在掃描過程中會錯過。 還可以在由ServiceLoader加載的提供程序中調(diào)用棄用的方法，這將被該工具遺漏。

在未來的版本中，JDK可能會提供一個名為jdeprdetect的動態(tài)分析工具，該工具將在運行時跟蹤棄用的API的使用。 該工具將有助于找到引用由靜態(tài)分析工具jdeprscan報告的棄用的API的死代碼。

八 導(dǎo)入時沒有棄用警告

直到JDK 9，如果使用import語句導(dǎo)入了棄用類的構(gòu)造函數(shù)，編譯器就會生成警告，即使在已棄用導(dǎo)入的構(gòu)造的所有使用站點上使用了@SuppressWarnings注解。 如果試圖擺脫代碼中的所有棄用警告，這是一個煩惱。 你不能擺脫它們，因為你不能注解import語句。 可以通過省略對導(dǎo)入棄用警告，JDK 9改進了這一點。

考慮下面ImportDeprecationWarning類，它在三個地方使用了棄用的StringBufferInputStream類：

在導(dǎo)入語句中

在變量聲明中

在實例創(chuàng)建的表達式中

// ImportDeprecationWarning.java

package com.jdojo.deprecation;

import java.io.StringBufferInputStream;

public class ImportDeprecationWarning {

@SuppressWarnings("deprecation")

public static void main(String[] args) {

StringBufferInputStream sbis =

new StringBufferInputStream("Hello");

for(int c = sbis.read(); c != -1; c = sbis.read()) {

System.out.println((char)c);

}

}

}

請注意，ImportDeprecationWarning類在main()方法上使用@SuppressWarnings注解來抑制棄用警告。 使用Xlint:deprecation`標志在JDK 8中編譯此類將生成以下警告。 在JDK 9中編譯此類不會生成任何棄用警告。

C:\Java9Revealed\com.jdojo.deprecation\src>javac -Xlint:deprecation -d ..\build\classes com\jdojo\deprecation\ImportDeprecationWarning.java

輸出結(jié)果為：

com\jdojo\deprecation\ImportDeprecationWarning.java:4: warning: [deprecation] StringBufferInputStream in java.io has been deprecated

import java.io.StringBufferInputStream;

^

1 warning

在JDK 8中編譯此類，在刪除main()方法上的@SuppressWarnings注解后，編譯器將生成三個棄用的警告 —— 一個用于每次使用棄用的StringBufferInputStream類，而JDK 9將僅生成兩個棄用警告 —— 不包括導(dǎo)入聲明的警告。

九. 總結(jié)

Java中的棄用是提供有關(guān)API生命周期的信息的一種方式。 棄用API會告訴用戶遷移，因為API有使用的危險，更好的替換存在，否則將在以后的版本中被刪除。 使用棄用的API會生成編譯時棄用警告。

@deprecated Javadoc標簽和@Deprecated注解一起用于棄用API元素，如模塊，包，類型，構(gòu)造函數(shù)，方法，字段，參數(shù)和局部變量。 在JDK 9之前，注解不包含任何元素。 它在運行時保留。

JDK 9為注解添加了兩個元素：since和forRemoval。 since元素默認為空字符串。 其值表示棄用的API元素的API版本。forRemoval元素的類型為boolean，默認為false。 其值為true表示API元素將在以后的版本中被刪除。

JDK 9編譯器根據(jù)@Deprecated注解的forRemoval元素的值生成兩種類型的棄用警告：forRemoval = false時為普通的棄用警告，forRemoval = true時為最終的刪除警告。

在JDK 9之前，可以通過使用@SuppressWarnings("deprecation")注解標示已棄用的API的使用場景來抑制棄用警告。 在JDK 9中，需要使用@SuppressWarnings("deprecation")來抑制普通警告，@SuppressWarnings("removal")來抑制刪除警告，而@SuppressWarnings({"deprecation", "removal"}可以抑制兩種類型的警告。

在JDK 9之前，使用import語句導(dǎo)入棄用的構(gòu)造會生成編譯時棄用警告。 JDK 9省略了這樣的警告。

總結(jié)

以上是生活随笔為你收集整理的java弃用标签_Java 9 揭秘（15. 增强的弃用注解）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。