1. 程式人生 > >Java 9 揭祕(15. 增強的棄用註解)

Java 9 揭祕(15. 增強的棄用註解)

Tips
做一個終身學習的人。

Java 9

主要介紹以下內容:

  • 如何棄用API
  • @deprecate Javadoc標籤和@Deprecation註解在棄用的API中的角色
  • 用於生成棄用警告的詳細規則
  • 在JDK 9中更新@Deprecation註解
  • JDK 9中的新的棄用警告
  • 如何使用@SuppressWarnings註解來抑制JDK 9中的不同型別的棄用警告
  • 如何使用jdeprscan靜態分析工具來掃描編譯的程式碼庫,以查詢已棄用的JDK API的用法

一. 什麼是棄用

Java中的棄用是提供有關API生命週期的資訊的一種方式。 可以棄用模組,包,型別,建構函式,方法,欄位,引數和區域性變數。 當棄用API時,要告訴其使用者:

  • 不要使用API,因為它存在風險。
  • API已經遷移,因為存在API的更好的替代方案。
  • API已經遷移,因為API將在以後的版本中被刪除。

二. 如何棄用API

JDK有兩個用於棄用API的結構:

  • @deprecated Javadoc標籤
  • @Deprecated註解

@deprecated Javadoc標籤已新增到JDK 1.1中,它允許使用豐富的HTML文字格式功能指定關於棄用的詳細資訊。JDK 5.0中添加了java.lang.Deprecated註解型別,並且可以在已被棄用的API元素上使用。 在JDK 9之前,註解不包含任何元素。 它在執行時保留。

@deprecated標籤和@Deprecated

註解應該一起使用。 兩者都應該存在或兩者都不存在。 @Deprecation註解不允許指定棄用的描述,因此必須使用@deprecated標籤來提供描述。

Tips
在API元素上使用@deprecated標籤(而不是@Deprecated註解)會生成編譯器警告。 在JDK 9之前,需要使用-Xlint:dep-ann編譯器標誌來檢視這些警告。

下面包含FileCopier類的宣告。 假設這個類作為類庫遷移的一部分。 該類使用@Deprecation註解表示棄用。 它的Javadoc使用@deprecated標籤來提供不推薦使用的詳細資訊,例如不推薦使用的時間,它的替換和刪除通知。 在JDK 9之前,@Deprecated

註解型別不包含任何元素,因此必須使用Javadoc中已棄用的API的@deprecated標籤提供有關棄用的所有詳細資訊。 請注意,Javadoc中使用的@since標籤表示FileCopier類自該庫的版本1.2以來已經存在,而@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
 * <code>java.nio.file.Files</code> 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標籤的內容移動到生成的Javadoc中的頂部,以引起讀者的注意。 當不被棄用的程式碼使用不推薦使用的API時,編譯器會生成警告。 請注意,使用@Deprecated註解標註API不會生成警告;但是,使用已經使用@Deprecated註解標註的API。 如果在類本身之外使用FileCopier類,則會收到關於使用不推薦使用的類的編譯器警告。

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

假設編譯了程式碼並將其部署到生產環境中。如果升級了JDK版本或包含舊應用程式使用的新的已棄用的API的庫/框架,則不會收到任何警告,並且將錯過從不推薦使用的API遷移的機會。必須重新編譯程式碼以接收警告。沒有任何掃描和分析編譯程式碼(例如JAR檔案)的工具,並報告使用已棄用的API。更壞的情況是,從舊版本中刪除不推薦使用的API,而舊的編譯程式碼會收到意外的執行時錯誤。當他們檢視不贊成使用的元素Javadoc時,開發人員也感到困惑 —— 當API被廢棄時,無法表達何種方式,以及在將來的版本中是否會刪除已棄用的API。所有可以做的是在文字中將這些資訊指定為@deprecated標籤的一部分。 JDK 9嘗試通過增強@Deprecated註解來解決這些問題。註解在JDK 9中已增加兩個新元素:sinceforRemoval

在JDK 9之前,註解的宣告如下:

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

在JDK 9中,棄用註解的宣告更改為以下內容:

@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;
}

兩個新元素都具有指定的預設值,因此註解的現有使用不會有問題。 since元素指定已註解的API元素已被棄用的版本。 它是一個字串,將遵循與JDK版本方案相同的版本命名約定,例如“9”。 它預設為空字串。 請注意,JDK 9沒有向@Deprecated註解型別新增元素,以指定不推薦的描述。 這是由於兩個原因:

  • 註解在執行時保留。 向註解新增描述性文字將新增到執行時記憶體。
  • 描述性文字不能只是純文字。 例如,它需要提供一個連結來替代已棄用的API。 現有的@deprecated Javadoc標籤已經提供了這個功能。

forRemoval元素表示註解的API元素在將來的版本中被刪除,應該遷移API。 它預設為false。

Tips
元素上的@since Javadoc標籤表示何時添加了API元素,而@Deprecated註解的since元素表示API元素已被棄用。

在JDK 9之前,棄用警告是基於API元素及其使用場景(use-site)上使用@Deprecated註解的問題,如下所示。 當在沒有棄用的使用場景使用不推薦使用的API元素時,會發出警告。 如果宣告及其使用場景都已棄用,則不會發出任何警告。 可以通過使用@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元素增加了多於五個用例。 當forRemoval設定為false時,不推薦使用API,則將這種棄用稱為普通棄用,在這種情況下發出的警告稱為普通棄用警告。 當forRemoval設定為true時,不推薦使用API,則將這種棄用稱為終止棄用,並且在這種情況下發出的警告稱為終止棄用警告或刪除警告。

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

