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タグを使用した場合は、警告が生成されます。