Interface UserDefinedFileAttributeView

A file attribute view that provides a view of a file's user-defined attributes, sometimes known as extended attributes. User-defined file attributes are used to store metadata with a file that is not meaningful to the file system. It is primarily intended for file system implementations that support such a capability directly but may be emulated. The details of such emulation are highly implementation specific and therefore not specified.

This FileAttributeView provides a view of a file's user-defined attributes as a set of name/value pairs, where the attribute name is represented by a String. An implementation may require to encode and decode from the platform or file system representation when accessing the attribute. The value has opaque content. This attribute view defines the read and write methods to read the value into or write from a ByteBuffer. This FileAttributeView is not intended for use where the size of an attribute value is larger than Integer.MAX_VALUE.

User-defined attributes may be used in some implementations to store security related attributes so consequently, in the case of the default provider at least, all methods that access user-defined attributes require the RuntimePermission("accessUserDefinedAttributes") permission when a security manager is installed.

The supportsFileAttributeView method may be used to test if a specific FileStore supports the storage of user-defined attributes.

Where dynamic access to file attributes is required, the getAttribute method may be used to read the attribute value. The attribute value is returned as a byte array (byte[]). The setAttribute method may be used to write the value of a user-defined attribute from a buffer (as if by invoking the write method), or byte array (byte[]).

Methods

name

String name()

Returns the name of this attribute view. Attribute views of this type have the name "user".

Specified by:

name in interface AttributeView

Returns:

the name of the attribute view

list

List<String> list()
           throws IOException

Returns a list containing the names of the user-defined attributes.

Returns:

An unmodifiable list containing the names of the file's user-defined

Throws:

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, a security manager is installed, and it denies RuntimePermission("accessUserDefinedAttributes") or its checkRead method denies read access to the file.

size

int size(String name)
  throws IOException

Returns the size of the value of a user-defined attribute.

Parameters:

name - The attribute name

Returns:

The size of the attribute value, in bytes.

Throws:

ArithmeticException - If the size of the attribute is larger than Integer.MAX_VALUE

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, a security manager is installed, and it denies RuntimePermission("accessUserDefinedAttributes") or its checkRead method denies read access to the file.

read

int read(String name,
         ByteBuffer dst)
  throws IOException

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();

Parameters:

name - The attribute name

dst - The destination buffer

Returns:

The number of bytes read, possibly zero

Throws:

IllegalArgumentException - If the destination buffer is read-only

IOException - If an I/O error occurs or there is insufficient space in the destination buffer for the attribute value

SecurityException - In the case of the default provider, a security manager is installed, and it denies RuntimePermission("accessUserDefinedAttributes") or its checkRead method denies read access to the file.

See Also:

size(java.lang.String)

write

int write(String name,
          ByteBuffer src)
   throws IOException

UserDefinedFileAttributeView view =
        FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class);
    view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));

Parameters:

name - The attribute name

src - The buffer containing the attribute value

Returns:

The number of bytes written, possibly zero

Throws:

IOException - If an I/O error occurs

SecurityException - In the case of the default provider, a security manager is installed, and it denies RuntimePermission("accessUserDefinedAttributes") or its checkWrite method denies write access to the file.

delete

void delete(String name)
     throws IOException

Deletes a user-defined attribute.

Parameters:

name - The attribute name

Throws:

IOException - If an I/O error occurs or the attribute does not exist

SecurityException - In the case of the default provider, a security manager is installed, and it denies RuntimePermission("accessUserDefinedAttributes") or its checkWrite method denies write access to the file.