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()
僅支援在輸出僅在呼叫 close()
時才顯示的輸出串流上,例如 S3A 檔案系統傳回的輸出串流。
串流必須實作 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
,則它應傳回 true
給 PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")
。這是為了允許應用程式驗證儲存體是否支援此功能。
如果檔案系統在路徑 P
下不支援 Abortable
,則它必須傳回 false
給 PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")