Module java.base

Package java.nio.file.attribute

Interface UserDefinedFileAttributeView

所有超级接口:

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版本起:

1.7

Method Summary

Modifier and Type	Method	Description
void	delete(String name)	删除用户定义属性。
List<String>	list()	返回包含用户定义属性名称的列表。
String	name()	返回此属性视图的名称。
int	read(String name, ByteBuffer dst)	将用户定义属性的值读入缓冲区。
int	size(String name)	返回用户定义属性值的大小。
int	write(String name, ByteBuffer src)	将用户定义属性的值从缓冲区写入。

Method Details

name

             String name()
            

返回此属性视图的名称。此类型的属性视图的名称为"user"。

指定者:

name 在接口 AttributeView

返回:

属性视图的名称

list

             List<String> list() throws IOException
            

返回包含用户定义属性名称的列表。

返回:

包含文件用户定义属性名称的不可修改列表

抛出:

IOException - 如果发生I/O错误

SecurityException - 在默认提供程序的情况下，安全管理器已安装，并且拒绝RuntimePermission("accessUserDefinedAttributes")或其checkRead方法拒绝对文件的读取访问。

size

             int size(String name) throws IOException
            

返回用户定义属性值的大小。

参数:

name - 属性名称

返回:

属性值的大小，以字节为单位。

抛出:

ArithmeticException - 如果属性的大小大于Integer.MAX_VALUE

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 + 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 - 在默认提供程序的情况下，安全管理器已安装，并且拒绝RuntimePermission("accessUserDefinedAttributes")或其checkWrite方法拒绝对文件的写入访问。

delete

             void delete(String name) throws IOException
            

删除用户定义属性。

参数:

name - 属性名称

抛出:

IOException - 如果发生I/O错误或属性不存在

SecurityException - 在默认提供程序的情况下，安装了安全管理器，并且它拒绝RuntimePermission("accessUserDefinedAttributes")或其checkWrite方法拒绝对文件的写访问。