Java 9 揭秘（15. 增強的棄用注解）

發(fā)布時間：2017年07月26日作者： IT網(wǎng)絡(luò)文摘 (該文來自筆記，點擊查看原文)

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

如何棄用API
@deprecate Javadoc標(biāo)簽和@Deprecation注解在棄用的API中的角色
用于生成棄用警告的詳細(xì)規(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標(biāo)簽
@Deprecated注解

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

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

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

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

// FileCopier.javapackage 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
 * <code>java.nio.file.Files</code> class instead. This class
 * will be removed in a future release of this library.
 *
 * @since 1.2
 */@Deprecatedpublic 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標(biāo)簽的內(nèi)容移動到生成的Javadoc中的頂部，以引起讀者的注意。當(dāng)不被棄用的代碼使用不推薦使用的API時，編譯器會生成警告。請注意，使用@Deprecated注解標(biāo)注API不會生成警告；但是，使用已經(jīng)使用@Deprecated注解標(biāo)注的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被廢棄時，無法表達(dá)何種方式，以及在將來的版本中是否會刪除已棄用的API。所有可以做的是在文本中將這些信息指定為@deprecated標(biāo)簽的一部分。 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;
}

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

注解在運行時保留。向注解添加描述性文本將添加到運行時內(nèi)存。
描述性文字不能只是純文本。例如，它需要提供一個鏈接來替代已棄用的API。現(xiàn)有的@deprecated Javadoc標(biāo)簽已經(jīng)提供了這個功能。

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

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

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

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及其使用場景在兩個不同的代碼庫中并獨立維護(hù)的情況。如果使用場景代碼庫存活超過了API代碼庫，則用場景將會收到意外的運行時錯誤，因為它使用的API不再存在。用場景發(fā)出警告將提供一個機會，以防在用場景的代碼去掉之前，來計劃替代最終棄用的API。

四. 抑制棄用警告

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

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

// Box.javapackage 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.javapackage 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編譯器標(biāo)志來編譯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: war

http://www.cnblogs.com/IcanFixIt/p/7234054.html

分類導(dǎo)航

Java 9 揭秘（15. 增強的棄用注解）

一. 什么是棄用

二. 如何棄用API

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

四. 抑制棄用警告

五. 一個棄用API示例

延伸閱讀

我想了解如何學(xué)習(xí)

分類導(dǎo)航

Java 9 揭秘（15. 增強的棄用注解）

一. 什么是棄用

二. 如何棄用API

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

四. 抑制棄用警告

五. 一個棄用API示例

延伸閱讀

我想了解如何學(xué)習(xí)

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