Fix 1525 classloading docs by BHARGAV-RUE · Pull Request #1594 · apache/maven-site

BHARGAV-RUE · 2026-06-05T16:31:50Z

Summary

This PR consolidates the Maven Classloading documentation by merging the content from the reference page into the guide page as discussed in #1525.

Changes

Merged the content from reference/maven-classloading.md into guide-maven-classloading.md
Moved the classloading diagrams to the shared image resources location
Added PNG versions of the diagrams for use in the guide
Removed the obsolete files:
- reference/maven-classloading.md
- reference/maven-classloading.odg
- reference/maven-classloading.png

Validation

Verified all image references resolve correctly
Reviewed the rendered documentation locally
Confirmed no unrelated files were modified

Fixes #1525

elharo · 2026-08-09T11:39:08Z


 The second classloader down the graph contains the core requirements of Maven. **It is used by Maven internally but not by plugins**. The core classloader has the libraries in `${maven.home}/lib`. In general these are just Maven libraries. For example instances of [`MavenProject`](/ref/current/apidocs/org/apache/maven/project/MavenProject.html) belong to this classloader.

+Contents of this classloader are configured in `${maven.home}/bin/m2.conf` and typically contains `${maven.home}/lib/ext/*.jar` and `${maven.home}/lib/*.jar`.


elharo · 2026-08-09T11:39:42Z


+## Core Extensions
+
+Core Extensions is a mechanism introduced in Maven 3.3.0 which allows additional components to be loaded into Maven Core as part of a build session.


Core Extensions enable additional components to be loaded into Maven Core as part of a build session.

elharo · 2026-08-09T11:40:03Z

+
+Core Extensions is a mechanism introduced in Maven 3.3.0 which allows additional components to be loaded into Maven Core as part of a build session.
+
+Each core extension is loaded in a separate classloader and there is no mechanism to share classes among core extensions. Core extension classloaders use Maven Core classloader as the parent and have access to both exported and internal Maven Core classes.


Each core extension is loaded in a separate classloader. There is no mechanism to share classes among core extensions.

elharo · 2026-08-09T11:40:44Z

