Module  java.base
软件包  java.nio.file.attribute

Interface UserDefinedFileAttributeView

  • All Superinterfaces:
    AttributeView ， FileAttributeView 

    public interface UserDefinedFileAttributeView
extends FileAttributeView
    文件属性视图，提供文件的用户定义属性（有时称为扩展属性）的视图。 用户定义的文件属性用于存储具有对文件系统无意义的文件的元数据。 它主要用于直接支持这种能力但可能被仿真的文件系统实现。 这种仿真的细节是高度实现具体的，因此没有指定。

    此FileAttributeView提供了一个文件的用户定义属性作为一组名称/值对的视图，其中属性名称由String表示。 当访问属性时，实现可能需要从平台或文件系统表示进行编码和解码。 该值具有不透明的内容。 此属性视图定义了read和write方法，以从ByteBuffer读取或写入值。 此FileAttributeView不适用于属性值的大小大于Integer.MAX_VALUE的位置 。

    在一些实现中可以使用用户定义的属性来存储与安全相关的属性，因此，至少在默认提供者的情况下，访问用户定义属性的所有方法在安装安全管理器时都需要RuntimePermission("accessUserDefinedAttributes")权限。

    supportsFileAttributeView方法可用于测试特定的FileStore是否支持用户定义属性的存储。

    在需要动态访问文件属性的地方，可以使用getAttribute方法来读取属性值。 属性值作为字节数组返回（byte []）。 setAttribute方法可用于从缓冲区（如通过调用write方法）或字节数组（byte []）写入用户定义属性的值。

    从以下版本开始：
    1.7

    • 方法详细信息

      • name

        String name​()
        返回此属性视图的名称。 此类型的属性视图名称为"user" 。
        Specified by:
        name在接口 AttributeView
        结果
        属性视图的名称

      • list

        List<String> list​()
           throws IOException
        返回包含用户定义属性名称的列表。
        结果
        一个不可修改的列表，其中包含文件用户定义的名称
        异常
        IOException - 如果发生I / O错误
        SecurityException - 在默认提供程序的情况下，安装了一个安全管理器，并且它拒绝RuntimePermission ("accessUserDefinedAttributes")或其checkRead方法拒绝对该文件的读取访问。

      • read

        int read​(String name,
         ByteBuffer dst)
  throws IOException
        将用户定义属性的值读入缓冲区。

        此方法将属性值作为字节序列读入给定的缓冲区，如果缓冲区中剩余的字节数不足以读取完整的属性值，则会失败。 传输到缓冲区的字节数为n ，其中n是属性值的大小。 序列中的第一个字节的索引为p和最后一个字节是指数p + n - 1 ，其中p是缓冲区的位置。 缓冲区的返回位置将等于p + n ; 其限制将不会改变。

        用法示例：假设我们要读取一个文件的MIME类型，该类型以用户定义的属性存储，名称为“ user.mimetype ”。 

          UserDefinedFileAttributeView view =
        Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
    String name = "user.mimetype";
    ByteBuffer buf = ByteBuffer.allocate(view.size(name));
    view.read(name, buf);
    buf.flip();
    String value = Charset.defaultCharset().decode(buf).toString();
        参数
        name - 属性名称
        dst - 目的缓冲区
        结果
        读取的字节数，可能为零
        异常
        IllegalArgumentException - 如果目标缓冲区是只读的
        IOException - 如果发生I / O错误或目标缓冲区中的属性值空间不足
        SecurityException - 在默认提供程序的情况下，安装了一个安全管理器，它将拒绝RuntimePermission ("accessUserDefinedAttributes")或其checkRead方法拒绝对该文件的读取访问。
        另请参见：
        size(java.lang.String)

      • write

        int write​(String name,
          ByteBuffer src)
   throws IOException
        从缓冲区写入用户定义属性的值。

        该方法将给定缓冲区中的属性值作为字节序列。 要传输的值的大小是r ，其中r是缓冲区中剩余的字节数，即src.remaining() 。 字节序列从索引p开始的缓冲区p ，其中p是缓冲区的位置。 一旦返回，缓冲区的位置将等于p + n ，其中n是传输的字节数; 其限制将不会改变。

        如果给定名称的属性已经存在，那么它的值将被替换。 如果属性不存在，则创建它。 如果实现具体，如果检查属性的存在和属性的创建的测试对于其他文件系统活动是原子的。

        如果没有足够的空间存储属性，或者属性名称或值超过实现特定的最大大小，则抛出IOException 。

        使用示例：假设我们要将文件的MIME类型写成用户定义的属性： 

          UserDefinedFileAttributeView view =
        FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class);
    view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
        参数
        name - 属性名称
        src - 包含属性值的缓冲区
        结果
        写入的字节数，可能为零
        异常
        IOException - 如果发生I / O错误
        SecurityException - 在默认提供程序的情况下，安装了一个安全管理器，并且它拒绝270566674487878 ("accessUserDefinedAttributes")或其checkWrite方法拒绝对该文件的写访问。

      • delete

        void delete​(String name)
     throws IOException
        删除用户定义的属性。
        参数
        name - 属性名称
        异常
        IOException - 如果发生I / O错误或属性不存在
        SecurityException - 在默认提供程序的情况下，安装了一个安全管理器，它将拒绝RuntimePermission ("accessUserDefinedAttributes")或其checkWrite方法拒绝对该文件的写入访问。