FileSystem.openFile()/FileContext.openFile()

これは、FileSystemとFileContextの両方によって提供されるメソッドであり、高度なファイルオープンオプションと、実装されている場合は非同期/遅延ファイルオープンをサポートします。

標準およびファイルシステム固有の両方のオプションをサポートする、ファイルをオープンするためのビルダーを作成します。build()呼び出しの戻り値はFuture<FSDataInputStream>であり、待機する必要があります。ファイルのオープンは非同期になる可能性があり、実際には読み取りが実際に実行されるまで延期される可能性があります（パーミッション/存在チェックを含む）。

このAPI呼び出しは、Hadoop 3.3.0でFileSystemとFileContextに追加されました。Hadoop 3.3.1で次のように調整されました。

FutureDataInputStreamBuilder openFile(Path path)

pathにあるファイルをリードのために開く操作を構築するためのFutureDataInputStreamBuilderを作成します。

返されたFutureDataInputStreamBuilderインスタンスでbuild()が呼び出されると、ビルダーパラメータが検証され、FileSystem.openFileWithOptions(Path, OpenFileParameters)またはAbstractFileSystem.openFileWithOptions(Path, OpenFileParameters)が呼び出されます。

これらの保護されたメソッドはCompletableFuture<FSDataInputStream>を返し、そのget()メソッドが呼び出されると、開かれたファイルの内容の入力ストリームを返すか、例外を発生させます。

FileSystem.openFileWithOptions(PathHandle, OpenFileParameters)の基本実装は最終的にFileSystem.open(Path, int)を呼び出します。

したがって、チェーンFileSystem.openFile(path).build().get()は、FileSystem.open(Path p, int bufferSize)と同じ前提条件と事後条件を持ちます。

ただし、実装が利用できる1つの違いがあります。

返されたストリームは、ファイルが存在しないことやアクセス許可の失敗が実際のデータの最初のread()まで表面化しない可能性のある遅延オープンを実装する場合があります。

これにより、オブジェクトストアのネットワークIOを節約できます。

openFile()操作は、その呼び出し中にファイルシステムの状態をチェックする場合がありますが、ファイルシステムの状態はこの呼び出しと実際のbuild()およびget()操作の間で変化する可能性があるため、このファイル固有の前提条件（ファイルが存在する、ファイルは読み取り可能など）はここでチェックしてはなりません。

open(Path, int)を実装しないFileSystem実装は、FutureDataInputStreamBuilder.build()またはその後のget()呼び出しまでUnsupportedOperationExceptionの発生を延期するか、openFile()呼び出しで高速に失敗する可能性があります。

ビルダーの使用方法、および渡すことができる標準オプションについては、FutureDataInputStreamBuilderを参照してください。

FutureDataInputStreamBuilder openFile(PathHandle)

指定されたPathHandleで識別されるファイルをリードのために開く操作を構築するためのFutureDataInputStreamBuilderを作成します。

ファイルシステムによって実装されている場合、openFile(Path)のセマンティクスと同じです。したがって、チェーンopenFile(pathhandle).build().get()は、open(Pathhandle, int)と同じ前提条件と事後条件を持ちます。

open(PathHandle handle, int bufferSize)を実装しないFileSystem実装は、FutureDataInputStreamBuilder.build()またはその後のget()呼び出しまでUnsupportedOperationExceptionの発生を延期するか、openFile(PathHandle)呼び出しで高速に失敗する可能性があります。

基本実装では、build()操作でこの例外が発生します。他の実装もこれをコピーする必要があります。

実装者のメモ

openFileWithOptions()の基本実装は、実際にはopen(path)操作を同期的に実行しますが、それでも結果またはエラーをCompletableFuture<>で返すため、すべてのファイルシステムで一貫したライフサイクルを提供します。

ファイルを開く時間がかかる可能性のあるファイルシステムクライアントでは、何らかのexecutor/スレッドプールで操作を送信することで非同期に実行する必要があります。これは、長距離接続を介してアクセスされる可能性のあるオブジェクトストアやその他のファイルシステムに特に推奨されます。

任意のファイルシステム固有のオプションがサポートされる場合があります。これらは、ファイルシステムスキーマ（例：hdfs.）または通常の構成設定fs.SCHEMA形式（例：fs.hdfs）で接頭辞を付ける必要があります。後者のスタイルにより、ファイルシステム構成とファイル固有の構成の両方で同じ構成オプションを使用できます。

ユーザーに一貫したモデルを提供するために、常にオプションを指定せずにファイルをオープンできるようにする必要があります。ただし、実装では、1つ以上の必須オプションを設定することを選択できます。

返されたストリームは、ファイルアクセスの「遅延」評価を実行する場合があります。これは、存在のプローブがコストが高く、非同期オープンがあっても不要とみなされる可能性のあるオブジェクトストアに関連しています。