接口 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 然后返回，则它保证写入不得可见，并且目标路径中文件系统中的任何现有数据都将继续可用。

  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，则它应向 PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable") 返回 true。这是为了允许应用程序验证存储是否支持该功能。

如果文件系统在路径 P 下不支持 Abortable，则它必须向 PathCababilities.hasPathCapability(path, "fs.capability.outputstream.abortable") 返回 false