介面 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 檔案系統傳回的輸出串流。

前置條件

串流必須實作 AbortableStreamCapabilities

 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,則傳回,然後保證寫入不得變為可見,且目的地路徑中檔案系統中的任何現有資料都應繼續可用。

  1. 呼叫 write() 方法必須失敗。
  2. 呼叫 flush() 必須為無操作(應用程式有時會在關閉的串流上呼叫此方法)
  3. 後續呼叫 abort() 必須為無操作。
  4. close() 不得顯示檔案,且不得引發例外

也就是說,close() 的後置條件變為

FS' = FS

清除

  • 如果暫時資料儲存在本機檔案系統或儲存體的上傳基礎架構中,則可以清除此資料;在此處預期盡力而為。

  • 串流不應重試清除作業;任何失敗都必須捕捉並新增至 AbortResult

傳回的 AbortResult

傳回的 AbortResult 值主要用於測試和記錄。

alreadyClosed():如果寫入已中止或關閉,則必須傳回 true

anyCleanupException();:應傳回在任何選用清除作業期間引發的任何 IOException。

執行緒安全性與原子性

輸出串流本身並未正式要求為執行緒安全,但由於應用程式有時會假設它們是執行緒安全,因此此呼叫必須為執行緒安全。

路徑/串流功能「fs.capability.outputstream.abortable」

應用程式必須能夠驗證串流支援 Abortable.abort() 作業,而不實際呼叫它。這是透過 StreamCapabilities 介面完成的。

  1. 如果串流執行個體支援 Abortable,則它必須在探測 hasCapability("fs.capability.outputstream.abortable") 中傳回 true

  2. 如果串流執行個體不支援 Abortable,則它必須在探測 hasCapability("fs.capability.outputstream.abortable") 中傳回 false

也就是說:如果串流宣告它支援此功能,呼叫 abort() 應符合作業的定義語意。

FileSystem/FileContext 實作應以類似方式宣告支援,以允許應用程式探查目標目錄/路徑中的功能。

如果檔案系統在路徑 P 下支援 Abortable,則它應傳回 truePathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")。這是為了允許應用程式驗證儲存體是否支援此功能。

如果檔案系統在路徑 P 下不支援 Abortable,則它必須傳回 falsePathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable")