svn commit: r724671 - /maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt

[be...@apache.org]

Author: bentmann
Date: Tue Dec  9 04:26:28 2008
New Revision: 724671

URL: http://svn.apache.org/viewvc?rev=724671&view=rev
Log:
[MNG-2384] document how plugin classloaders work
Submitted by: Anders Kr. Andersen

o Applied with modifications

Modified:
    maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt

Modified: maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt?rev=724671&r1=724670&r2=724671&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt (original)
+++ maven/site/trunk/src/site/apt/guides/mini/guide-maven-classloading.apt Tue Dec  9 04:26:28 2008
@@ -2,44 +2,107 @@
  Guide to Maven Classloading
  ------
  Jason van Zyl
+ Anders Kristian Andersen
  ------
- 12 October 2005
+ 2008-12-10
  ------
-
-How Maven's classloaders work
+ 
+ 
+Guide to Maven Classloading
+
+ This is a description of the classloader hierarchy in Maven 2.0.6+.
+ 
+* Overview
+
+ * System Classloader
+ 
+ * Core Classloader
+ 
+ * Plugin Classloaders
+ 
+ * Custom Classloaders
+
+ [] 
+ 
+ 
+* 1. {System Classloader}
 
  Maven uses the {{{http://classworlds.codehaus.org}Classworlds}} classloading framework with which we
- create our classloader graph. If you look in your <<<$\{maven.home\}/m2/core>>> 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 following graph of classloaders where the <<<plexus.core>>> classloader, 
- or Realm in Classworlds, is the parent in the context of Maven.
-
-+----+
-
-[plexus.core]
-${maven.home}/core/*.jar
-    ^
-    |
-    |
-[plexus.core.maven]
-${maven.home}/lib/*.jar
-    ^
-    |
-    |
-[per plugin]
-
-+----+
-
- The top level classloader contains plexus container and plexus utils, and also has access to Classworlds.
-
- The next classloader down the graph contain the core requirements of Maven. In general these are just Maven libraries.
- 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.
-
- After that, each plugin has its own classloader, including its dependencies, itself, and the libraries above.
- It <does not> contain the project dependencies as in Maven 1.x, but instead has access to a list of JAR files in case
- they are needed.
-
- In addition, a project can list <extensions>. These are loaded into <<<[plexus.maven.core]>>> classloader and
- so available to the Maven core and all plug-ins for the current project and subsequent projects (in the future,
- we plan to remove it from subsequent projects).
+ 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.
+ 
+ An Ant script like this will show the contents of the system classloader:
+ 
+---
+    <target name="info">
+      <echo>java.class.path=${java.class.path}</echo>
+    </target>
+---
+ 
+
+* 2. {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
+ <<<{{{http://maven.apache.org/ref/current/maven-project/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 {{{http://maven.apache.org/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).
+
+  
+* 3. {Plugin Classloaders}
+
+ 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.
+
+ Users can add dependencies to this classloader by adding dependencies 
+ to a plugin in the <<<{{{http://maven.apache.org/ref/current/maven-model/maven.html#class_plugin}plugins/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:
+ 
+---
+            <plugin>
+              <groupId>org.apache.maven.plugins</groupId>
+              <artifactId>maven-antrun-plugin</artifactId>
+              <version>1.3</version>
+              <dependencies>
+                <dependency>
+                  <groupId>org.apache.ant</groupId>
+                  <artifactId>ant-nodeps</artifactId>
+                  <version>1.7.1</version>
+                </dependency>
+              </dependencies>
+              ...
+            </plugin>
+---
+ 
+ Plugins can inspect their effective runtime class path via the expressions <<<$\{plugin.artifacts\}>>> or
+ <<<$\{plugin.artifactMap\}>>> to have a list or map, respectively, of resolved artifacts injected from the
+ <<<{{{http://maven.apache.org/ref/current/maven-plugin-descriptor/apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html}PluginDescriptor}}>>>.
+
+ Please note that the plugin classloader does not contain the
+ {{{http://maven.apache.org/ref/current/maven-model/maven.html#class_dependency}dependencies}}
+ of the current project. Instead, plugins can query the project's compile, runtime and test class path from the 
+ <<<{{{http://maven.apache.org/ref/current/maven-project/apidocs/org/apache/maven/project/MavenProject.html}MavenProject}}>>>
+ in combination with the mojo annotation <<<requiresDependencyResolution>>> from the
+ {{{http://maven.apache.org/developers/mojo-api-specification.html}Mojo API Specification}}. For instance, flagging a
+ mojo with <<<@requiresDependencyResolution runtime>>> enables it to query the runtime class path of the current project
+ from which it could create further classloaders.
+
+ When a build plugin is executed, the thread's context classloader is set to the plugin classloader.
+
+
+* 4. {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.
+ 
+ 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.