Интерфейс ModuleReader

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

public interface ModuleReader extends Closeable

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

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

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

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

Требования к реализации:

Реализации 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 - Если произошла ошибка ввода-вывода или чтец модуля закрыт

См. также:

open

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

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

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

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

read

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

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

Примечание API:

Этот метод предназначен для высокопроизводительной загрузки классов. Он не способен (и не предназначен) для чтения произвольно больших ресурсов, которые потенциально могут быть 2 ГБ или больше. Причина использования этого метода в сочетании с методом release - позволить реализациям читателя модулей управлять буферами эффективным способом.

Требования к реализации:

Реализация по умолчанию вызывает метод open и считывает все байты из потока ввода в буфер байтов.

Параметры:

name - Имя ресурса для чтения

Возвращает:

Буфер байтов, содержащий содержимое ресурса, или пустой Optional, если не найден

ИСКЛЮЧЕНИЕ:

IOException - Если произошла ошибка ввода-вывода или чтец модуля закрыт

OutOfMemoryError - Если ресурс больше, чем Integer.MAX_VALUE, максимальная ёмкость буфера байтов

См. также:

release

default void release(ByteBuffer bb)

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

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

list

Stream<String> list() throws IOException

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

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

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

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

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

close

void close() throws IOException

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

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

Определено в:: close в интерфейсе AutoCloseable
Определено в:: close в интерфейсе Closeable
ИСКЛЮЧЕНИЕ:: IOException - если произошла ошибка ввода-вывода

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/lang/module/ModuleReader.html