gnodet-bot commented on code in PR #13588: URL: https://github.com/apache/maven/pull/13588#discussion_r4529454889
########## src/site/markdown/classloading.md: ########## @@ -0,0 +1,407 @@ +<!--- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Maven Classloading + +This document describes the classloading mechanism used by Maven 4.x. +Maven uses [maven-classworlds][classworlds] — an internalized fork of +Plexus Classworlds — to build a hierarchy of isolated classloaders +(called **realms**) so that plugins, extensions and the Maven core can +each see only the classes they are supposed to see. + +The following diagram gives an overview of the realm hierarchy during a +typical Maven build. Solid arrows indicate the parent classloader +relationship. Dashed blue arrows indicate package imports. Dashed green +arrows indicate export feeds. + + + +Each realm is described in detail below. + +## ClassWorlds Bootstrap ClassLoader + +This classloader is created and managed by the calling environment: the +JVM launcher, an integration testing harness, or an IDE embedder. + +During a normal command-line invocation this is the JVM System +ClassLoader and contains: + +- `${maven.home}/boot/*.jar` — the classworlds library that bootstraps + all other realms +- Any `-javaagent` classes specified on the JVM command line + +## Maven Core Realm (`plexus.core`) + +Contains all Maven runtime classes: `MavenProject`, `AbstractMojo`, +Plexus/Sisu DI, SLF4J, Guice, the Aether resolver, and more. + +The contents are configured by `${maven.home}/bin/m2.conf` and +typically include: + +- `${maven.home}/lib/ext/*.jar` +- `${maven.home}/lib/*.jar` +- `${maven.home}/lib/modules/*.jar` — loaded as a classpath fallback + when JPMS module layer creation is not available (see below) + +This realm is the **container realm** in the Plexus/Sisu container +unless core extensions are present, in which case the `maven.ext` realm +takes over as the container realm (see below). + +### JPMS Module Layer (`lib/modules/`) + +The `m2.conf` `module` directive instructs maven-classworlds to load +`${maven.home}/lib/modules/*.jar` as a dedicated JPMS `ModuleLayer` +(a child layer of the boot layer) rather than adding them to the +`plexus.core` classpath. This enables module-system features such as +`--enable-native-access` for JLine's terminal support. + +Currently `lib/modules/` contains the JLine JARs. When a module layer +is successfully created, the `load ${maven.home}/lib/modules/*.jar` +entry inside `[plexus.core]` acts as a no-op (the classes are already +visible via the parent module layer). On older JDKs or in embedder +environments where `createModuleLayer()` is not invoked, the same JARs +are picked up from the classpath entry as a transparent fallback. + +## Core Extension Realms (`coreExtension>G:A:V`) + +Core extensions are loaded during Maven startup, **before the POM is +parsed**. Because they load before POM parsing, core extensions can +influence the build itself (e.g. polyglot Maven). Each core extension +gets its own isolated classloader. + +Maven reads `extensions.xml` files from three locations, in precedence +order (project overrides user, user overrides installation): + +| Source | Default path | +|---|---| +| **Project** | `${session.rootDirectory}/.mvn/extensions.xml` | +| **User** | `${user.home}/.m2/extensions.xml` | +| **Installation** | `${maven.home}/conf/extensions.xml` | + +The paths are configurable via the `maven.project.extensions`, +`maven.user.extensions`, and `maven.installation.extensions` properties. + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<extensions> + <extension> + <groupId>...</groupId> + <artifactId>...</artifactId> + <version>...</version> + <!-- optional: parent-first (default), self-first, plugin --> Review Comment: ⚠️ **Wrong default — still not fixed.** The XML comment still says `parent-first` is the default. Per `core-extensions.mdo` (`<defaultValue>self-first</defaultValue>`), `self-first` is the default. ```suggestion <!-- optional: self-first (default), parent-first, plugin --> ``` ########## src/site/markdown/classloading.md: ########## @@ -0,0 +1,407 @@ +<!--- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Maven Classloading + +This document describes the classloading mechanism used by Maven 4.x. +Maven uses [maven-classworlds][classworlds] — an internalized fork of +Plexus Classworlds — to build a hierarchy of isolated classloaders +(called **realms**) so that plugins, extensions and the Maven core can +each see only the classes they are supposed to see. + +The following diagram gives an overview of the realm hierarchy during a +typical Maven build. Solid arrows indicate the parent classloader +relationship. Dashed blue arrows indicate package imports. Dashed green +arrows indicate export feeds. + + + +Each realm is described in detail below. + +## ClassWorlds Bootstrap ClassLoader + +This classloader is created and managed by the calling environment: the +JVM launcher, an integration testing harness, or an IDE embedder. + +During a normal command-line invocation this is the JVM System +ClassLoader and contains: + +- `${maven.home}/boot/*.jar` — the classworlds library that bootstraps + all other realms +- Any `-javaagent` classes specified on the JVM command line + +## Maven Core Realm (`plexus.core`) + +Contains all Maven runtime classes: `MavenProject`, `AbstractMojo`, +Plexus/Sisu DI, SLF4J, Guice, the Aether resolver, and more. + +The contents are configured by `${maven.home}/bin/m2.conf` and +typically include: + +- `${maven.home}/lib/ext/*.jar` +- `${maven.home}/lib/*.jar` +- `${maven.home}/lib/modules/*.jar` — loaded as a classpath fallback + when JPMS module layer creation is not available (see below) + +This realm is the **container realm** in the Plexus/Sisu container +unless core extensions are present, in which case the `maven.ext` realm +takes over as the container realm (see below). + +### JPMS Module Layer (`lib/modules/`) + +The `m2.conf` `module` directive instructs maven-classworlds to load +`${maven.home}/lib/modules/*.jar` as a dedicated JPMS `ModuleLayer` +(a child layer of the boot layer) rather than adding them to the +`plexus.core` classpath. This enables module-system features such as +`--enable-native-access` for JLine's terminal support. + +Currently `lib/modules/` contains the JLine JARs. When a module layer +is successfully created, the `load ${maven.home}/lib/modules/*.jar` +entry inside `[plexus.core]` acts as a no-op (the classes are already +visible via the parent module layer). On older JDKs or in embedder +environments where `createModuleLayer()` is not invoked, the same JARs +are picked up from the classpath entry as a transparent fallback. + +## Core Extension Realms (`coreExtension>G:A:V`) + +Core extensions are loaded during Maven startup, **before the POM is +parsed**. Because they load before POM parsing, core extensions can +influence the build itself (e.g. polyglot Maven). Each core extension +gets its own isolated classloader. + +Maven reads `extensions.xml` files from three locations, in precedence +order (project overrides user, user overrides installation): + +| Source | Default path | +|---|---| +| **Project** | `${session.rootDirectory}/.mvn/extensions.xml` | +| **User** | `${user.home}/.m2/extensions.xml` | +| **Installation** | `${maven.home}/conf/extensions.xml` | + +The paths are configurable via the `maven.project.extensions`, +`maven.user.extensions`, and `maven.installation.extensions` properties. + +```xml +<?xml version="1.0" encoding="UTF-8"?> +<extensions> + <extension> + <groupId>...</groupId> + <artifactId>...</artifactId> + <version>...</version> + <!-- optional: parent-first (default), self-first, plugin --> + <classLoadingStrategy>...</classLoadingStrategy> + </extension> +</extensions> +``` + +Each extension can use `META-INF/maven/extension.xml` to declare +exported packages and artifacts. These exports are aggregated into +`CoreExports` and become visible to all plugins and build extensions +through the Maven API realm. + +The `<classLoadingStrategy>` element controls the realm's parent +wiring: + +| Strategy | Behavior | +|---|---| +| `parent-first` (default) | Imports everything from the core realm. Classes from the core are preferred over the extension's own. | Review Comment: ⚠️ **Wrong default — still not fixed.** The table marks `parent-first` as the default. Per `core-extensions.mdo`, `self-first` is the default and `parent-first` is not. The rows need to reflect this. ```suggestion | `self-first` (default) | Uses the core realm as parent but checks its own classes first. Allows the extension to override core classes. | | `plugin` | Imports only `CoreExports` packages (the Maven API surface). Same isolation as build extensions. | | `parent-first` | Imports everything from the core realm. Classes from the core are preferred over the extension's own. | ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
