Интерфейс ModuleFinder

Optional<ModuleReference> find(String name)

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

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

Set<ModuleReference> findAll()

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

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-файлов, реализация может также поддерживать модули, упакованные в другие, специфичные для реализации форматы модулей. Если элемент массива, переданного этому методу, является путём к каталогу модулей, записи в каталоге, не распознанные как модули, игнорируются. Если элемент массива является путём к нераспознанному упакованному модулю, при обращении к файлу выбрасывается FindException. Пути к несуществующим файлам всегда игнорируются.

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

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

static ModuleFinder compose(ModuleFinder... finders)

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

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