3 非推奨の拡張
APIが今後削除されるかどうかを含めて、非推奨の意味のセマンティクスを明確にしています。
ライブラリの保守担当者である場合は、更新された非推奨構文を使用して、ライブラリで提供されるAPIのステータスをライブラリのユーザーに通知できます。
ライブラリまたはアプリケーションの開発者である場合は、jdeprscan
ツールを使用して、アプリケーションまたはライブラリで使用されている非推奨のJDK API要素を探すことができます。
JDKでの非推奨
非推奨は、ライブラリのコンシューマに非推奨APIからコードを移行する必要があることを示す通知です。
-
APIが危険である(Thread.stopメソッドなど)。
-
単純に名前が変更された(たとえば、AWT Component.show/hideがsetVisibleに置き換わった)。
-
より新しくよりよいAPIをかわりに使用できる。
-
APIが削除される予定である。
以前のリリースでは、非推奨になったAPIが削除されたことはほとんどありません。JDK 9では、削除対象のAPIが非推奨としてマークされます。これは、JDKプラットフォームの次期リリースでAPIが削除されることを示します。アプリケーションまたはライブラリでこれらのAPIを使用している場合は、すぐに移行することを計画する必要があります。
JDKの現在のリリースの非推奨APIのリストは、API仕様の非推奨APIのページを参照してください。
APIを非推奨とする方法
APIを非推奨にするには、@Deprecated注釈および@deprecated JavaDocタグという2つの異なるメカニズムを使用する必要があります。
APIをマークする@Deprecated注釈は、クラス・ファイルに記録され、ランタイムに使用されます。これにより、javac
およびjdeprscan
などの様々なツールで非推奨APIを検出し使用状況のフラグを付けられるようになります。@deprecated JavaDocタグは、非推奨になった理由を説明したり代替APIを提示するために、非推奨APIのドキュメントで使用されます。
大文字と小文字に注意してください。注釈は大文字のDで始まり、JavaDocタグは小文字のdで始まります。
@Deprecated注釈の使用
非推奨を示すには、モジュール、クラス、メソッドまたはメンバーの宣言の前に@Deprecatedを置きます。注釈にはこれらの要素が含まれます。
-
@Deprecated(since="
<version>
")-
<version>は、APIが非推奨になったバージョンを識別します。これは情報提供を目的としています。デフォルトは空の文字列(
"
"
)です。
-
-
@Deprecated(forRemoval=
<boolean>
)-
forRemoval=trueは、APIが今後のリリースで削除されることを示します。
-
forRemoval=falseは、今後はコードでこのAPIを使用しないことが推奨されますが、現時点でAPIが削除される予定はないことを示します。これはデフォルト値です。
-
たとえば: @Deprecated(since="9", forRemoval=true)
-
推奨されていません。
-
非推奨、削除予定: このAPI要素は将来のバージョンで削除予定です。
javadoc
ツールによって、非推奨APIのリストが含まれるdeprecated-list.html
という名前のページが生成され、そのページへのリンクがナビゲーション・バーに追加されます。
次に示すのは@Deprecated注釈の簡単な使用例で、java.lang.Threadクラスからの抜粋です。
public class Thread implements Runnable {
...
@Deprecated(since="1.2")
public final void stop() {
...
}
...
非推奨のセマンティクス
@Deprecated注釈の2つの要素を使用すると、開発者は、エクスポートされたAPI (アプリケーションや他のライブラリなど、そのライブラリの外部のコードにアクセスできるライブラリによって提供されるAPI)の非推奨の意味を明確にできます。
-
@Deprecated(forRemoval=true)は、APIがJDKプラットフォームの今後のリリースで削除されることを示します。
-
@Deprecated(since="
<version>
")には、JDK 9以降に非推奨になったAPI要素がいつ非推奨になったかを示すJDKバージョン文字列が含まれています。
ライブラリを保守し独自のAPIを作成している場合、@Deprecated注釈を使用していることが想定されます。APIの削除に関するポリシーについて決定および周知する必要があります。たとえば、6週間ごとに新しいライブラリをリリースする場合、APIを削除対象として非推奨にしても、数か月の間は削除せずに、顧客が移行するための時間を用意することができます。
@deprecated JavaDocタグの使用
非推奨プログラム要素のJavaDocコメントで@deprecatedタグを使用して、今後の使用は(引き続き動作するとしても)推奨されないことを示します。このタグは、すべてのクラス、メソッドまたはフィールド・ドキュメントのコメントで有効です。@deprecatedタグの後にはスペースまたは改行を置く必要があります。@deprecatedタグに続く段落では、非推奨になった理由を説明し、かわりに使用できるものを提示します。同じ機能を持つ新しいバージョンを示すテキストを@linkタグでマークします。
javadoc
ツールによって、@deprecatedタグに続くテキストが説明の前に移動され、その前に警告が置かれます。たとえば、次のソースによって、 /**
* ...
* @deprecated This method does not properly convert bytes into
* characters. As of JDK 1.1, the preferred way to do this is via the
* {@code String} constructors that take a {@link
* java.nio.charset.Charset}, charset name, or that use the platform's
* default charset.
* ...
*/
@Deprecated(since="1.1")
public String(byte ascii[], int hibyte) {
...
次の出力が生成されます。
@Deprecated(since="1.1")
public String(byte[] ascii,
int hibyte)
Deprecated. This method does not properly convert bytes into characters. As of
JDK 1.1, the preferred way to do this is via the String constructors that take a
Charset, charset name, or that use the platform's default charset.
対応する@Deprecated注釈を使用せずに@deprecated JavaDocタグを使用した場合は、警告が生成されます。
通知および警告
APIが非推奨になった場合は、開発者に通知する必要があります。非推奨APIによって、コードに問題が発生したり、これが後に削除された場合はランタイムにエラーが発生する可能性があります。
Javaコンパイラでは非推奨APIに関する警告が生成されます。警告に関する詳細な情報を生成するオプションがあり、また非推奨の警告を抑制することもできます。
コンパイラの非推奨警告
非推奨がforRemoval=false
である場合、Javaコンパイラでは「通常の非推奨警告」が生成されます。非推奨がforRemoval=true
である場合、コンパイラでは「削除警告」が生成されます。
2種類の警告は個別の-Xlint
フラグ(-Xlint:deprecation
および-Xlint:removal
)によって制御されます。デフォルトではjavac -Xlint:removal
オプションが有効であり、削除警告が表示されます。
また、警告は("–"を付けて)個別にオフにできます(-Xlint:-deprecation
および-Xlint:-removal
)。
通常の非推奨警告の例を次に示します。
$ javac src/example/DeprecationExample.java
Note: src/example/DeprecationExample.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
javac -Xlint:deprecation
オプションを使用して、どのAPIが非推奨になっているかを示します。
$ javac -Xlint:deprecation src/example/DeprecationExample.java
src/example/DeprecationExample.java:12: warning: [deprecation] getSelectedValues() in JList has been deprecated
Object[] values = jlist.getSelectedValues();
^
1 warning
削除警告の例を次に示します。
public class RemovalExample {
public static void main(String[] args) {
System.runFinalizersOnExit(true);
}
}
$ javac RemovalExample.java
RemovalExample.java:3: warning: [removal] runFinalizersOnExit(boolean) in System
has been deprecated and marked for removal
System.runFinalizersOnExit(true);
^
1 warning
==========
非推奨警告の抑制
javac -Xlint
オプションは、javac
の特定の実行でコンパイルされたすべてのファイルの警告を制御します。今後は表示しない警告を生成するソース・コードの特定の場所を識別しているとします。@SuppressWarnings
注釈を使用して、そのコードがコンパイルされるときはいつでも警告を抑制できます。非推奨APIを使用するクラス、メソッド、フィールドまたはローカル変数の宣言に@SuppressWarnings
注釈を配置します。
@SuppressWarnings
オプションを次に示します。
-
@SuppressWarnings("deprecation") — 通常の非推奨警告のみを抑制します。
-
@SuppressWarnings("removal") — 削除警告のみを抑制します。
-
@SuppressWarnings({"deprecation","removal"}) — 両方のタイプの警告を抑制します。
警告の抑制の例を次に示します。
@SuppressWarnings("deprecation")
Object[] values = jlist.getSelectedValues();
@SuppressWarnings
注釈を使用すると、コマンドラインで警告が有効化されている場合も、この行の警告は発行されません。
jdeprscanの実行
jdeprscan
は、アプリケーションでの非推奨JDK API要素の使用をレポートする静的分析ツールです。jdeprscan
を実行して、コンパイル済クラス・ファイルまたはjarファイルに発生する可能性がある問題を識別しやすくします。
コンパイラの通知から非推奨のJDK APIを見つけることができます。ただし、JDKのリリースごとに再コンパイルしない場合、警告が抑制されている場合、またはバイナリ・アーティファクトとして配布されるサードパーティのライブラリに依存している場合は、jdeprscan
を実行する必要があります。
非推奨APIがJDKから削除される前に、そのAPIへの依存性を発見することが重要です。現在のJDKリリースで、削除される非推奨APIをバイナリで使用しており、再コンパイルしない場合は、通知を受け取りません。今後のJDKリリースでAPIが削除されると、バイナリはランタイムに失敗します。jdeprscan
によって、APIが削除される前に、現時点でそれが使用されていることが検出されます。
ツールを実行するための完全な構文と出力の解析方法は、Java Development Kitツール仕様のjdeprscanコマンドに関する項を参照してください。