-The API classloader is a filtered view of the Core Classloader, done by exposing only the exported packages from all Core Extensions. The main API is listed in [Maven Core Extensions Reference](/ref/current/maven-core/core-extensions.html).
+The API classloader aggregates exported packages from both the Maven Core classloader and any Maven Core Extensions classloaders. It does not include any classes directly.
+
+This has been introduced with Maven 3.3.1 ([MNG-5771](https://issues.apache.org/jira/browse/MNG-5771)). The main API is listed in [Maven Core Extensions Reference](/ref/current/maven-core/core-extensions.html).


delete "This has been introduced with Maven 3.3.1 (MNG-5771)."

elharo · 2026-08-09T11:41:06Z

+This has been introduced with Maven 3.3.1 ([MNG-5771](https://issues.apache.org/jira/browse/MNG-5771)). The main API is listed in [Maven Core Extensions Reference](/ref/current/maven-core/core-extensions.html).

-This has been introduced with Maven 3.3.1 ([MNG-5771](https://issues.apache.org/jira/browse/MNG-5771)).
+The Maven API classloader uses the approximate JVM Bootstrap classloader as its parent (there is no public API to access the JVM Bootstrap classloader; the implementation uses `ClassLoader.getSystemClassLoader().getParent()`). This parent does not contain any application or javaagent classes, which allows for a consistent Maven API classpath regardless of how the Maven JVM was launched.


run-on sentence
avoid parentheses

elharo · 2026-08-09T11:41:38Z


 For every plugin which is marked with `<extensions>true</extensions>` and every [build extension](/ref/current/maven-model/maven.html#class_extension) listed in the according section of the POM, there is a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. It imports everything from the API classloader. All JSR 330 or Plexus components declared in the underlying JAR are registered in the global Plexus container while creating the classloader. In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container. Build extensions have limited effect as they are loaded late.

+Modern Maven 3.x build extensions are those that either consist of multiple artifacts or include a `META-INF/maven/extension.xml` descriptor. Each such extension is loaded in a fully isolated classloader — it is not possible to share classes or inject components among extensions. Build extension classloaders use the ClassWorlds bootstrap classloader as the parent, which allows build extensions access to `-javaagent` classes.


Maven build extensions either consist of multiple artifacts

elharo · 2026-08-09T11:42:55Z

+
+- **With build extensions**: plugin classloaders are wired to project classloaders, giving plugin code access to both Maven API packages and packages exported by the project build extensions. Maven will create one and only one classloader for each unique plugin+dependencies+build-extensions combination.
+
+All plugin classloaders use the ClassWorlds bootstrap classloader as the parent. This provides a relatively clean and therefore consistent plugin classpath, while still allowing plugins access to `-javaagent` classes (see [MNG-4747](https://issues.apache.org/jira/browse/MNG-4747)).


delete therefore

BHARGAV-RUE added 2 commits June 5, 2026 21:44

Improve Maven classloading guide documentation

3c81cee

Imporved guide-maven-classloading

5bc8fd5

elharo requested changes Aug 9, 2026

View reviewed changes

BHARGAV-RUE added 2 commits August 11, 2026 15:03

Merge branch 'apache:master' into fix-1525-classloading-docs

d97c5d9

Address review comments

87ca3d7

Navigation Menu

Uh oh!

Fix 1525 classloading docs - #1594

Fix 1525 classloading docs#1594
BHARGAV-RUE wants to merge 4 commits into
apache:masterfrom
BHARGAV-RUE:fix-1525-classloading-docs

BHARGAV-RUE commented Jun 5, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

elharo Aug 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		The second classloader down the graph contains the core requirements of Maven. It is used by Maven internally but not by plugins. The core classloader has the libraries in `${maven.home}/lib`. In general these are just Maven libraries. For example instances of [`MavenProject`](/ref/current/apidocs/org/apache/maven/project/MavenProject.html) belong to this classloader.

		Contents of this classloader are configured in `${maven.home}/bin/m2.conf` and typically contains `${maven.home}/lib/ext/.jar` and `${maven.home}/lib/.jar`.


		## Core Extensions

		Core Extensions is a mechanism introduced in Maven 3.3.0 which allows additional components to be loaded into Maven Core as part of a build session.


		For every plugin which is marked with `<extensions>true</extensions>` and every [build extension](/ref/current/maven-model/maven.html#class_extension) listed in the according section of the POM, there is a dedicated classloader. Those are isolated. That is, one build extension does not have access to other build extensions. It imports everything from the API classloader. All JSR 330 or Plexus components declared in the underlying JAR are registered in the global Plexus container while creating the classloader. In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container. Build extensions have limited effect as they are loaded late.

		Modern Maven 3.x build extensions are those that either consist of multiple artifacts or include a `META-INF/maven/extension.xml` descriptor. Each such extension is loaded in a fully isolated classloader — it is not possible to share classes or inject components among extensions. Build extension classloaders use the ClassWorlds bootstrap classloader as the parent, which allows build extensions access to `-javaagent` classes.


		- With build extensions: plugin classloaders are wired to project classloaders, giving plugin code access to both Maven API packages and packages exported by the project build extensions. Maven will create one and only one classloader for each unique plugin+dependencies+build-extensions combination.

		All plugin classloaders use the ClassWorlds bootstrap classloader as the parent. This provides a relatively clean and therefore consistent plugin classpath, while still allowing plugins access to `-javaagent` classes (see [MNG-4747](https://issues.apache.org/jira/browse/MNG-4747)).

Uh oh!

Conversation

BHARGAV-RUE commented Jun 5, 2026

Summary

Changes

Validation

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

elharo Aug 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants