Интерфейс ModuleFinder

Optional<ModuleReference> find(String name)

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

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

Set<ModuleReference> findAll()

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

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

static ModuleFinder ofSystem()

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

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, его значение является допустимым именем класса, и его пакет входит в набор пакетов, полученный для модуля, то это значение — главный класс модуля.

Если 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 базовых поисковиков модулей, будут перенаправлены вызывающему методу результирующего поиска модулей's методам find или findAll.