org.apache.hadoop.fs.Abortable出力を表示しないように、アクティブな操作を中止します。
特に、出力ストリームでサポートされている場合、成功したabort()は、close()操作でストリームが表示されないことを保証する必要があります。
@InterfaceAudience.Public
@InterfaceStability.Unstable
public interface Abortable {
/**
* Abort the active operation without the output becoming visible.
*
* This is to provide ability to cancel the write on stream; once
* a stream is aborted, the write MUST NOT become visible.
*
* @throws UnsupportedOperationException if the operation is not supported.
* @return the result.
*/
AbortableResult abort();
/**
* Interface for the result of aborts; allows subclasses to extend
* (IOStatistics etc) or for future enhancements if ever needed.
*/
interface AbortableResult {
/**
* Was the stream already closed/aborted?
* @return true if a close/abort operation had already
* taken place.
*/
boolean alreadyClosed();
/**
* Any exception caught during cleanup operations,
* exceptions whose raising/catching does not change
* the semantics of the abort.
* @return an exception or null.
*/
IOException anyCleanupException();
}
}
abort()進行中の操作を中止し、操作が完了したときに、出力が可視にならないようにします。
他のファイルシステムクラスがAbortableを実装するまでは、このインターフェースは出力ストリームのみを対象として指定されます。
abort()Abortable.abort()は、例えばS3Aファイルシステムによって返される出力ストリームのように、close()が呼び出されたときにのみ出力が表示される出力ストリームでのみサポートする必要があります。
ストリームは、AbortableとStreamCapabilitiesを実装する必要があります。
if unsupported:
throw UnsupportedException
if not isOpen(stream):
no-op
StreamCapabilities.hasCapability("fs.capability.outputstream.abortable") == True
abort()が返された後、ファイルシステムは変更されていない必要があります。
FS' = FS
成功したabort()操作は、ストリームclose()が呼び出されたときに、出力が表示されないことを保証する必要があります。
厳密に言えば
Abortable.abort()がUnsupportedOperationExceptionを発生させずに返される場合、書き込みは表示されず、宛先パスのファイルシステム内の既存のデータは引き続き利用可能であることを保証します。
write()メソッドの呼び出しは失敗する必要があります。flush()の呼び出しは、何もしない必要があります（アプリケーションは、クローズされたストリームでこれを呼び出すことがあります）。abort()の呼び出しは、何もしない必要があります。close()は、ファイルを表示してはいけません。また、例外を発生させてはいけません。つまり、close()の事後条件は次のようになります
FS' = FS
一時データがローカルファイルシステムまたはストアのアップロードインフラストラクチャに保存されている場合、これはクリーンアップされる場合があります。ここでは、最善の努力が期待されます。
ストリームはクリーンアップ操作を再試行しないでください。そこでの失敗はすべてキャッチされ、AbortResultに追加される必要があります。
AbortResult返されるAbortResultの値は、主にテストとロギング用です。
alreadyClosed(): 書き込みがすでに中止またはクローズされている場合は、trueを返す必要があります。
anyCleanupException();: オプションのクリーンアップ操作中に発生したIOExceptionを返す必要があります。
出力ストリーム自体は、正式にはスレッドセーフである必要はありませんが、アプリケーションが時々そうであると仮定するため、この呼び出しはスレッドセーフである必要があります。
アプリケーションは、実際に呼び出すことなく、ストリームがAbortable.abort()操作をサポートしていることを検証できる必要があります。これは、StreamCapabilitiesインターフェースを介して行われます。
ストリームインスタンスがAbortableをサポートしている場合は、プローブhasCapability("fs.capability.outputstream.abortable")でtrueを返す必要があります。
ストリームインスタンスがAbortableをサポートしていない場合は、プローブhasCapability("fs.capability.outputstream.abortable")でfalseを返す必要があります。
つまり、ストリームがその機能のサポートを宣言した場合、abort()の呼び出しは、操作の定義されたセマンティクスを満たす必要があります。
FileSystem/FileContextの実装は、アプリケーションが宛先ディレクトリ/パスの機能をプローブできるように、同様にサポートを宣言する必要があります。
ファイルシステムがパスPの下でAbortableをサポートしている場合、PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")に対してtrueを返す必要があります。これは、ストアがこの機能をサポートしていることをアプリケーションが検証できるようにするためです。
ファイルシステムがパスPの下でAbortableをサポートしていない場合、PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")に対してfalseを返す必要があります。