Интерфейс ModuleFinder

Optional<ModuleReference> find(String name)

Находит ссылку на модуль с заданным именем.

Объект ModuleFinder предоставляет согласованный вид модулей, которые он находит. Если find вызывается несколько раз для поиска одного и того же модуля (по имени), то каждый раз будет возвращаться тот же результат. Если модуль найден, то гарантируется, что он является членом набора модулей, возвращаемых методом findAll.

Set<ModuleReference> findAll()

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

Объект ModuleFinder предоставляет согласованный вид модулей, которые он находит. Если findAll вызывается несколько раз, то каждый раз будет возвращён тот же (равный) результат. Для каждого элемента ModuleReference в возвращённом наборе гарантируется, что find найдёт ModuleReference при вызове для поиска этого модуля.

static ModuleFinder ofSystem()

Возвращает поиск модулей, который находит системные модули. Системные модули — это модули в образе среды выполнения Java. Поиск модулей всегда найдёт java.base.

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

static ModuleFinder of(Path... entries)

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

1. Путь к каталогу модулей.

2. Путь к главному каталогу расширенного модуля.

3. Путь к упакованному модулю.

Поиск модулей выполняется путём последовательного поиска каждого каталога, расширенного модуля или упакованного модуля в порядке индексов массива. Он находит первое вхождение модуля с заданным именем и игнорирует другие модули с тем же именем, которые встречаются позже в последовательности.

Если элемент представляет собой путь к каталогу модулей, то каждая запись в каталоге — это упакованный модуль или главный каталог расширенного модуля. Ошибка, если каталог содержит более одного модуля с тем же именем. Если элемент является путём к каталогу, и этот каталог содержит файл с именем module-info.class, то каталог обрабатывается как расширенный модуль, а не каталог модулей.

Поиск модулей, возвращаемый этим методом, поддерживает модули, упакованные в файлы JAR. Файл JAR с module-info.class в его главном каталоге или в версиированной записи в файле JAR с многократной версией является модульным файлом JAR и, таким образом, определяет явный модуль. Файл JAR, не имеющий module-info.class в своём главном каталоге, определяет автоматический модуль, как следует:

• Если файл JAR содержит атрибут "Automatic-Module-Name" в его главном манифесте, то его значение является именем модуля. В противном случае имя модуля определяется из имени файла JAR.

• version, и имя модуля, когда атрибут "Automatic-Module-Name" отсутствует, определяются из имени файла JAR следующим образом:

  • Удаляется суффикс ".jar".

  • Если имя соответствует регулярному выражению "-(\\d+(\\.|$))", то имя модуля определяется из подпоследовательности, предшествующей дефису первого вхождения. Подпоследовательность после дефиса анализируется как Version и игнорируется, если её нельзя проанализировать как Version.

  • Все неалфавитно-цифровые символы ([^A-Za-z0-9]) в имени модуля заменяются точкой ("."), все повторяющиеся точки заменяются одной точкой, а все начальные и конечные точки удаляются.

  • В качестве примера, файл JAR с именем "foo-bar.jar" получит имя модуля "foo.bar" и версию. Файл JAR с именем "foo-bar-1.2.3-SNAPSHOT.jar" получит имя модуля "foo.bar" и версию "1.2.3-SNAPSHOT".

• Набор пакетов в модуле получается из записей в файле JAR, не являющихся каталогами, и заканчивающихся на ".class". Имя кандидата в пакет определяется из имени с использованием символов до, но не включая, последний слэш. Все оставшиеся слэши заменяются точкой ("."). Если полученная строка является допустимым именем пакета, то она рассматривается как имя пакета. Например, если файл JAR содержит запись "p/q/Foo.class", то полученное имя пакета — "p.q".

• Содержимое записей, начинающихся с META-INF/services/, предполагается файлами конфигурации сервисов (см. ServiceLoader). Если имя файла (после META-INF/services/) является допустимым именем класса, то предполагается, что это полное имя класса типа сервиса. Записи в файле предполагаются полными именами классов провайдеров.

• Если в главном манифесте файла JAR есть атрибут "Main-Class", его значение является допустимым именем класса, и его пакет содержится в наборе пакетов, полученных для модуля, то это значение — основной класс модуля main class.

Если для автоматического модуля нельзя создать ModuleDescriptor (с помощью API ModuleDescriptor.Builder), то бросается исключение FindException. Это может произойти, когда значение атрибута "Automatic-Module-Name" не является допустимым именем модуля, допустимое имя модуля не может быть получено из имени файла JAR, где файл JAR содержит .class в главном каталоге файла JAR, где запись в файле конфигурации сервиса не является допустимым именем класса или имя пакета не входит в набор пакетов, полученных для модуля.

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

Пути к файлам, которые не существуют, всегда игнорируются.

Так же, как и для автоматических модулей, содержимое упакованного или расширенного модуля может потребовать сканирования для определения пакетов в модуле. Игнорируются или нет скрытые файлы hidden files зависит от реализации и не указано.

Если в главном каталоге найден файл .class (кроме module-info.class ), то он предполагается классом в безымянном пакете, и поэтому бросается исключение FindException.

Поиски, созданные этим методом, ленивые и не проверяют заранее, являются ли заданные пути к файлам каталогами или упакованными модулями. Следовательно, методы find или findAll будут завершаться ошибкой только в случае поиска в каталоге или упакованном модуле, и при этом возникнет ошибка.

static ModuleFinder compose(ModuleFinder... finders)

Возвращает поиск модулей, составленный из последовательности нуля или более поисков модулей. Метод find результирующего поиска модулей найдёт модуль, вызвав метод find каждого поиска модулей в порядке индексов массива, пока модуль не будет найден или все поиски модулей не будут перебраны. Метод findAll результирующего поиска модулей вернёт набор модулей, включающий все модули, найденные первым поиском модулей. Набор модулей будет включать все модули, найденные вторым и последующими поисками модулей, которые не были найдены предыдущими поисками модулей в последовательности.

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