Класс ModuleLayer

java.lang.Object

java.lang.ModuleLayer

public final class ModuleLayer extends Object

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

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

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

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

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

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

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

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

defineModulesWithOneLoader

public ModuleLayer defineModulesWithOneLoader(Configuration cf, ClassLoader parentLoader)

Создаёт новый модульный слой, с этим слоем в качестве родительского, определяя модули из заданной Configuration для виртуальной машины Java. Этот метод создаёт один загрузчик классов и определяет все модули для этого загрузчика. 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)

Создаёт новый модульный слой, с этим слоем в качестве родительского, определяя модули из заданной Configuration для виртуальной машины Java. Каждый модуль определён для собственного 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)

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

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


 Configuration

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

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

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


 Configuration

для виртуальной машины Java. Каждый модуль определён для собственного 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)

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


 Configuration

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

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

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

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

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

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

API Note:: Реализация определяет, является ли создание слоя с помощью этого метода атомарной операцией или нет. Следовательно, возможно, что этот метод завершится ошибкой с некоторыми модулями, но не со всеми, определёнными для виртуальной машины Java.
Parameters:: cf - Конфигурация для слоя; parentLayers - Список родительских слоёв в порядке поиска; clf - Функция для сопоставления имени модуля с загрузчиком классов
Returns:: Контроллер, управляющий вновь созданным слоем
Throws:: IllegalArgumentException - Если родитель(и) данной конфигурации не соответствуют конфигурации родительских слоёв, включая порядок; LayerInstantiationException - Если создание слоя завершается ошибкой по любой из перечисленных выше причин

configuration

public Configuration configuration()

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

Returns:: Конфигурация для этого слоя

parents

public List<ModuleLayer> parents()

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

Returns:: Возможный пустой неизменяемый список родителей этого слоя

modules

public Set<Module> modules()

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

Returns:: Возможный пустой неизменяемый набор модулей в этом слое

findModule

public Optional<Module> findModule(String name)

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

Parameters:: name - Имя модуля для поиска
Returns:: Модуль с заданным именем или пустой Optional, если в этом слое или любом родительском слое нет модуля с этим именем

findLoader

public ClassLoader findLoader(String name)

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

API Note:: Этот метод не возвращает Optional<ClassLoader>, потому что `null` используется для представления загрузчика классов загрузки.
Parameters:: name - Имя модуля для поиска
Returns:: Загрузчик классов, которому определён модуль
Throws:: IllegalArgumentException - если модуль с заданным именем не определён в этом слое или в любом родителе этого слоя

toString

public String toString()

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

Overrides:: toString in class Object
Returns:: Возможная пустая строка, описывающая этот модульный слой

empty

public static ModuleLayer empty()

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

Returns:: Пустой слой

boot

public static ModuleLayer boot()

Возвращает слой загрузки. Слой загрузки содержит по крайней мере один модуль, java.base. Его родителем является empty слой.

API Note:: Этот метод возвращает null во время запуска и до полного инициализации слоя загрузки.
Returns:: Слой загрузки

© 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.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/lang/ModuleLayer.html