1. コア・ライブラリ
  2. 非推奨の拡張
  3. 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)

@Deprecated注釈を使用すると、プログラム要素が表示される場所にかかわらず、JavaDocによって生成されたドキュメントに次のいずれかのマークが付きます:

  • 非推奨になりました。

  • 非推奨、削除予定: この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)の非推奨の意味を明確にできます。

JDKプラットフォームの場合:

  • @Deprecated(forRemoval=true)は、APIがJDKプラットフォームの今後のリリースで削除されることを示します。

  • @Deprecated(since="<version>")には、JDK 9以降に非推奨になったAPI要素がいつ非推奨になったかを示すJDKバージョン文字列が含まれています。

ライブラリを保守し独自のAPIを作成している場合、@Deprecated注釈を使用していることが想定されます。APIの削除に関するポリシーについて決定および周知する必要があります。たとえば、6週間ごとに新しいライブラリをリリースする場合、APIを削除対象として非推奨にしても、数か月の間は削除せずに、顧客が移行するための時間を用意することができます。

@deprecated JavaDocタグの使用

非推奨プログラム要素のJavaDocコメントで@deprecatedタグを使用して、今後の使用は(引き続き動作するとしても)推奨されないことを示します。このタグは、すべてのクラス、メソッドまたはフィールド・ドキュメントのコメントで有効です。@deprecatedタグの後にはスペースまたは改行を置く必要があります。@deprecatedタグに続く段落では、非推奨になった理由を説明し、かわりに使用できるものを提示します。同じ機能を持つ新しいバージョンを示すテキストを@linkタグでマークします。

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