Класс ModuleLayer

java.lang.Object

java.lang.ModuleLayer

public final class ModuleLayer extends Object

Слой модулей в виртуальной машине Java.

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

При создании слоя для каждого ResolvedModule в конфигурации создаётся объект Module. Для каждого разрешённого модуля, который read, Module reads соответствующий модуль времени выполнения Module, который может находиться в том же слое или в parent слое.

Методы defineModulesWithOneLoader и defineModulesWithManyLoaders предоставляют удобные способы создания слоя модулей, в котором все модули сопоставлены одному загрузчику классов или каждый модуль сопоставлен собственному загрузчику классов. Метод defineModules предназначен для более сложных случаев, когда модули сопоставляются пользовательским загрузчикам классов с помощью переданной методу функции. У каждого из этих методов есть экземплярный и статический варианты. Экземплярные методы создают слой, у которого принимающий объект является родительским слоем. Статические методы предназначены для более сложных случаев, когда родительских слоёв может быть несколько или когда для управления модулями в слое требуется Controller.

Виртуальная машина Java содержит как минимум один непустой слой — слой boot, который создаётся при запуске виртуальной машины Java. Загрузочный слой содержит модуль java.base и является единственным слоем в виртуальной машине Java с модулем под названием «java.base». Модули загрузочного слоя сопоставлены загрузчику классов начальной загрузки и другим загрузчикам классов, встроенным в виртуальную машину Java. При создании дополнительных слоёв загрузочный слой часто будет parent.

Каждый Module в слое создаётся так, чтобы он exports и opens пакеты, описанные в его ModuleDescriptor. Квалифицированные экспорты (когда пакет экспортируется набору целевых модулей, а не всем модулям) материализуются при создании слоя следующим образом:

Если модуль X экспортирует пакет в Y, и модуль времени выполнения Module X читает Module Y, то пакет экспортируется в Module Y (который может находиться в том же слое, что и X, или в родительском слое).
Если модуль X экспортирует пакет в Y, а модуль времени выполнения Module X не читает Y, целевой модуль Y ищется так, как если бы для поиска модуля в этом слое или его родительских слоях был вызван метод findModule. Если Y найден, пакет экспортируется экземпляру Y, который был найден. Если Y не найден, квалифицированный экспорт игнорируется.

Квалифицированные открытия обрабатываются так же, как квалифицированные экспорты.

Как и при создании Configuration, при создании слоя к automatic модулям применяется особый подход. Автоматический модуль создаётся в виртуальной машине Java как Module, который читает каждый безымянный Module в виртуальной машине Java.

Если не указано иное, передача аргумента null методу этого класса приводит к выбрасыванию исключения NullPointerException.

Пример

В этом примере создаётся конфигурация путём разрешения модуля с именем «myapp» с конфигурацией загрузочного слоя в качестве родительской. Затем создаётся новый слой с модулями из этой конфигурации. Все модули определяются одним и тем же загрузчиком классов.

    ModuleFinder finder = ModuleFinder.of(dir1, dir2, dir3);
    ModuleLayer parent = ModuleLayer.boot();
    Configuration cf = parent.configuration()
                             .resolve(finder, ModuleFinder.of(), Set.of("myapp"));
    ClassLoader scl = ClassLoader.getSystemClassLoader();
    ModuleLayer layer = parent.defineModulesWithOneLoader(cf, scl);
    Class<?> c = layer.findLoader("myapp").loadClass("app.Main");

Начиная с версии:

См. также:

Краткое описание вложенных классов

