-
- All Superinterfaces:
AttributeView,FileAttributeView
public interface UserDefinedFileAttributeView extends FileAttributeView
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
FileAttributeViewprovides a view of a file's user-defined attributes as a set of name/value pairs, where the attribute name is represented by aString. 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 thereadandwritemethods to read the value into or write from aByteBuffer. ThisFileAttributeViewis not intended for use where the size of an attribute value is larger thanInteger.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
supportsFileAttributeViewmethod may be used to test if a specificFileStoresupports the storage of user-defined attributes.Where dynamic access to file attributes is required, the
getAttributemethod may be used to read the attribute value. The attribute value is returned as a byte array (byte[]). ThesetAttributemethod may be used to write the value of a user-defined attribute from a buffer (as if by invoking thewritemethod), or byte array (byte[]).- Since:
- 1.7
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voiddelete(String name)Deletes a user-defined attribute.List<String>list()Returns a list containing the names of the user-defined attributes.Stringname()Returns the name of this attribute view.intread(String name, ByteBuffer dst)Read the value of a user-defined attribute into a buffer.intsize(String name)Returns the size of the value of a user-defined attribute.intwrite(String name, ByteBuffer src)Writes the value of a user-defined attribute from a buffer.
-
-
-
Method Detail
-
name
String name()
Returns the name of this attribute view. Attribute views of this type have the name"user".- Specified by:
namein interfaceAttributeView- 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 occursSecurityException- In the case of the default provider, a security manager is installed, and it deniesRuntimePermission("accessUserDefinedAttributes")or itscheckReadmethod 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 thanInteger.MAX_VALUEIOException- If an I/O error occursSecurityException- In the case of the default provider, a security manager is installed, and it deniesRuntimePermission("accessUserDefinedAttributes")or itscheckReadmethod denies read access to the file.
-
read
int read(String name, ByteBuffer dst) throws IOException
Read the value of a user-defined attribute into a buffer.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
n, wherenis the size of the attribute value. The first byte in the sequence is at indexpand the last byte is at indexp + n - 1, wherepis the buffer's position. Upon return the buffer's position will be equal top + 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 "
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();- Parameters:
name- The attribute namedst- The destination buffer- Returns:
- The number of bytes read, possibly zero
- Throws:
IllegalArgumentException- If the destination buffer is read-onlyIOException- If an I/O error occurs or there is insufficient space in the destination buffer for the attribute valueSecurityException- In the case of the default provider, a security manager is installed, and it deniesRuntimePermission("accessUserDefinedAttributes")or itscheckReadmethod denies read access to the file.- See Also:
size(java.lang.String)
-
write
int write(String name, ByteBuffer src) throws IOException
Writes the value of a user-defined attribute from a buffer.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
r, whereris the number of bytes remaining in the buffer, that issrc.remaining(). The sequence of bytes is transferred from the buffer starting at indexp, wherepis the buffer's position. Upon return, the buffer's position will be equal top + n, wherenis 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 respect 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
IOExceptionis thrown.Usage Example: Suppose we want to write a file's MIME type as a user-defined attribute:
UserDefinedFileAttributeView view = FIles.getFileAttributeView(path, UserDefinedFileAttributeView.class); view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));- Parameters:
name- The attribute namesrc- The buffer containing the attribute value- Returns:
- The number of bytes written, possibly zero
- Throws:
IOException- If an I/O error occursSecurityException- In the case of the default provider, a security manager is installed, and it deniesRuntimePermission("accessUserDefinedAttributes")or itscheckWritemethod 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 existSecurityException- In the case of the default provider, a security manager is installed, and it deniesRuntimePermission("accessUserDefinedAttributes")or itscheckWritemethod denies write access to the file.
-
-