diff --git a/content/markdown/guides/mini/guide-maven-classloading.md b/content/markdown/guides/mini/guide-maven-classloading.md index a30499362a..93afbd673f 100644 --- a/content/markdown/guides/mini/guide-maven-classloading.md +++ b/content/markdown/guides/mini/guide-maven-classloading.md @@ -21,6 +21,7 @@ under the License. This is a description of the classloader hierarchy in Maven. +![Maven Classloading overview](../../../resources/images/maven-classloading.png) ## Overview @@ -39,6 +40,10 @@ The search order is always as given above. This is the classloader exposing all JRE classes. +During normal command line Maven invocation, the ClassWorlds bootstrap classloader is the JVM System +classloader and contains classes from `${maven.home}/boot/plexus-classworlds-*.jar` and classes +from `-javaagent`. + ## System Classloader It contains only Plexus Classworlds and imports the platform classloader. @@ -47,32 +52,85 @@ It contains only Plexus Classworlds and imports the platform classloader. 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`. + You can add elements to this classloader by the means outlined in [Core Extension](./guide-using-extensions.html). These are loaded through the same classloader as `${maven.home}/lib` and hence are available to the Maven core and all plugins for the current project (through the API Classloader, see next paragraph). More information is available in [Core Extension](./guide-using-extensions.html). +## 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. + +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. + +A core extension can use a `META-INF/maven/extension.xml` descriptor to declare packages and artifacts exported by the extension. If the descriptor is not present, no packages or artifacts are exported, but the extension can still contribute components to Maven Core extension points. + +Core extensions are configured in the `.mvn/extensions.xml` configuration file at the project's top level: + +```xml + + + + ... + ... + ... + + ... + ... + +``` + +Core extensions are loaded as part of Maven runtime startup and disposed of as part of Maven runtime shutdown. + +## Maven Extensions Classloader + +The Maven Extensions classloader aggregates packages exported by all core extension realms. It also loads additional classpath entries specified via the `-Dmaven.ext.class.path` command line parameter. + +This classloader is created only when core extensions are configured for the build. If created, it will be set as the "container realm" in the Plexus container instance (replacing the Core Classloader in that role). + ## API Classloader -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). -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. ## Build Extension Classloaders -![Build Extension Class Realm](../../buildExtensionClassRealm.svg) +![Maven Classloading Overview](../../../resources/images/buildExtensionClassRealm.PNG) For every plugin which is marked with `true` 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 guarantees that each distinct modern build extension (as identified by groupId, artifactId, version and set of dependencies) is loaded by one and only one extension classloader, and that classloader is wired to all projects that use the extension. + ## Project Classloaders There is one project classloader per Maven project (identified through its coordinates). 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. +Legacy Maven 2.x build extensions (i.e. extensions that consist of a single artifact which does not include a `META-INF/maven/extension.xml` descriptor) are loaded directly into the project classloader rather than a separate extension classloader. + +Maven guarantees there will be one and only one project classloader for each unique set of project build extensions, and the same classloader will be used by all projects that have that set of build extensions. + ## Plugin Classloaders -![Plugin Class Realm](../../pluginClassRealm.svg) +![Plugin Class Realm](../../../resources/images/pluginClassRealm.png) Each plugin (which is not marked as build extension) has its own classloader that imports the Project classloader. Plugins marked with `true` leverage the Build Extension classloader instead of the Plugin classloader. +Plugin classloaders are wired differently depending on whether the project uses build extensions: + +- **Without build extensions**: a single classloader is created for each plugin identified by `groupId:artifactId:version`, importing API packages from the Maven API classloader. Maven will create one and only one classloader for each unique plugin+dependency combination. + +- **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)). + +Note: Reporting plugins are wired differently and are outside the scope of this document. + Users can add dependencies to this classloader by adding dependencies to a plugin in the [`plugins/plugin`](/ref/current/maven-model/maven.html#class_plugin) section of their project `pom.xml`. Here is a sample of adding `ant-nodeps` to the plugin classloader of the Antrun Plugin and hereby enabling the use of additional/optional Ant tasks: ```xml @@ -102,3 +160,28 @@ When a build plugin is executed, the thread's context classloader is set to the Plugins are free to create further classloaders. For example, a plugin might want to create a classloader that combines the plugin class path and the project class path. It is important to understand that the plugin classloader cannot load classes from any of those custom classloaders. Some factory patterns require that. Here you must add the classes to the plugin classloader as shown before. + +## Exported Artifacts and Packages + +Maven Core, Core Extensions, and Build Extensions use a `META-INF/maven/extension.xml` descriptor to declare API packages and artifacts exported by the classloader. + +```xml + + + + + org.something.myextension + + + + + org.company:myextension + + +``` + +If this descriptor is absent, the extension exports nothing but may still register components into the Maven Core extension points. \ No newline at end of file diff --git a/content/markdown/reference/maven-classloading.md b/content/markdown/reference/maven-classloading.md deleted file mode 100644 index ca50b28254..0000000000 --- a/content/markdown/reference/maven-classloading.md +++ /dev/null @@ -1,123 +0,0 @@ -# Maven classloading - - - -![](maven-classloading.png) - -## ClassWorlds bootstrap classloader - -This classloader is created and managed by the calling environment: JVM launcher, integration testing harness, etc. - -During normal command line Maven invocation this is the JVM System classloader and contains classes from `${maven.home}/boot/plexus-classworlds-*.jar` and classes from `-javaagent`. - -## Maven Core classloader - -This classloader contains core Maven runtime classes like MavenProject, AsbtractMojo and so on. This is the classloader set as the "container realm" in the Plexus container instance unless Maven Extensions classloader is created (see below). - -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`. - -## Maven Core Extensions classloaders - -Core Extensions is a new 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 extensions classloaders use Maven Core classloader as the parent and have access to both exported and internal Maven Core classes. - -Core extension can use `META-INF/maven/extension.xml` descriptor to declare packages and artifacts exported by the extension. If the descriptor is not present, no packages or artifacts are exported, but the extension can still contribute components to Maven Core extension points. - -Core extensions are configured `.mvn/extensions.xml` configuration file in the project's top level. - -```xml - - - - ... - ... - ... - - ... - ... - -``` - -Core extensions are loaded as part of Maven runtime startup and disposed of as part of Maven runtime shutdown. - -## Maven extensions classloader - -Maven extensions classloader aggregates packages exported by core extensions realms. It also loads additional classpath entries specified in `-Dmaven.ext.class.path` command line parameter. - -Maven extensions classloader is created only when core extensions are configured for the build. If created, it will be set as "container realm" in the Plexus container. - -## Maven API classloader - -Maven API classloader aggregates exported packages from Maven Core and Maven Core Extensions classloaders. Maven API classloader does not include any classes directly. - -Maven API uses approximate JVM Bootstrap classloader as its parent. (there is no API to access JVM Bootstrap classloader, implementation uses `ClassLoader.getSystemClassLoader().getParent()`). The parent classloader does not contain any application or javaagent classes, which allows for consistent Maven API classpath regardless how Maven JVM was launched. - -## Build Extension classloaders - -Modern Maven 3.x build extensions are build extensions that either consist of multiple artifacts or have `META-INF/maven/extension.xml`. Each modern build extension is loaded in a a fully isolated classloader, i.e. it is not possible to share classes or inject components among extensions. - -Maven guarantees that each distinct modern build extension (as identified by plugin groupId, artifactId, version and set of dependecies) is loaded by one and only one extensions classloader and the classloader is wired to all projects that use the extension. - -Build extension classloaders use ClassWorld bootstrap classloader as the parent, which allows build extensions access to `-javaagent` classes. - -## Project classloaders - -Project classloader aggregates Maven API packages, packages exported by project build extensions. - -Project classloaders use Maven API classloader as the parent and import exported classes from project build extension realms. Legacy Maven 2.x build extensions, i.e. extensions that consist of single artifact which does not include `META-INF/maven/extension.xml` descriptor, are directly in project classloaders. - -Maven guarantees there will be one and only one project classloader for each unique set of project build extensions and the same classloader will be used by all projects that have the set of build extensions. - -## Plugin classloaders - -Plugin classloaders are wired differently for projects with and without build extensions. - -For projects without build extensions, single classloader is created for each plugin identified by groupId:artifactId:version and the classloader imports API packages from Maven API classloader. Maven will create one and only one classloader for each unique plugin+dependency combination. - -For projects that use build extensions, plugin classloaders are wired to project classloaders. This gives plugin code access to both Maven API packages and packages exported by the project build extensions. Maven will create one and only one classlaoder for each unique plugin+dependencies+build-extensions combination. - -All plugin classloaders use ClassWorlds bootstrap classloader as the parent. This provides 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)). - -Reporting plugins are wired differently still, but reporting plugins are a special case and are outside of the scope of this document. - -## Exported artifacts and packages - -Maven Core, Session and Build Extensions use `META-INF/maven/extension.xml` descriptor to declare API packages and artifacts exported by the classloader. - -```xml - - - - - org.something.myextension - - - - - org.company:myextension - - -``` - diff --git a/content/markdown/reference/maven-classloading.odg b/content/markdown/reference/maven-classloading.odg deleted file mode 100644 index 40b64f4967..0000000000 Binary files a/content/markdown/reference/maven-classloading.odg and /dev/null differ diff --git a/content/resources/images/buildExtensionClassRealm.PNG b/content/resources/images/buildExtensionClassRealm.PNG new file mode 100644 index 0000000000..bde4b11f77 Binary files /dev/null and b/content/resources/images/buildExtensionClassRealm.PNG differ diff --git a/content/markdown/reference/maven-classloading.png b/content/resources/images/maven-classloading.png similarity index 100% rename from content/markdown/reference/maven-classloading.png rename to content/resources/images/maven-classloading.png diff --git a/content/resources/images/pluginClassRealm.png b/content/resources/images/pluginClassRealm.png new file mode 100644 index 0000000000..fc9d79de15 Binary files /dev/null and b/content/resources/images/pluginClassRealm.png differ