Интерфейс 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 запрещает запись в файл.