Интерфейс ModuleReader

Все суперинтерфейсы:: AutoCloseable, Closeable

public interface ModuleReader
extends Closeable

Обеспечивает доступ к содержимому модуля.

Читатель модуля предназначен для случаев, когда требуется доступ к ресурсам в модуле, независимо от того, загружен ли модуль. Например, фреймворк, который сканирует коллекцию упакованных модулей в файловой системе, может использовать читатель модуля для доступа к определенному ресурсу в каждом модуле. Читатель модуля также предназначен для использования реализациями ClassLoader для загрузки классов и ресурсов из модулей.

Ресурс в модуле идентифицируется абстрактным именем, которое представляет собой строку пути, разделенную через '/'. Например, модуль java.base может иметь ресурс "java/lang/Object.class", который по соглашению является файлом класса для java.lang.Object. Читатель модуля может рассматривать каталоги в содержимом модуля как ресурсы (делает он это или нет, зависит от конкретного читателя модуля). Если содержимое модуля содержит каталог, который может быть найден как ресурс, то его имя заканчивается слешем ('/'). Каталог также можно найти по имени без конечного слеша.

Читатель модуля открыт при создании и закрывается путем вызова метода close. Отсутствие закрытия читателя модуля может привести к утечке ресурсов. Оператор try-with-resources предоставляет полезную конструкцию для обеспечения закрытия читателей модулей.

Реализация ModuleReader может потребовать разрешений для доступа к ресурсам в модуле. Поэтому методы find, open, read и list могут выбросить SecurityException если доступ запрещен менеджером безопасности.

Требования к реализации:: Реализации ModuleReader должны проявлять особую осторожность при переводе абстрактного имени ресурса в местоположение ресурса в упакованном модуле или в файловой системе. Реализации рекомендуется рассматривать имена ресурсов с элементами, такими как '., '..', элементами, содержащими разделители файлов, или пустыми элементами, как "не найдены". Более общим правилом является то, что если имя ресурса отсутствует в потоке элементов, которые возвращает метод list, то ресурс должен рассматриваться как "не найден", чтобы избежать несоответствий.
С версии:: 9
См. также:: ModuleReference

Методы

Модификатор и тип	Метод	Описание
`void`	`close()`	Закрывает читатель модуля.
`Optional<URI>`	`find(String name)`	Находит ресурс, возвращая URI ресурса в модуле.
`Stream<String>`	`list()`	Выводит содержимое модуля, возвращая поток элементов, которые являются именами всех ресурсов в модуле.
`default Optional<InputStream>`	`open(String name)`	Открывает ресурс, возвращая поток ввода для чтения ресурса в модуле.
`default Optional<ByteBuffer>`	`read(String name)`	Читает ресурс, возвращая буфер байтов с содержимым ресурса.
`default void`	`release(ByteBuffer bb)`	Освобождает буфер байтов.

Методы

find

Optional<URI> find(String name)
            throws IOException

Находит ресурс, возвращая URI ресурса в модуле.

Если читатель модуля может определить, что имя указывает на каталог, то результирующий URI будет заканчиваться слешем ('/').

Параметры:: name - Имя ресурса для открытия для чтения
Возвращает:: URI ресурса; пустой Optional если ресурс не найден или URI не может быть построен для поиска ресурса
Исключение:: IOException - Если произошла ошибка ввода-вывода или читатель модуля закрыт; SecurityException - Если доступ запрещен менеджером безопасности
См. также:: ClassLoader.getResource(String)

open

default Optional<InputStream> open(String name)
                            throws IOException

Открывает ресурс, возвращая поток ввода для чтения ресурса в модуле.

Поведение потока ввода при использовании после закрытия читателя модуля зависит от реализации и поэтому не указано.

Требования к реализации:: Умолчанная реализация вызывает метод find для получения URI ресурса. Если найден, то пытается построить URL и открыть соединение с ресурсом.
Параметры:: name - Имя ресурса для открытия для чтения
Возвращает:: Поток ввода для чтения ресурса или пустой Optional если не найден
Исключение:: IOException - Если произошла ошибка ввода-вывода или читатель модуля закрыт; SecurityException - Если доступ запрещен менеджером безопасности

read

default Optional<ByteBuffer> read(String name)
                           throws IOException

Читает ресурс, возвращая буфер байтов с содержимым ресурса. Элемент в возвращенном буфере в позиции является первым байтом ресурса, элемент в границе буфера - последним байтом ресурса. После использования, необходимо вызвать метод release. Отсутствие вызова метода release может привести к утечке ресурсов.

Примечание API:: Этот метод предназначен для высокопроизводительной загрузки классов. Он не может (и не предназначен) для чтения произвольно больших ресурсов, которые потенциально могут быть 2 ГБ или больше. Причина использования этого метода в сочетании с методом release заключается в том, чтобы позволить реализациям читателя модулей управлять буферами эффективным способом.
Требования к реализации:: Умолчанная реализация вызывает метод open и считывает все байты из потока ввода в буфер байтов.
Параметры:: name - Имя ресурса для чтения
Возвращает:: Буфер байтов, содержащий содержимое ресурса, или пустой Optional если не найден
Исключение:: IOException - Если произошла ошибка ввода-вывода или читатель модуля закрыт; SecurityException - Если доступ запрещен менеджером безопасности; OutOfMemoryError - Если ресурс больше, чем Integer.MAX_VALUE, максимальная емкость буфера байтов
См. также:: ClassLoader.defineClass(String, ByteBuffer, java.security.ProtectionDomain)

release

default void release(ByteBuffer bb)

Освобождает буфер байтов. Этот метод следует вызывать после использования содержимого буфера, возвращенного методом read. Поведение этого метода при вызове для освобождения уже освобожденного буфера или при вызове для освобождения буфера после закрытия ModuleReader зависит от реализации и поэтому не указано.

Требования к реализации:: Умолчанная реализация ничего не делает, кроме проверки на null буфера байтов.
Параметры:: bb - Буфер байтов для освобождения

list

Stream<String> list()
             throws IOException

Выводит содержимое модуля, возвращая поток элементов, которые являются именами всех ресурсов в модуле. Включает ли поток элементов имена, соответствующие каталогам в модуле, зависит от читателя модуля.

В ленивых реализациях может быть выброшено исключение IOException при использовании потока для вывода содержимого модуля. В этом случае исключение IOException будет обернуто в UncheckedIOException и выброшено из метода, вызвавшего попытку доступа. SecurityException также может быть выброшено при использовании потока для вывода содержимого модуля, если доступ запрещен менеджером безопасности.

Поведение потока при использовании после закрытия читателя модуля зависит от реализации и поэтому не указано.

Возвращает:: Поток элементов, которые являются именами всех ресурсов в модуле
Исключение:: IOException - Если произошла ошибка ввода-вывода или читатель модуля закрыт; SecurityException - Если доступ запрещен менеджером безопасности

close

void close()
    throws IOException

Закрывает читатель модуля. После закрытия последующие попытки найти или прочитать ресурс завершатся ошибкой, выбросив IOException.

Читатель модуля не обязан быть асинхронно закрываемым. Если один поток читает ресурс, а другой поток вызывает метод close, то второй поток может заблокироваться до завершения операции чтения.

Определено в:: close в интерфейсе AutoCloseable
Определено в:: close в интерфейсе Closeable
Исключение:: IOException - если произошла ошибка ввода-вывода