Spec-Zone.ru › OpenJDK 21

Интерфейс 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

Краткое описание методов

Модификатор и тип Метод Описание
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)
Записывает значение пользовательского атрибута из буфера.

Подробное описание методов

name

String name()
Возвращает имя этого вида атрибутов. Виды атрибутов этого типа имеют имя "user".
Указано в:
name в интерфейсе AttributeView
Возвращает:
имя вида атрибутов

list

List<String> list() throws IOException
Возвращает список, содержащий имена пользовательских атрибутов.
Возвращает:
Неизменяемый список, содержащий имена пользовательских атрибутов файла
Исключения:
IOException - Если произошла ошибка ввода/вывода
SecurityException - В случае с поставщиком по умолчанию, установлена система безопасности, и она запрещает RuntimePermission("accessUserDefinedAttributes") или его метод checkRead запрещает чтение файла.

size

int size(String name) throws IOException
Возвращает размер значения пользовательского атрибута.
Параметры:
name - Имя атрибута
Возвращает:
Размер значения атрибута в байтах.
Исключения:
ArithmeticException - Если размер атрибута больше, чем Integer.MAX_VALUE
IOException - Если произошла ошибка ввода/вывода
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 - Если произошла ошибка ввода/вывода или в буфере назначения недостаточно места для значения атрибута
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 - Если произошла ошибка ввода/вывода
SecurityException - В случае с поставщиком по умолчанию, установлена система безопасности, и она запрещает RuntimePermission("accessUserDefinedAttributes") или его метод checkWrite запрещает запись в файл.

delete

void delete(String name) throws IOException
Удаляет пользовательский атрибут.
Параметры:
name - Имя атрибута
Исключения:
IOException - Если произошла ошибка ввода/вывода или атрибут не существует
SecurityException - В случае с поставщиком по умолчанию, установлена система безопасности, и она запрещает RuntimePermission("accessUserDefinedAttributes") или его метод checkWrite запрещает запись в файл.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/nio/file/attribute/UserDefinedFileAttributeView.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API