プライマリ・コンテンツに移動
Java Platform, Standard Editionコア・ライブラリ
リリース9
E90922-01
目次へ移動
目次

前
次

1 非推奨の拡張

JDK 9では、APIが今後削除されるかどうかを含めて、非推奨の意味のセマンティクスを明確にしています。

ライブラリの保守担当者である場合は、更新された非推奨構文を使用して、ライブラリで提供されるAPIのステータスをライブラリのユーザーに通知できます。

ライブラリまたはアプリケーションの開発者である場合は、jdeprscanツールを使用して、アプリケーションまたはライブラリで使用されている非推奨のJDK API要素を探すことができます。

JDKでの非推奨

非推奨は、ライブラリのコンシューマに非推奨APIからコードを移行する必要があることを示す通知です。

JDKでは、次を含む様々な理由でAPIが非推奨になりました。
  • APIが危険である(Thread.stopメソッドなど)。

  • 単純に名前が変更された(例: AWT Component.show/hidesetVisibleに置き換わった)。

  • より新しくよりよいAPIをかわりに使用できる。

  • 非推奨のAPIが削除される予定である。

以前のリリースでは、非推奨になったAPIが実際に削除されたことはありません。JDK 9では、削除対象のAPIが非推奨としてマークされます。これは、JDKプラットフォームの次期リリースでAPIが削除されることを示します。アプリケーションまたはライブラリでこれらのAPIを使用している場合は、すぐに移行することを計画する必要があります。

JDK 9リリースの非推奨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)

@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の非推奨の意味を明確に示すことができます。

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

通知および警告

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 Platform, Standard Editionツール・リファレンスjdeprscanに関する項を参照してください。