This {@code 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 {@code 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 * {@link #read read} and {@link #write write} methods to read the value into * or write from a {@link ByteBuffer}. This {@code FileAttributeView} is not * intended for use where the size of an attribute value is larger than {@link * 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 * {@code RuntimePermission("accessUserDefinedAttributes")} permission when a * security manager is installed. * *
The {@link java.nio.file.FileStore#supportsFileAttributeView * supportsFileAttributeView} method may be used to test if a specific {@link * java.nio.file.FileStore FileStore} supports the storage of user-defined * attributes. * *
Where dynamic access to file attributes is required, the {@link
* java.nio.file.Files#getAttribute getAttribute} method may be used to read
* the attribute value. The attribute value is returned as a byte array (byte[]).
* The {@link java.nio.file.Files#setAttribute setAttribute} method may be used
* to write the value of a user-defined attribute from a buffer (as if by
* invoking the {@link #write write} method), or byte array (byte[]).
*
* @since 1.7
*/
public interface UserDefinedFileAttributeView
extends FileAttributeView
{
/**
* Returns the name of this attribute view. Attribute views of this type
* have the name {@code "user"}.
*/
@Override
String name();
/**
* Returns a list containing the names of the user-defined attributes.
*
* @return An unmodifiable list continaing the names of the file's
* user-defined
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}("accessUserDefinedAttributes")
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
List This method reads the value of the attribute into the given buffer
* as a sequence of bytes, failing if the number of bytes remaining in
* the buffer is insufficient to read the complete attribute value. The
* number of bytes transferred into the buffer is {@code n}, where {@code n}
* is the size of the attribute value. The first byte in the sequence is at
* index {@code p} and the last byte is at index {@code p + n - 1}, where
* {@code p} is the buffer's position. Upon return the buffer's position
* will be equal to {@code p + n}; its limit will not have changed.
*
* Usage Example:
* Suppose we want to read a file's MIME type that is stored as a user-defined
* attribute with the name "{@code user.mimetype}".
* This method writes the value of the attribute from a given buffer as
* a sequence of bytes. The size of the value to transfer is {@code r},
* where {@code r} is the number of bytes remaining in the buffer, that is
* {@code src.remaining()}. The sequence of bytes is transferred from the
* buffer starting at index {@code p}, where {@code p} is the buffer's
* position. Upon return, the buffer's position will be equal to {@code
* p + n}, where {@code n} is the number of bytes transferred; its limit
* will not have changed.
*
* If an attribute of the given name already exists then its value is
* replaced. If the attribute does not exist then it is created. If it
* implementation specific if a test to check for the existence of the
* attribute and the creation of attribute are atomic with repect to other
* file system activities.
*
* Where there is insufficient space to store the attribute, or the
* attribute name or value exceed an implementation specific maximum size
* then an {@code IOException} is thrown.
*
* Usage Example:
* Suppose we want to write a file's MIME type as a user-defined attribute:
*
* UserDefinedFileAttributeView view = file
* .getFileAttributeView(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();
*
*
* @param name
* The attribute name
* @param dst
* The destination buffer
*
* @return The number of bytes read, possibly zero
*
* @throws IllegalArgumentException
* If the destination buffer is read-only
* @throws IOException
* If an I/O error occurs or there is insufficient space in the
* destination buffer for the attribute value
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}("accessUserDefinedAttributes")
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*
* @see #size
*/
int read(String name, ByteBuffer dst) throws IOException;
/**
* Writes the value of a user-defined attribute from a buffer.
*
*
* UserDefinedFileAttributeView view = file
* .getFileAttributeView(UserDefinedFileAttributeView.class);
* view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
*
*
* @param name
* The attribute name
* @param src
* The buffer containing the attribute value
*
* @return The number of bytes written, possibly zero
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}("accessUserDefinedAttributes")
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
int write(String name, ByteBuffer src) throws IOException;
/**
* Deletes a user-defined attribute.
*
* @param name
* The attribute name
*
* @throws IOException
* If an I/O error occurs or the attribute does not exist
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link
* RuntimePermission}("accessUserDefinedAttributes")
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void delete(String name) throws IOException;
}