Модификатор и тип	Класс	Описание
`static final class`	`ModuleLayer.Controller`	Управляет слоем модулей.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static ModuleLayer`	`boot()`	Возвращает загрузочный слой.
`Configuration`	`configuration()`	Возвращает конфигурацию этого слоя.
`ModuleLayer`	`defineModules(Configuration cf, Function<String, ClassLoader> clf)`	Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной `Configuration`.
`static ModuleLayer.Controller`	`defineModules(Configuration cf, List<ModuleLayer> parentLayers, Function<String, ClassLoader> clf)`	Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной `Configuration`.
`ModuleLayer`	`defineModulesWithManyLoaders(Configuration cf, ClassLoader parentLoader)`	Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной `Configuration`.
`static ModuleLayer.Controller`	`defineModulesWithManyLoaders(Configuration cf, List<ModuleLayer> parentLayers, ClassLoader parentLoader)`	Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной `Configuration`.
`ModuleLayer`	`defineModulesWithOneLoader(Configuration cf, ClassLoader parentLoader)`	Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной `Configuration`.
`static ModuleLayer.Controller`	`defineModulesWithOneLoader(Configuration cf, List<ModuleLayer> parentLayers, ClassLoader parentLoader)`	Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной `Configuration`.
`static ModuleLayer`	`empty()`	Возвращает пустой слой.
`ClassLoader`	`findLoader(String name)`	Возвращает `ClassLoader` для модуля с указанным именем.
`Optional<Module>`	`findModule(String name)`	Возвращает модуль с указанным именем из этого слоя или, если его нет в этом слое, из родительских слоёв.
`Set<Module>`	`modules()`	Возвращает неизменяемое множество модулей этого слоя.
`List<ModuleLayer>`	`parents()`	Возвращает неизменяемый список родительских слоёв в порядке поиска.
`String`	`toString()`	Возвращает строку с описанием этого слоя модулей.

Методы, объявленные в классе Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создаёт и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли другой объект этому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API может быть удалён в будущей версии. Финализация устарела и может быть удалена в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Переводит текущий поток в состояние ожидания до пробуждения, обычно вследствие уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Переводит текущий поток в состояние ожидания до пробуждения, обычно вследствие уведомления или прерывания, либо до истечения определённого промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Переводит текущий поток в состояние ожидания до пробуждения, обычно вследствие уведомления или прерывания, либо до истечения определённого промежутка реального времени.

Подробное описание методов

defineModulesWithOneLoader

public ModuleLayer defineModulesWithOneLoader(Configuration cf, ClassLoader parentLoader)

Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной Configuration. Этот метод создаёт один загрузчик классов и определяет все модули в этом загрузчике классов. parent каждого загрузчика классов — это указанный родительский загрузчик классов. Этот метод работает в точности так, как описано для статического метода defineModulesWithOneLoader, если вызвать его, указав этот слой в качестве родительского. Иными словами, если этот слой — thisLayer, данный метод эквивалентен вызову:

    ModuleLayer.defineModulesWithOneLoader(cf, List.of(thisLayer), parentLoader).layer();

Параметры:

cf — конфигурация слоя

parentLoader — родительский загрузчик классов для загрузчика классов, создаваемого этим методом; для загрузчика классов начальной загрузки может быть null

Возвращает:

Созданный слой

Выбрасывает:

IllegalArgumentException — если указанная конфигурация имеет более одного родителя или родитель конфигурации не является конфигурацией этого слоя

LayerInstantiationException — если слой не удаётся создать по какой-либо из причин, указанных для статического метода defineModulesWithOneLoader

См. также:

defineModulesWithManyLoaders

public ModuleLayer defineModulesWithManyLoaders(Configuration cf, ClassLoader parentLoader)

Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной Configuration. Каждый модуль определяется в собственном ClassLoader, созданном этим методом. parent каждого загрузчика классов — это указанный родительский загрузчик классов. Этот метод работает в точности так, как описано для статического метода defineModulesWithManyLoaders, если вызвать его, указав этот слой в качестве родительского. Иными словами, если этот слой — thisLayer, данный метод эквивалентен вызову:

    ModuleLayer.defineModulesWithManyLoaders(cf, List.of(thisLayer), parentLoader).layer();

Параметры:

cf — конфигурация слоя

parentLoader — родительский загрузчик классов для каждого загрузчика классов, создаваемого этим методом; для загрузчика классов начальной загрузки может быть null

Возвращает:

Созданный слой

Выбрасывает:

LayerInstantiationException — если слой не удаётся создать по какой-либо из причин, указанных для статического метода defineModulesWithManyLoaders

См. также:

defineModules

public ModuleLayer defineModules(Configuration cf, Function<String, ClassLoader> clf)

Создаёт новый слой модулей, используя этот слой в качестве родительского, и определяет в виртуальной машине Java модули из указанной Configuration. Каждый модуль сопоставляется своему загрузчику классов по имени с помощью указанной функции. Этот метод работает в точности так, как описано для статического метода defineModules, если вызвать его, указав этот слой в качестве родительского. Иными словами, если этот слой — thisLayer, данный метод эквивалентен вызову:

    ModuleLayer.defineModules(cf, List.of(thisLayer), clf).layer();

Параметры:: cf — конфигурация слоя; clf — функция для сопоставления имени модуля загрузчику классов
Возвращает:: Созданный слой
Выбрасывает:: IllegalArgumentException — если указанная конфигурация имеет более одного родителя или родитель конфигурации не является конфигурацией этого слоя; LayerInstantiationException — если слой не удаётся создать по какой-либо из причин, указанных для статического метода defineModules

defineModulesWithOneLoader

public static ModuleLayer.Controller defineModulesWithOneLoader(Configuration cf, List<ModuleLayer> parentLayers, ClassLoader parentLoader)

Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной


Configuration

. Этот метод создаёт один загрузчик классов и определяет все модули в этом загрузчике классов.

Созданный этим методом загрузчик классов использует прямое делегирование при загрузке классов из модулей. При вызове метода loadClass для загрузки класса имя пакета класса используется для сопоставления его модулю. Это может быть модуль в этом слое, а значит, он определён в том же загрузчике классов. Это также может быть пакет в модуле родительского слоя, экспортируемый одному или нескольким модулям этого слоя. Загрузчик классов делегирует загрузку загрузчику классов модуля и выбрасывает ClassNotFoundException, если этот загрузчик классов не находит класс. При вызове loadClass для загрузки классов, не сопоставленных модулю, загрузка делегируется родительскому загрузчику классов.

Созданный этим методом загрузчик классов ищет ресурсы (getResource, getResources и другие методы работы с ресурсами) во всех модулях слоя, прежде чем искать их в родительском загрузчике классов.

Создание слоя, в котором все модули определены в одном загрузчике классов, может завершиться неудачей по следующим причинам:

Пересекающиеся пакеты: два или более модуля в конфигурации содержат один и тот же пакет.
Разделённое делегирование: для загрузки классов из определённого пакета полученному загрузчику классов потребуется делегировать загрузку более чем одному загрузчику классов.

Кроме того, слой нельзя создать, если конфигурация содержит модуль с именем «java.base», модуль содержит пакет с именем «java» или пакет, имя которого начинается с «java.».

Параметры:

cf — конфигурация слоя

parentLayers — список родительских слоёв в порядке поиска

Возвращает:

Контроллер, управляющий созданным слоем

Выбрасывает:

IllegalArgumentException — если родительские конфигурации указанной конфигурации не соответствуют конфигурациям родительских слоёв, включая порядок

LayerInstantiationException — если невозможно определить все модули в одном загрузчике классов по любой из перечисленных выше причин

См. также:

defineModulesWithManyLoaders

public static ModuleLayer.Controller defineModulesWithManyLoaders(Configuration cf, List<ModuleLayer> parentLayers, ClassLoader parentLoader)

Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной


Configuration

. Каждый модуль определяется в собственном ClassLoader, созданном этим методом. parent каждого загрузчика классов — это указанный родительский загрузчик классов.

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

Созданные этим методом загрузчики классов ищут ресурсы (getResource, getResources и другие методы работы с ресурсами) в модуле, определённом в соответствующем загрузчике классов, прежде чем искать их в родительском загрузчике классов.

Параметры:

cf — конфигурация слоя

parentLayers — список родительских слоёв в порядке поиска

Возвращает:

Контроллер, управляющий созданным слоем

Выбрасывает:

LayerInstantiationException — если слой не удаётся создать, поскольку конфигурация содержит модуль с именем «java.base», модуль содержит пакет с именем «java» или пакет, имя которого начинается с «java.»

См. также:

defineModules

public static ModuleLayer.Controller defineModules(Configuration cf, List<ModuleLayer> parentLayers, Function<String, ClassLoader> clf)

Создаёт новый слой модулей и определяет в виртуальной машине Java модули из указанной


Configuration

. Указанная функция сопоставляет каждый модуль конфигурации с загрузчиком классов по имени. Создание слоя сообщает виртуальной машине Java о классах, которые могут загружаться, чтобы виртуальная машина Java знала, членом какого модуля является каждый класс.

Делегирование между загрузчиками классов должно учитывать читаемость модулей. Во избежание взаимоблокировок при загрузке классов загрузчики классов должны быть parallel-capable. Кроме того, субъект, создающий этим методом новый слой, должен обеспечить готовность загрузчиков классов загружать классы из этих модулей до первой попытки загрузки классов или ресурсов.

Создание слоя может завершиться неудачей по следующим причинам:

Два или более модуля с одним и тем же пакетом сопоставлены одному загрузчику классов.
Модуль сопоставлен загрузчику классов, в котором уже определён модуль с таким же именем.
Модуль сопоставлен загрузчику классов, который уже определил типы в одном из пакетов этого модуля.

Кроме того, слой нельзя создать, если конфигурация содержит модуль с именем «java.base», конфигурация содержит модуль с пакетом с именем «java» или именем, начинающимся с «java.», либо функция сопоставления имени модуля загрузчику классов возвращает null или загрузчик классов платформы.

Если функция сопоставления имени модуля загрузчику классов выбрасывает ошибку или исключение времени выполнения, оно передаётся вызывающему этого метода.

Примечание к API:: Зависит от реализации, является ли создание слоя этим методом атомарной операцией. Следовательно, метод может завершиться неудачей, хотя некоторые модули, но не все, уже будут определены в виртуальной машине Java.
Параметры:: cf — конфигурация слоя; parentLayers — список родительских слоёв в порядке поиска; clf — функция для сопоставления имени модуля загрузчику классов
Возвращает:: Контроллер, управляющий созданным слоем
Выбрасывает:: IllegalArgumentException — если родительские конфигурации указанной конфигурации не соответствуют конфигурациям родительских слоёв, включая порядок; LayerInstantiationException — если создание слоя завершается неудачей по любой из перечисленных выше причин

configuration

public Configuration configuration()

Возвращает конфигурацию этого слоя.

Возвращает:: Конфигурацию этого слоя

parents

public List<ModuleLayer> parents()

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

Возвращает:: Возможно, пустой неизменяемый список родительских слоёв

modules

public Set<Module> modules()

Возвращает неизменяемое множество модулей этого слоя.

Возвращает:: Возможно, пустое неизменяемое множество модулей этого слоя

findModule

public Optional<Module> findModule(String name)

Возвращает модуль с указанным именем из этого слоя или, если его здесь нет, из родительских слоёв. Поиск модуля в родительских слоях эквивалентен вызову findModule для каждого родительского слоя в порядке поиска до тех пор, пока модуль не будет найден или не будут проверены все родители. Для дерева слоёв это эквивалентно поиску в глубину.

Параметры:: name — имя искомого модуля
Возвращает:: Модуль с указанным именем или пустой Optional, если модуль с таким именем отсутствует в этом слое и во всех родительских слоях

findLoader

public ClassLoader findLoader(String name)

Возвращает ClassLoader для модуля с указанным именем. Если модуль с указанным именем отсутствует в этом слое, выполняется поиск в parent слоях способом, описанным в findModule.

Примечание к API:: Этот метод не возвращает Optional<ClassLoader>, поскольку для представления загрузчика классов начальной загрузки необходимо использовать `null`.
Параметры:: name — имя искомого модуля
Возвращает:: ClassLoader, в котором определён модуль
Выбрасывает:: IllegalArgumentException — если модуль с указанным именем не определён ни в этом слое, ни в одном из его родительских слоёв

toString

public String toString()

Возвращает строку с описанием этого слоя модулей.

Переопределяет:: toString в классе Object
Возвращает:: Возможно, пустую строку с описанием этого слоя модулей

empty

public static ModuleLayer empty()

Возвращает пустой слой. В пустом слое нет модулей. У него нет родительских слоёв.

Возвращает:: Пустой слой

boot

public static ModuleLayer boot()

Возвращает загрузочный слой. Загрузочный слой содержит как минимум один модуль — java.base. Его родитель — слой empty.

Примечание к API:: Во время запуска и до полной инициализации загрузочного слоя этот метод возвращает null.
Возвращает:: Загрузочный слой

© 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.