このドキュメントの目的は、Hadoopソースベースに対してアプリケーションを構築する際に期待できることを、ダウンストリーム開発者に明確に示すことです。このドキュメントは主にHadoop互換性ガイドラインを精選したものであり、そのため、さまざまなHadoopインターフェースのリリース間の互換性の保証に焦点を当てています。
このドキュメントの対象読者は、ソースコード自体、ビルドアートファクト、または実行中のシステムとの対話に関わらず、Apache Hadoopを構築または依存するプロジェクトまたはアプリケーションに取り組んでいるすべての開発者です。
Hadoop開発コミュニティは、新しい機能の導入と既存の問題の修正のために、定期的に新しいHadoopリリースを作成します。リリースは3つのカテゴリに分類されます。
Apache Hadoopに属するメソッドを呼び出したり、クラスを使用したりするソフトウェアを作成する際には、開発者は次のガイドラインに従う必要があります。ガイドラインに従わないと、Hadoopのリリース間での移行に問題が発生する可能性があります。
パッケージ、クラス、メソッドには、対象者アノテーションが付加されている場合があります。3つのプライバシーレベルがあります。 公開、限定非公開、および非公開。ダウンストリーム開発者は、公開としてマークされているパッケージ、クラス、メソッド、およびフィールドのみを使用する必要があります。公開としてマークされていないパッケージ、クラス、およびメソッドは、Hadoopの内部と見なされ、Hadoopの他のコンポーネントによる消費のみに意図されています。
要素に、その包含要素のアノテーションと競合するアノテーションがある場合、最も制限の強いアノテーションが優先されます。たとえば、非公開メソッドが公開クラスに含まれている場合、そのメソッドは非公開として扱う必要があります。公開メソッドが非公開クラスに含まれている場合、そのメソッドは非公開として扱う必要があります。
メソッドにプライバシーアノテーションがない場合、そのクラスからプライバシーを継承します。クラスにプライバシーがない場合、そのパッケージからプライバシーを継承します。パッケージにプライバシーがない場合、非公開であると見なす必要があります。
パッケージ、クラス、メソッドには、安定性アノテーションが付加されている場合があります。安定性には3つのクラスがあります。安定、発展中、および不安定。安定性アノテーションは、非互換な変更がいつ行われてもよいかを決定します。安定とは、メジャーリリース間で非互換な変更が許可されないことを意味します。発展中とは、マイナーリリース間で非互換な変更が許可されないことを意味します。不安定とは、いつでも非互換な変更が許可されることを意味します。ダウンストリーム開発者としては、不安定なAPIを避け、可能な限り安定したAPIを優先することが最善です。
メソッドに安定性アノテーションがない場合、そのクラスから安定性を継承します。クラスに安定性がない場合、そのパッケージから安定性を継承します。パッケージに安定性がない場合、不安定であると見なす必要があります。
APIの安定性に関する上記の規則に従って、新しいリリースでは、次のようにAPIを変更できます。
| リリースの種類 | 安定したAPIの変更 | 発展中のAPIの変更 | 不安定なAPIの変更 |
|---|---|---|---|
| メジャー | 許可 | 許可 | 許可 |
| マイナー | 許可しない | 許可 | 許可 |
| メンテナンス | 許可しない | 許可しない | 許可 |
メジャーリリースは、Hadoop開発コミュニティがメジャーリリース間でも可能な限り互換性を維持しようと努めている場合でも、許可されている場合、いかなるAPIの互換性も壊すことができます。また、不安定なAPIは、予告なしにいつでも変更される可能性があることにも注意してください。
@Deprecatedとしてアノテーションされているクラスまたはメソッドは、もはや安全に使用できません。非推奨の要素は引き続き機能しますが、後続のリリースで削除される可能性があり、おそらく削除されます。安定性アノテーションは、非推奨の要素が削除できる最も早いリリースを決定します。安定な要素は、次のメジャーリリースまで削除できません。発展中の要素は、次のマイナーリリースまで削除できません。不安定な要素はいつでも削除される可能性があり、通常は削除される前に非推奨としてマークされません。安定および発展中の要素は、削除される前に、完全なメジャーリリースまたはマイナーリリース（それぞれ）の間、非推奨としてマークする必要があります。たとえば、安定な要素がHadoop 3.1で非推奨としてマークされている場合、Hadoop 5.0まで削除できません。
Apache Hadoop開発コミュニティは、正しさのために変更が行われる場合でも、リリース間でAPIの動作が常に一貫していることを保証するために努力しています。API JavaDocは、APIの期待される動作の主要な権威と見なされます。JavaDocが不十分または不足している場合、単体テストは期待される動作のフォールバック権威と見なされます。単体テストが存在しない場合、意図された動作は名前から推測する必要があります。可能な限り、ダウンストリーム開発者は、API自体のソースコードを見て期待される動作を判断することを避けるべきです。これは、Hadoop開発コミュニティによって期待される動作として明示的に保持されていない実装の詳細への依存関係を作成する可能性があるためです。
JavaDocで期待される動作を推測するのに不十分な場合、ダウンストリーム開発者は、JavaDocを追加または改善するようにHadoop JIRAを提出することを強くお勧めします。
正しさのために行われた修正により、APIの期待される動作が変更される可能性があることに注意してください。ただし、このような変更には、新しい動作を明確にするドキュメントが添付されていることが期待されます。
Apache Hadoop開発コミュニティは、リリース間でエンドユーザーアプリケーションのバイナリ互換性を維持しようと努めています。アプリケーションがPrivate、Limited-Private、またはUnstable APIを使用していない限り、新しいHadoopリリースにアップグレードしても、理想的にはアプリケーションの更新は必要ありません。特にMapReduceアプリケーションは、リリース間でバイナリ互換性が保証されています。
Hadoop互換性仕様には、Hadoop開発コミュニティが遵守すべき標準が記載されていますが、様々な理由により、ソースコードが互換性仕様の理想に沿っていない場合があります。
ダウンストリーム開発者が遭遇する一般的な問題を2つ挙げます。
これらの場合、ダウンストリーム開発者は、適切な開発者メーリングリストへのメール送信、またはJIRAへの登録、あるいはその両方によって、Hadoop開発コミュニティに問題を提起することを強く推奨します。開発コミュニティはフィードバックを高く評価しています。
Hadoopに対してアプリケーションを開発中に問題が発生した場合は、いずれの場合でも、ダウンストリーム開発者はHadoop開発コミュニティに連絡することを推奨します。1人の開発者にとって問題であれば、多くの開発者が遭遇している、または遭遇する可能性のある問題である可能性が高いです。
Hadoopでのストリーム（例：FSDataOutputStream）の処理において、アプリケーションはStreamCapabilitiesクラスのメソッドを使用して、ストリームの機能をプログラムで照会できます。ストリーム機能に動的に適応することで、変化する実装と環境において、アプリケーションの堅牢性を向上させることができます。
Hadoop REST APIは、様々なダウンストリームおよび内部アプリケーションやサービスの主要なインターフェースです。RESTクライアントをサポートするために、Hadoop REST APIはバージョン管理されており、バージョン内では非互換な変更は行われません。エンドポイント自体、サポートされているパラメータのリスト、およびエンドポイントからの出力は、RESTエンドポイントのバージョン内では非互換な変更が禁止されています。ただし、新しいフィールドやその他の追加的な変更は互換性のある変更とみなされるため、REST APIのコンシューマは、未知のフィールドを無視できるだけの柔軟性を持つ必要があります。
REST APIのバージョンは単一の数字であり、Hadoopのバージョン番号とは関係ありません。バージョン番号は、「v」で始まるエンドポイントURLにエンコードされます（例：「v1」）。新しいRESTエンドポイントバージョンは、マイナーリリースまたはメジャーリリースでのみ導入できます。RESTエンドポイントバージョンは、メジャーリリース全体で非推奨とマークされた後にのみ削除できます。
Hadoopは、アプリケーションクライアントやダウンストリームライブラリによって消費される可能性のある様々な出力を生成します。Hadoopからの出力を使用する際には、次の点を考慮してください。
シーケンスファイル、HARファイルなど、Hadoopがデータの格納に使用しているバイナリファイル形式は、マイナーリリース間で互換性が維持されることが保証されています。さらに、メジャーリリース間で変更が行われた場合、後方互換性と前方互換性の両方が維持されなければなりません。シーケンスファイル形式だけが非互換な変更がないことが保証されていることに注意してください。そこに含まれるシリアライズされたクラスは保証されていません。
操作によって生成されたデータに加えて、HadoopはHDFSメタデータストア、YARNリソースマネージャ状態ストア、YARNフェデレーション状態ストアなど、様々な形式の様々なデータストアに状態情報を維持しています。すべてのHadoop内部データストアは、Hadoopに対して内部的かつPrivateとみなされます。ダウンストリーム開発者は、データまたはデータ形式が予測不可能に変更される可能性があるため、Hadoop状態ストアからのデータの消費を試みるべきではありません。
Hadoopコマンドラインインターフェースを構成するツールのセットは、エンドユーザーと、CLIツールを実行して出力を解析するツールを作成するダウンストリーム開発者の両方が使用することを目的としています。このため、Hadoop CLIツールはインターフェースとして扱われ、メジャーリリース間で安定性が維持されます。メジャーリリース間では、CLIツールのオプションは削除されたり、意味的に変更されたりしません。同様に、CLIツールからの出力は、メジャーバージョン番号内では同じままです。CLIツールの出力に対する変更は非互換な変更とみなされるため、メジャーバージョン間ではCLI出力は変更されません。CLIツールの出力は、CLIツールによって生成されるログ出力とは異なることに注意してください。ログ出力は自動化された消費を目的としておらず、いつでも変更される可能性があります。
Hadoopによって公開されているWeb UIは、人間が使用する目的のみです。データのためにUIをスクレイピングすることは、サポートされているユースケースではありません。リリース間でWeb UIに表示されるデータの互換性を確保するための努力は行われていません。
Hadoopは、XML設定ファイルとログ設定ファイルという2つの主要な形式の設定ファイルを使用します。
XML設定ファイルには、名前と値のペアとしてプロパティのセットが含まれています。プロパティの名前と意味はHadoopによって定義され、マイナーリリース間で安定性が維持されることが保証されています。プロパティはメジャーリリースでのみ削除でき、少なくともメジャーリリース全体で非推奨とマークされている場合のみです。ほとんどのプロパティには、XML設定ファイルに明示的に設定されていない場合に使用されるデフォルト値があります。デフォルトのプロパティ値は、メンテナンスリリース中は変更されません。様々なHadoopコンポーネントによってサポートされているプロパティの詳細については、コンポーネントのドキュメントを参照してください。
ダウンストリーム開発者とユーザーは、ツールやアプリケーションで使用するために、独自の属性をXML設定ファイルに追加できます。Hadoopは新しいプロパティの定義について正式な制限を設けていませんが、Hadoopによって定義されているプロパティと競合する新しいプロパティは、予期せず望ましくない結果につながる可能性があります。ユーザーは、Hadoopによって定義されているプロパティの名前空間と競合するカスタム設定プロパティ名を使用しないようにし、したがってHadoopによって使用されているプレフィックス（例：hadoop、io、ipc、fs、net、ftp、ha、file、dfs、mapred、mapreduce、yarn）を使用しないようにすることをお勧めします。
HadoopデーモンとCLIによって生成されるログ出力は、設定ファイルのセットによって管理されます。これらのファイルは、Hadoopの様々なコンポーネントによって出力されるログメッセージの最小レベル、およびそれらのメッセージの格納場所と方法を制御します。マイナーリリース間では、ログメッセージを削減、削除、またはリダイレクトするログ設定の変更は行われません。
Hadoopは、JSONリソースプロファイル設定やXMLフェアスケジューラ設定など、様々な形式の他の種類の設定ファイルを多数使用しています。マイナーリリース内では、設定ファイル形式に非互換な変更は導入されません。マイナーリリース間でも、可能な限り非互換な設定ファイル形式の変更は回避されます。
ダウンストリーム開発者またはHadoopのコンシューマとして、ソースコード、設定ファイル、ビルドアートファクトなど、Hadoopプラットフォームのすべての要素にアクセスできます。プラットフォームのオープンな性質によって許可されていますが、開発者は、いつでも変更される可能性のあるHadoopのこれらの内部詳細に依存関係を作成するべきではありません。ただし、Hadoop開発コミュニティは、メジャーバージョン内では既存の構造を安定させるように試みます。
Hadoop設定ファイル、ジョブ履歴情報（ジョブ履歴サーバーによって消費される）、およびHadoopによって生成されるログファイルの場所と一般的な構造は、メンテナンスリリース間で維持されます。
Hadoopビルドプロセスによって生成されるビルドアートファクト（例：JARファイル）は、いつでも変更される可能性があり、クライアントアーティファクトを除いて、信頼できるものとして扱うべきではありません。クライアントアーティファクトとその内容は、メジャーリリース内では互換性が維持されます。アプリケーションコードがマイナーリリース間で、そして可能な限りメジャーリリース間でも変更せずに機能し続けることを可能にすることが、Hadoop開発コミュニティの目標です。現在のクライアントアーティファクトのリストは以下のとおりです。
一部のHadoopコンポーネントは、環境変数を通じて情報を受け取ります。たとえば、HADOOP_OPTS環境変数は、ほとんどのHadoopプロセスによって、新しいJVMの起動時に使用される追加のJVM引数の文字列として解釈されます。マイナーリリース間では、Hadoopが環境変数を解釈する方法が非互換な方法で変更されることはありません。つまり、同じ変数に配置された同じ値は、同じメジャーバージョン内のすべてのHadoopリリースで同じ結果を生成する必要があります。
Hadoopは、動作のために多数のサードパーティライブラリに依存しています。Hadoop開発コミュニティは、可能な限りこれらの依存関係をダウンストリーム開発者から隠蔽するように努めています。Guavaなどの一般的なライブラリは、これらの依存関係がダウンストリームに公開されている場合、Hadoopとダウンストリームアプリケーション間に重大な互換性の問題を引き起こす可能性があります。それにもかかわらず、Hadoopは、特にHadoop 3以前では、一部の依存関係を公開しています。メジャーリリース間では、クライアントアーティファクトによってHadoopによって新しい依存関係が公開されることはありません。
一般的なダウンストリームのアンチパターンとして、hadoop classpath の出力を用いてダウンストリームアプリケーションのクラスパスを設定したり、Hadoopに含まれるサードパーティ製のJARファイルを全てダウンストリームアプリケーションのクラスパスに追加したりすることがあります。この方法は、ダウンストリームアプリケーションとHadoopのサードパーティ依存関係を強く結びつけ、Hadoopの依存関係が変化すると保守が困難になる脆弱なアプリケーションにつながります。この方法は強く推奨しません。
Hadoopは動作にJava仮想マシンに依存しており、ダウンストリームアプリケーションに影響を与える可能性があります。混乱を最小限に抑えるため、Hadoopのメジャーリリース間では、サポートされるJVMの最小バージョンは変更されません。現在のサポートされるJVMの最小バージョンがメジャーリリース間でサポートされなくなる場合、マイナーリリースでサポートされるJVMの最小バージョンが変更される可能性があります。
Hadoopには、圧縮、コンテナ実行バイナリ、および様々なネイティブ統合を含むいくつかのネイティブコンポーネントも含まれています。これらのネイティブコンポーネントは、Hadoopのネイティブ依存関係のセットを導入します。ネイティブ依存関係のセットはマイナーリリースで変更される可能性がありますが、Hadoop開発者コミュニティは、依存関係のバージョンの変更を可能な限りマイナーバージョンの変更に制限しようとします。
Hadoopは現在、x86およびAMDプロセッサを搭載したLinuxとWindows上で、Hadoop開発者コミュニティによってサポートされています。これらのOSとプロセッサは、当面の間、サポートされる可能性が高いです。サポート計画が変更された場合、廃止されるOSまたはプロセッサは、実際に廃止される前に、少なくとも1つのマイナーリリース、できれば1つのメジャーリリースの間、非推奨として文書化されます。Hadoopは他のOSやプロセッサアーキテクチャでも動作する可能性がありますが、問題が発生した場合、コミュニティは支援できない可能性があります。
Hadoopデーモンに必要な最小リソースがリリース間、メンテナンスリリース間でもどのように変化するかの保証はありません。それにもかかわらず、Hadoop開発者コミュニティは、マイナーリリース内で要件を増やすことを避けるよう努めます。
FileSystem APIなどを介してHadoopがサポートするファイルシステムは、ほとんどの場合、メジャーリリース全体で引き続きサポートされます。メジャーバージョン内でファイルシステムのサポートを削除できる唯一のケースは、代替クライアント実装へのクリーンな移行パスが提供される場合です。
Apache Hadoopに対するアプリケーションやプロジェクトの開発に関する質問は、関連するコンポーネントの開発者メーリングリストにお問い合わせください。