You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by kw...@apache.org on 2022/11/15 09:11:42 UTC
[maven-site] branch feature/core-and-build-extensions created (now 7fbc8ecc)
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a change to branch feature/core-and-build-extensions
in repository https://gitbox.apache.org/repos/asf/maven-site.git
at 7fbc8ecc [MNG-5771] Document all classloaders used in Maven
This branch includes the following new commits:
new 7fbc8ecc [MNG-5771] Document all classloaders used in Maven
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[maven-site] 01/01: [MNG-5771] Document all classloaders used in Maven
Posted by kw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
kwin pushed a commit to branch feature/core-and-build-extensions
in repository https://gitbox.apache.org/repos/asf/maven-site.git
commit 7fbc8ecc56dee103a9a0498a694d319c8c59eb8b
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Tue Nov 15 10:11:35 2022 +0100
[MNG-5771] Document all classloaders used in Maven
Clarify differences between Core and Build extensions
---
.../apt/guides/mini/guide-maven-classloading.apt | 84 +++++++++++++++-------
content/apt/guides/mini/guide-using-extensions.apt | 13 ++--
pom.xml | 42 ++++++++++-
src/plantuml/buildExtensionClassRealm.puml | 46 ++++++++++++
src/plantuml/pluginClassRealm.puml | 54 ++++++++++++++
5 files changed, 208 insertions(+), 31 deletions(-)
diff --git a/content/apt/guides/mini/guide-maven-classloading.apt b/content/apt/guides/mini/guide-maven-classloading.apt
index 7215d24b..30416ad7 100644
--- a/content/apt/guides/mini/guide-maven-classloading.apt
+++ b/content/apt/guides/mini/guide-maven-classloading.apt
@@ -30,28 +30,35 @@
Guide to Maven Classloading
This is a description of the classloader hierarchy in Maven.
-
+
+%{toc|section=1|fromDepth=2}
+
* Overview
- * System Classloader
+ Maven uses the {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}} classloading framework with which we
+ create our classloader graph. If you look in your <<<$\{maven.home\}/boot>>> directory you will see a single JAR
+ which is the Classworlds JAR we use to boot the classloader graph. The Classworlds JAR is the only element of
+ the Java <<<CLASSPATH>>> and Classworlds then builds the other classloaders or realms in Classworlds terminology.
- * Core Classloader
+ Each realm exposes
- * Plugin Classloaders
+ [[1]] optionally some classes imported from 0..n other classloaders
- * Custom Classloaders
-
- []
+ [[2]] optionally some classes from a directory or JAR
+
+ [[3]] one parent classloader
+ []
-* 1. {System Classloader}
+ The search order is always as given above.
- Maven uses the {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}} classloading framework with which we
- create our classloader graph. If you look in your <<<$\{maven.home\}/boot>>> directory you will see a single JAR
- which is the Classworlds JAR we use to boot the classloader graph. The Classworlds JAR is the only element of
- the Java <<<CLASSPATH>>> and Classworlds then builds the other classloaders or realms in Classworlds terminology.
+* {Platform Classloader}
+
+ This is the classloader exposing all JRE classes.
+
+* {System Classloader}
- An Ant script like this will show the contents of the system classloader:
+ An Ant script like this will show the contents of the system/bootstrap classloader:
+---+
<target name="info">
@@ -59,26 +66,53 @@ Guide to Maven Classloading
</target>
+---+
+ It imports the platform classloader.
-* 2. {Core Classloader}
+* {Core Classloader}
- The second classloader down the graph contains the core requirements of Maven. More precisely, the core classloader
- has the libraries in <<<$\{maven.home\}/lib>>>. In general these are just Maven libraries, e.g. instances of
+ The second classloader down the graph contains the core requirements of Maven. <<It is only 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, e.g. instances of
<<<{{{/ref/current/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>>
belong to this classloader.
- We hope to further separate these in the future to just be Maven APIs and have
- the implementations selected at runtime as required by the system.
You can add elements to this classloader by {{{/ref/current/maven-model/maven.html#class_extension}extensions}}.
These are loaded into the same place as <<<$\{maven.home\}/lib>>> and hence are available
- to the Maven core and all plugins for the current project and subsequent projects (in future, we
- plan to remove it from subsequent projects).
+ to the Maven core and all plugins for the current project (through the API classloader).
+ More information available in {{{./guide-using-extensions.html}Core Extension}}.
+
+* {API Classloader}
+
+ This exposes a filtered view of the Core Classloader by only exposing the exported packages from all Core Extensions.
+ The main API is listed in {{{https://maven.apache.org/ref/3-LATEST/maven-core/core-extensions.html}Maven Core Extensions Reference}}.
+
+ This has been introduced with Maven 3.3.1 ({{{https://issues.apache.org/jira/browse/MNG-5771}MNG-5771}}).
+
+* {Build Extension Classloaders}
-
-* 3. {Plugin Classloaders}
+[../../buildExtensionClassRealm.svg] Build Extension Class Realm
- After that, each plugin has its own classloader that is a child of Maven's core classloader.
- The classes in this classloader are taken from the dependencies in the plugin's dependency list.
+ For every plugin which is marked with <<<\<extensions\>true\</extensions\>>>> or a build extension listed in the according section of the POM there is
+ a dedicated classloader. Those are isolated (i.e. one build extension does not have access to other build extensions).
+ It imports everything from API classloader.
+ All JSR 330 or Plexus components declared in the underlying JAR are registered as components 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.
+
+* {Project Classloaders}
+
+ There is one project classloader per Maven project (identified through its GAV).
+ This one imports the API Classloader. In addition it exposes all classes from all Build Extension Classloaders which are bound to the current project.
+ This is only released with the container.
+ During the build outside Mojo executions, the thread's context classloader is set to the project classloader.
+
+* {Plugin Classloaders}
+
+[../../pluginClassRealm.svg] Plugin Class Realm
+
+ Each plugin (which is not marked as build extension) has its own classloader that imports the Project classloader.
+
+ Plugins marked with <<<\<extensions\>true\</extensions\>>>> leverage the Build Extension classloader instead of the Plugin classloader.
Users can add dependencies to this classloader by adding dependencies
to a plugin in the <<<{{{/ref/current/maven-model/maven.html#class_plugin}plugins/plugin}}>>>
@@ -118,7 +152,7 @@ Guide to Maven Classloading
When a build plugin is executed, the thread's context classloader is set to the plugin classloader.
-* 4. {Custom Classloaders}
+* {Custom Classloaders}
Plugins are free to create further classloaders on their discretion. For example, a plugin might want to create a
classloader that combines the plugin class path and the project class path.
diff --git a/content/apt/guides/mini/guide-using-extensions.apt b/content/apt/guides/mini/guide-using-extensions.apt
index 115fe5bc..76f87f14 100644
--- a/content/apt/guides/mini/guide-using-extensions.apt
+++ b/content/apt/guides/mini/guide-using-extensions.apt
@@ -28,7 +28,8 @@
Using Extensions
- Extensions are a way to add classes to {{{./guide-maven-classloading.html#Core_Classloader}Core Classloader}}.
+ Extensions are a way to add classes to either the {{{./guide-maven-classloading.html#Core_Classloader}Core Classloader}} (Core Extensions)
+ or the {{{./guide-maven-classloading.html#Project_Classloaders}Project Classloader}} (Build Extensions).
This is necessary for adjusting Maven in a way that affects more than just one plug-in.
The mechanism allows to either replace default {{{https://www.eclipse.org/sisu/}Sisu components}} with custom ones or add
@@ -40,10 +41,12 @@ Using Extensions
* Loading Extensions
- There are different means of loading extensions. They can be distinguished into <<early>> and <<late>> loading behaviour. Some extensions require early loading.
- Please refer to the extension's documentation whether early loading is required.
+ There are different means of loading extensions depending on the type. There are <core extensions> which are loaded <<early>>
+ and build extensions which are loaded <<late>>.
+ Some extensions require early loading as they fundamentally change Maven behaviour.
+ Please refer to the extension's documentation whether they provide a core or a build extension.
-** Early Loading
+** Core Extension
* Registered via extension jar in <<<$\{maven.home\}/lib/ext>>>
@@ -53,7 +56,7 @@ Using Extensions
[]
-** Late Loading
+** Build Extension
* Registered via {{{../../pom.html#Plugins}<<<project->build->plugins->plugin>>>}} with element <<<extensions>>> being set to <<<true>>>. This is useful for regular plug-ins carrying some extensions.
diff --git a/pom.xml b/pom.xml
index a0147741..c743139b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -76,6 +76,7 @@
<doxiaVersion>2.0.0-M3</doxiaVersion>
<doxiaToolsVersion>2.0.0-M3</doxiaToolsVersion>
<javaVersion>8</javaVersion>
+ <siteDirectory>${project.basedir}/content</siteDirectory>
</properties>
<repositories>
@@ -111,7 +112,7 @@
<artifactId>maven-site-plugin</artifactId>
<version>4.0.0-M3</version>
<configuration>
- <siteDirectory>${project.basedir}/content</siteDirectory>
+ <siteDirectory>${siteDirectory}</siteDirectory>
<skipDeploy>true</skipDeploy><!-- don't deploy site with maven-site-plugin -->
</configuration>
<dependencies>
@@ -283,6 +284,45 @@
</execution>
</executions>
</plugin>
+ <plugin>
+ <groupId>it.mulders.puml</groupId>
+ <artifactId>plantuml-maven-plugin</artifactId>
+ <version>0.1</version>
+ <dependencies>
+ <dependency>
+ <groupId>it.mulders.puml</groupId>
+ <artifactId>plantuml-v1-adapter</artifactId>
+ <version>0.2</version>
+ </dependency>
+ <dependency>
+ <groupId>net.sourceforge.plantuml</groupId>
+ <artifactId>plantuml</artifactId>
+ <version>1.2022.12</version>
+ </dependency>
+ </dependencies>
+ <executions>
+ <execution>
+ <id>generate-svg-from-plantuml</id>
+ <goals>
+ <goal>generate</goal>
+ </goals>
+ <phase>pre-site</phase>
+ <configuration>
+ <sourceFiles>
+ <directory>src/plantuml</directory>
+ <includes>
+ <include>**/*.dot</include>
+ <include>**/*.puml</include>
+ </includes>
+ </sourceFiles>
+ <outputDirectory>${project.reporting.outputDirectory}</outputDirectory>
+ <format>SVG</format>
+ <stripPath>src/plantuml</stripPath>
+ </configuration>
+ </execution>
+ </executions>
+
+ </plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
diff --git a/src/plantuml/buildExtensionClassRealm.puml b/src/plantuml/buildExtensionClassRealm.puml
new file mode 100644
index 00000000..0065a9f7
--- /dev/null
+++ b/src/plantuml/buildExtensionClassRealm.puml
@@ -0,0 +1,46 @@
+/*
+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.
+*/
+@startuml
+!pragma layout smetana
+Platform o-- Bootstrap
+Bootstrap "1" o-- "many" BuildExtension
+API "1" o-- "many" BuildExtension
+CoreExtension "many" o-- "1" API
+
+class Bootstrap {
+ Plexus Classworlds
+}
+
+class CoreExtension {
+ all packages defined in "/META-INF/maven/extension.xml"
+}
+
+class Platform {
+ all JRE classes
+}
+
+class BuildExtension {
+ dependencies
+ classes
+}
+
+note right of API : Just composition of all Core Extensions
+note right of Bootstrap : ${maven.home}/boot
+note right of BuildExtension : Per GAV of plugin loaded with <extensions>true</extensions> or build extension
+@enduml
\ No newline at end of file
diff --git a/src/plantuml/pluginClassRealm.puml b/src/plantuml/pluginClassRealm.puml
new file mode 100644
index 00000000..fef2c72a
--- /dev/null
+++ b/src/plantuml/pluginClassRealm.puml
@@ -0,0 +1,54 @@
+/*
+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.
+*/
+@startuml
+!pragma layout smetana
+Platform o-- Bootstrap
+Bootstrap "1" o-- "many" Plugin
+API "1" o-- "many" Project
+CoreExtension "many" o-- "1" API
+Project "1" --o "many" Plugin
+BuildExtension "many" o-- "1"Project
+class Bootstrap {
+ Plexus Classworlds
+}
+
+class CoreExtension {
+ all packages defined in "/META-INF/maven/extension.xml"
+}
+
+class Platform {
+ all JRE classes
+}
+
+class BuildExtension {
+ dependencies
+ classes
+}
+
+class Plugin {
+ dependencies
+ classes
+}
+
+note right of Plugin : Per GAV of plugin
+note right of Project : One per Maven POM
+note right of API : Just composition of all Core Extensions
+note right of Bootstrap : ${maven.home}/boot
+note right of BuildExtension : Per GAV of plugin loaded with <extensions>true</extensions> or build extension
+@enduml
\ No newline at end of file