svn commit: r425247 - /jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java

[sk...@apache.org]

Author: skitching
Date: Mon Jul 24 18:26:37 2006
New Revision: 425247

URL: http://svn.apache.org/viewvc?rev=425247&view=rev
Log:
Add javadoc about setExplicitLoader/addLogicalLib.

Modified:
    jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java

Modified: jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java
URL: http://svn.apache.org/viewvc/jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java?rev=425247&r1=425246&r2=425247&view=diff
==============================================================================
--- jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java (original)
+++ jakarta/commons/proper/logging/trunk/src/test/org/apache/commons/logging/PathableClassLoader.java Mon Jul 24 18:26:37 2006
@@ -72,9 +72,27 @@
      * See setParentFirst.
      */
     private boolean parentFirst = true;
-    
+
     /**
      * Constructor.
+     * <p>
+     * Often, null is passed as the parent, ie the parent of the new
+     * instance is the bootloader. This ensures that the classpath is
+     * totally clean; nothing but the standard java library will be
+     * present.
+     * <p>
+     * When using a null parent classloader with a junit testcase, it *is*
+     * necessary for the junit library to also be visible. In this case, it
+     * is recommended that the following code be used:
+     * <pre>
+     * pathableLoader.useExplicitLoader(
+     *   "junit.",
+     *   junit.framework.Test.class.getClassLoader());
+     * </pre>
+     * Note that this works regardless of whether junit is on the system
+     * classpath, or whether it has been loaded by some test framework that
+     * creates its own classloader to run unit tests in (eg maven2's
+     * Surefire plugin).
      */
     public PathableClassLoader(ClassLoader parent) {
         super(NO_URLS, parent);
@@ -125,6 +143,28 @@
 
     /**
      * Specify a classloader to use for specific java packages.
+     * <p>
+     * The specified classloader is normally a loader that is NOT
+     * an ancestor of this classloader. In particular, this loader
+     * may have the bootloader as its parent, but be configured to 
+     * see specific other classes (eg the junit library loaded
+     * via the system classloader).
+     * <p>
+     * The differences between using this method, and using
+     * addLogicalLib are:
+     * <ul>
+     * <li>If code calls getClassLoader on a class loaded via
+     * "lookaside", then traces up its inheritance chain, it
+     * will see the "real" classloaders. When the class is remapped
+     * into this classloader via addLogicalLib, the classloader
+     * chain seen is this object plus ancestors.
+     * <li>If two different jars contain classes in the same
+     * package, then it is not possible to load both jars into
+     * the same "lookaside" classloader (eg the system classloader)
+     * then map one of those subsets from here. Of course they could
+     * be loaded into two different "lookaside" classloaders and
+     * then a prefix used to map from here to one of those classloaders.
+     * </ul>
      */
     public void useExplicitLoader(String prefix, ClassLoader loader) {
         if (lookasides == null) {



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org