接口 PathCapabilities

PathCapabilities 接口提供了一种编程方式，用于查询由 FileSystem、FileContext 或其他实现类实例在给定路径下提供的操作。

public interface PathCapabilities {
  boolean hasPathCapability(Path path, String capability)
      throws IOException;
}

这里有几个目标：

  1. 允许调用者探测可选的文件系统操作，而无需实际调用它们。
  2. 允许具有自身可选实例级特性的文件系统声明这些特性是否在特定实例中处于活动状态。
  3. 允许与对象存储协同工作的文件系统连接器暴露这些存储的语义基础差异（例如：文件在关闭前不可见，文件重命名为O(data)操作，目录重命名非原子性等）。

可用功能

功能被定义为字符串，并分为“通用功能”和针对特定存储的非标准功能。

通用功能都定义在fs.capability.前缀下

请查阅org.apache.hadoop.fs.CommonPathCapabilities的javadocs以获取这些信息。

各个文件系统可能会提供自己的一组功能，这些功能可以被探测到。这些功能的名称必须以fs. + 文件系统方案 + .capability开头。例如fs.s3a.capability.select.sql;

boolean hasPathCapability(path, capability)

探测在给定路径下提供特定功能的实例。

后置条件

if fs_supports_the_feature(path, capability):
  return True
else:
  return False

返回: True, 当且仅当特定功能可用时。

文件系统实例不得返回True表示支持任何功能，除非确认该特定实例确实支持该功能。因此，如果调用方探测某项功能，则可以认为该特定特性/语义是可用的。

如果探针返回False，则可能表示以下情况之一：

  1. 该功能未知。
  2. 该功能已知，且已知在此实例上不可用。
  3. 已知该功能，但本地类无法确定在提供的路径下是否支持。

该谓词设计为低开销。如果需要进行除路径/链接解析之外的远程调用，它应得出该功能可用性未知的结论并返回False。

谓词必须也是无副作用的。

路径的有效性 无需检查路径是否存在；该参数的存在是为了让任何将操作转发到其他文件系统（例如 viewfs）的文件系统能够解析并将其转发到嵌套文件系统。可以认为该调用是相对轻量级的。

因此，虽然文件系统声明它在某个路径下支持某项功能，但由于其他原因，实际操作可能会失败。

举个例子，虽然文件系统可能支持在某个路径下使用append()，但如果对目录调用该操作，可能会导致调用失败。

对于路径 root = new Path("/")：能力调用可能会成功

fs.hasCapabilities(root, "fs.capability.append") == true

但随后对该特定路径的操作可能会失败，因为根路径是一个目录：

fs.append(root)

同样地，系统不会检查调用者是否有权限执行特定操作：仅仅因为某个功能在该路径上可用，并不意味着调用者可以执行该操作。

因此，hasCapabilities(path, capability)探针声明的是该操作不会被以不支持为由拒绝，而非调用者在该路径上的特定调用会被允许。

可用时长

随着远程存储状态的变化，路径能力也可能随之改变。这可能是由于文件系统本地状态的变更（例如符号链接或挂载点的变化），或其功能的变更（例如由于操作变更、系统升级等原因导致某项功能变为可用/不可用）。

必须调用以确定可用性的功能

某些操作可能被客户端连接器识别并认为可用，但实际上由于远程存储的状态和权限问题（这些状态无法预先确定，只能通过尝试具有副作用的操作来验证），在调用时可能会失败。

一个关键的例子是符号链接和本地文件系统。文件系统声明支持此功能，除非显式禁用符号链接——当调用时它们实际上可能会失败。

实现者说明

实现者不得为任何不能保证支持的功能返回true。返回true表示根据文件系统客户端所知，该文件系统的实现/部署确实提供了所查询的期望操作和语义。

出于性能考虑，实现不应检查路径是否存在，除非需要解析路径中的符号链接以确定是否存在某个功能。这对FileContext和viewfs是必需的。

各个文件系统不得单方面定义新的以fs.capability为前缀的功能。相反，它们必须执行以下操作之一：

  • 定义并稳定新的跨文件系统能力标志（首选方式），从而正式添加一个新的fs.capability值。
  • 使用文件系统的方案作为其自身选项的前缀，例如 fs.hdfs.