Интерфейс ModuleReader

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

public interface ModuleReader extends Closeable

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

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

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

ModuleReader открывается при создании и закрывается вызовом метода 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://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/module/ModuleReader.html