為了實現向後相容,如果程式碼在JDK 8中生成了棄用警告,它將繼續在JDK 9中生成普通的棄用警告。如果API已經被終止使用,其使用場景將生成刪除警告,而不考慮使用場景狀態。

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

四. 抑制棄用警告

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

  • 在JDK 8中,棄用的API和使用場景會抑制棄用警告。
  • 在JDK 9中,API的棄用從普通的棄用變為最終棄用。
  • 由於JDK 8中抑制了棄用警告,所以在JDK 9中使用場景的編譯沒有問題。
  • API被刪除,並且使用場景收到意外的執行時錯誤,而不會在之前接收到任何刪除警告。

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

五. 一個棄用API示例

在本節中,展示棄用API的所有用例,使用棄用使用的API,並通過一個簡單的示例來抑制警告。 在該示例中,對方法標示為棄用的,並使用它們來生成編譯時警告。 但是,不限於僅棄用方法。 對這些方法的註解可以更好地瞭解預期的行為。 下面包含一個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類中的幾種方法已經被普遍和最終棄用了。 m4X()的方法,其中X是數字,顯示如何抑制棄用警告。

// 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類,因此編譯會發出棄用警告。 請注意,以下命令在一行上輸入,而不是兩行。

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

輸出結果為:

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
···

六. 靜態分析棄用的API

棄用警告是編譯時警告。 如果部署的應用程式的編譯程式碼開始使用通常已棄用的API或生成執行時錯誤,一旦有效的API已被終止使用並被刪除,那麼將不會收到任何警告。 在JDK 9之前,必須重新編譯原始碼,以便在升級JDK或其他庫/框架時檢視廢棄用警告。 JDK 9通過提供一個jdeprscan的靜態分析工具來改善這種情況,該工具可用於掃描已編譯的程式碼,以檢視所使用的已棄用的API列表。 目前,該工具報告了僅JDK中棄用 API。 如果編譯的程式碼使用其他庫中不棄用的API,例如Spring或Hibernate或自己的庫,則此工具將不會報告這些。

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

jdeprscan [options] {dir|jar|class}

這裡,[options]是零個或多個選項的列表。 可以指定一個空格分隔目錄,JAR或完全限定類名的列表作為要掃描的引數。 可用選項如下:

-l, --list
--class-path <CLASSPATH>
--for-removal
--release <6|7|8|9>
-v, --verbose
--version
--full-version
-h, --help

--list選項列出了Java SE中的一些棄用的API。 當使用此選項時,不應指定編譯類的位置的引數。

--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選項列印有關jdeprscan工具的詳細幫助訊息。

下面包含JDeprScanTest類的程式碼。 程式碼很簡單。 它只是編譯,而不是執行。 執行它不會產生任何有趣的輸出。 它建立兩個執行緒。 一個執行緒使用Thread類的stop()方法停止,另一個執行緒使用Thread類的destroy()方法進行銷燬。 從JDK 1.2和JDK 1.5開始,stop()destroy()方法為普通棄用。 JDK 9已經最終棄用了destroy()方法,而繼續保持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的列表。它將列印一個長列表。 該命令需要幾秒鐘才能開始列印結果,因為它掃描整個JDK。

C:\Java9Revealed>jdeprscan --list

輸出的結果為:

@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

輸出的結果為:

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

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

七. 動態分析棄用的API

jdeprscan工具是一個靜態分析工具,因此它將跳過動態使用的棄用API。 例如,可以使用反射來呼叫已棄用的方法,這個工具在掃描過程中會錯過。 還可以在由ServiceLoader載入的提供程式中呼叫棄用的方法,這將被該工具遺漏。

在未來的版本中,JDK可能會提供一個名為jdeprdetect的動態分析工具,該工具將在執行時跟蹤棄用的API的使用。 該工具將有助於找到引用由靜態分析工具jdeprscan報告的棄用的API的死程式碼。

八 匯入時沒有棄用警告

直到JDK 9,如果使用import語句匯入了棄用類的建構函式,編譯器就會生成警告,即使在已棄用匯入的構造的所有使用站點上使用了@SuppressWarnings註解。 如果試圖擺脫程式碼中的所有棄用警告,這是一個煩惱。 你不能擺脫它們,因為你不能註解import語句。 可以通過省略對匯入棄用警告,JDK 9改進了這一點。

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

  • 在匯入語句中
  • 在變數宣告中
  • 在例項建立的表示式中
// 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

輸出結果為:

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將僅生成兩個棄用警告 —— 不包括匯入宣告的警告。

九. 總結

Java中的棄用是提供有關API生命週期的資訊的一種方式。 棄用API會告訴使用者遷移,因為API有使用的危險,更好的替換存在,否則將在以後的版本中被刪除。 使用棄用的API會生成編譯時棄用警告。

@deprecated Javadoc標籤和@Deprecated註解一起用於棄用API元素,如模組,包,型別,建構函式,方法,欄位,引數和區域性變數。 在JDK 9之前,註解不包含任何元素。 它在執行時保留。

JDK 9為註解添加了兩個元素:sinceforRemovalsince元素預設為空字串。 其值表示棄用的API元素的API版本。forRemoval元素的型別為boolean,預設為false。 其值為true表示API元素將在以後的版本中被刪除。

JDK 9編譯器根據@Deprecated註解的forRemoval元素的值生成兩種型別的棄用警告:forRemoval = false時為普通的棄用警告,forRemoval = true時為最終的刪除警告。

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

在JDK 9之前,使用import語句匯入棄用的構造會生成編譯時棄用警告。 JDK 9省略了這樣的警告。