Интерфейс 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, то ресурс следует рассматривать как "не найден" для избежания несоответствий.

С версии:

См. также:

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

Модификатор и тип	Метод	Описание
`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 - Если доступ запрещен менеджером безопасности

См. также:

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, максимальный размер буфера байтов

См. также:

release

default void release(ByteBuffer bb)

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

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

list

Stream<String> list() throws IOException

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

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

Возвращаемый поток может содержать ссылки на один или несколько открытых каталогов в модуле. Каталоги будут закрыты при закрытии потока.

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

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

close

void close() throws IOException

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

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

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

© 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/lang/module/ModuleReader.html