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

С:

См. также:

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 - если произошла ошибка ввода-вывода

© 1993, 2021, 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/17/docs/api/java.base/java/lang/module/ModuleReader.html