OpenJDK 27 · java.nio.file.attribute.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.

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[]).

Modifier and Type	Method and Description
public void	delete(String The attribute name name) Deletes a user-defined attribute.
public List<String>	Returns: An unmodifiable list containing the names of the file's user-defined list() Returns a list containing the names of the user-defined attributes.
public String	name() Redeclares java.nio.file.attribute.AttributeView.name. Returns the name of this attribute view.
public int	Returns: The number of bytes read, possibly zero read(String The attribute name name, ByteBuffer The destination buffer dst) Read the value of a user-defined attribute into a buffer.
public int	Returns: The size of the attribute value, in bytes. size(String The attribute name name) Returns the size of the value of a user-defined attribute.
public int	Returns: The number of bytes written, possibly zero write(String The attribute name name, ByteBuffer The buffer containing the attribute value src) Writes the value of a user-defined attribute from a buffer.

Method Detail

delete	back to summary
public void delete(String name) throws IOException Deletes a user-defined attribute. Parameters name:String The attribute name Exceptions IOException: If an I/O error occurs or the attribute does not exist

delete

back to summary

public void delete(String name) throws IOException

Deletes a user-defined attribute.

Parameters

name:String: The attribute name

Exceptions

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

list	back to summary
public List<String> list() throws IOException Returns a list containing the names of the user-defined attributes. Returns:List<String> An unmodifiable list containing the names of the file's user-defined Exceptions IOException: If an I/O error occurs

list

back to summary

public List<String> list() throws IOException

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

Returns:List<String>

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

Exceptions

IOException:: If an I/O error occurs

name back to summary

name	back to summary
public String name() Redeclares java.nio.file.attribute.AttributeView.name. Returns the name of this attribute view. Attribute views of this type have the name `"user"`. Annotations @Override

public String name()

Redeclares java.nio.file.attribute.AttributeView.name.

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

Annotations

@Override

read back to summary

read	back to summary
public 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`, where `n` is the size of the attribute value. The first byte in the sequence is at index `p` and the last byte is at index `p + n - 1`, where `p` is the buffer's position. Upon return the buffer's position will be equal to `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 "`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();` 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:String The attribute name dst:ByteBuffer The destination buffer Returns:int The number of bytes read, possibly zero Exceptions IOException: If an I/O error occurs or there is insufficient space in the destination buffer for the attribute value IllegalArgumentException: If the destination buffer is read-only See Also `size`

public 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, where n is the size of the attribute value. The first byte in the sequence is at index p and the last byte is at index p + n - 1, where p is the buffer's position. Upon return the buffer's position will be equal to 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 "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:String: The attribute name
dst:ByteBuffer: The destination buffer

Returns:int

The number of bytes read, possibly zero

Exceptions

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

See Also

size

size back to summary

size	back to summary
public int size(String name) throws IOException Returns the size of the value of a user-defined attribute. Parameters name:String The attribute name Returns:int The size of the attribute value, in bytes. Exceptions IOException: If an I/O error occurs ArithmeticException: If the size of the attribute is larger than `Integer#MAX_VALUE`

public int size(String name) throws IOException

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

Parameters

name:String: The attribute name

Returns:int

The size of the attribute value, in bytes.

Exceptions

IOException:: If an I/O error occurs
ArithmeticException:: If the size of the attribute is larger than Integer#MAX_VALUE

write back to summary

write	back to summary
public 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`, where `r` is the number of bytes remaining in the buffer, that is `src.remaining()`. The sequence of bytes is transferred from the buffer starting at index `p`, where `p` is the buffer's position. Upon return, the buffer's position will be equal to `p + n`, where `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. It is 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 `IOException` is 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"));` UserDefinedFileAttributeView view = Files.getFileAttributeView(path, UserDefinedFileAttributeView.class); view.write("user.mimetype", Charset.defaultCharset().encode("text/html")); Parameters name:String The attribute name src:ByteBuffer The buffer containing the attribute value Returns:int The number of bytes written, possibly zero Exceptions IOException: If an I/O error occurs

public 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, where r is the number of bytes remaining in the buffer, that is src.remaining(). The sequence of bytes is transferred from the buffer starting at index p, where p is the buffer's position. Upon return, the buffer's position will be equal to p + n, where 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. It is 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 IOException is 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:String: The attribute name
src:ByteBuffer: The buffer containing the attribute value

Returns:int

The number of bytes written, possibly zero

Exceptions

IOException:: If an I/O error occurs

public Interface UserDefinedFileAttributeView

Method Summary

Method Detail