- * This loader defaults to the 2.3 servlet spec behavior where non - * system classes are loaded from the classpath in preference to the - * parent loader. Java2 compliant loading, where the parent loader - * always has priority, can be selected with the - * {@link WebAppContext#setParentLoaderPriority(boolean)} - * method and influenced with {@link WebAppContext#isHiddenClass(Class)} and - * {@link WebAppContext#isProtectedClass(Class)}. + * This loader implements the Servlet specification behavior that may invert the normal Java classloader parent priority + * behaviour. The {@link ClassVisibilityChecker} API of the {@link WebAppClassLoader.Context} implementation is + * used to determine which classes from the parent classloader are hidden from the context, and which are protected + * from being overridden by the context. *
- * If no parent class loader is provided, then the current thread
- * context classloader will be used. If that is null then the
- * classloader that loaded this class is used as the parent.
+ * Java compliant loading, where the parent loader always has priority, can be selected with the
+ * {@link WebAppContext#setParentLoaderPriority(boolean)} method.
*/
public class WebAppClassLoader extends URLClassLoader implements ClassVisibilityChecker
{
@@ -169,6 +165,9 @@ public static
+ * The {@link Thread#currentThread()} {@link Thread#getContextClassLoader()} will be used as the parent loader,
+ * unless {@code null}, in which case the classloader that loaded this class is used as the parent.
*
* @param context the context for this classloader
*/
@@ -180,7 +179,9 @@ public WebAppClassLoader(Context context)
/**
* Constructor.
*
- * @param parent the parent classloader
+ * @param parent the parent classloader; if {@code null} then the {@link Thread#currentThread()}
+ * {@link Thread#getContextClassLoader()} will be used as the parent loader,
+ * unless also {@code null}, in which case the classloader that loaded this class is used as the parent.
* @param context the context for this classloader
*/
public WebAppClassLoader(ClassLoader parent, Context context)
diff --git a/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppContext.java b/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppContext.java
index ddc15c77b2db..0a4d5ab71f5e 100644
--- a/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppContext.java
+++ b/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppContext.java
@@ -77,7 +77,9 @@
* The handlers are configured by pluggable configuration classes, with
* the default being {@link WebXmlConfiguration} and
* {@link JettyWebXmlConfiguration}.
- *
+ * The class implements {@link WebAppClassLoader.Context} and thus the {@link org.eclipse.jetty.util.ClassVisibilityChecker}
+ * API, which is used by any {@link WebAppClassLoader} to control visibility of classes to the context.
- * These classes/packages are used to implement the server and are hidden
- * from the context. If the context needs to load these classes, it must have its
- * own copy of them in WEB-INF/lib or WEB-INF/classes.
+ * This {@link ClassMatcher} is used to implement the {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract
+ * for the context by determining which classes and resources from the server and environment classloader are hidden
+ * from the context. The context may have its own copy of these classes/resources in WEB-INF/lib or WEB-INF/classes.
*
* @param hiddenClasses the server classes pattern
*/
@@ -644,9 +646,10 @@ public void setHiddenClassMatcher(ClassMatcher hiddenClasses)
/**
* Set the protected (system) classes patterns.
*
- * These classes/packages are provided by the JVM and
- * cannot be replaced by classes of the same name from WEB-INF,
- * regardless of the value of {@link #setParentLoaderPriority(boolean)}.
+ *
+ * This {@link ClassMatcher} is used to implement the {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract
+ * for the context by determining which classes and resources from the server and environment classloader may not be
+ * overridden by the context. The context may not have its own copy of these classes/resources.
*
* @param protectedClasses the system classes pattern
*/
@@ -661,6 +664,8 @@ public void setProtectedClassMatcher(ClassMatcher protectedClasses)
* any existing matcher.
*
* @param hiddenClasses The class matcher of patterns to add to the server ClassMatcher
+ * @see org.eclipse.jetty.util.ClassVisibilityChecker
+ * @see #setHiddenClassMatcher(ClassMatcher)
*/
public void addHiddenClassMatcher(ClassMatcher hiddenClasses)
{
@@ -672,6 +677,8 @@ public void addHiddenClassMatcher(ClassMatcher hiddenClasses)
* any existing matcher.
*
* @param protectedClasses The class matcher of patterns to add to the system ClassMatcher
+ * @see org.eclipse.jetty.util.ClassVisibilityChecker
+ * @see #setProtectedClassMatcher(ClassMatcher)
*/
public void addProtectedClassMatcher(ClassMatcher protectedClasses)
{
@@ -679,7 +686,9 @@ public void addProtectedClassMatcher(ClassMatcher protectedClasses)
}
/**
- * @return The ClassMatcher used to match System (protected) classes
+ * @return The ClassMatcher used to match System (protected) classes to implement the
+ * {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract.
+ * @see #setProtectedClassMatcher(ClassMatcher)
*/
public ClassMatcher getProtectedClassMatcher()
{
@@ -687,7 +696,9 @@ public ClassMatcher getProtectedClassMatcher()
}
/**
- * @return The ClassMatcher used to match Server (hidden) classes
+ * @return The ClassMatcher used to match Server (hidden) classes to implement the
+ * {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract.
+ * @see #setHiddenClassMatcher(ClassMatcher)
*/
public ClassMatcher getHiddenClassMatcher()
{
diff --git a/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppClassLoader.java b/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppClassLoader.java
index 4df0656aad20..e6d61cbdb79b 100644
--- a/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppClassLoader.java
+++ b/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppClassLoader.java
@@ -54,17 +54,13 @@
* Specializes URLClassLoader with some utility and file mapping
* methods.
*
- * This loader defaults to the 2.3 servlet spec behavior where non
- * system classes are loaded from the classpath in preference to the
- * parent loader. Java2 compliant loading, where the parent loader
- * always has priority, can be selected with the
- * {@link WebAppContext#setParentLoaderPriority(boolean)}
- * method and influenced with {@link WebAppContext#isHiddenClass(Class)} and
- * {@link WebAppContext#isProtectedClass(Class)}.
+ * This loader implements the Servlet specification behavior that may invert the normal Java classloader parent priority
+ * behaviour. The {@link ClassVisibilityChecker} API of the {@link WebAppClassLoader.Context} implementation is
+ * used to determine which classes from the parent classloader are hidden from the context, and which are protected
+ * from being overridden by the context.
*
- * If no parent class loader is provided, then the current thread
- * context classloader will be used. If that is null then the
- * classloader that loaded this class is used as the parent.
+ * Java compliant loading, where the parent loader always has priority, can be selected with the
+ * {@link WebAppContext#setParentLoaderPriority(boolean)} method.
*/
public class WebAppClassLoader extends URLClassLoader implements ClassVisibilityChecker
{
@@ -148,6 +144,9 @@ public static
+ * The {@link Thread#currentThread()} {@link Thread#getContextClassLoader()} will be used as the parent loader,
+ * unless {@code null}, in which case the classloader that loaded this class is used as the parent.
*
* @param context the context for this classloader
*/
@@ -159,7 +158,9 @@ public WebAppClassLoader(Context context)
/**
* Constructor.
*
- * @param parent the parent classloader
+ * @param parent the parent classloader; if {@code null} then the {@link Thread#currentThread()}
+ * {@link Thread#getContextClassLoader()} will be used as the parent loader,
+ * unless also {@code null}, in which case the classloader that loaded this class is used as the parent.
* @param context the context for this classloader
*/
public WebAppClassLoader(ClassLoader parent, Context context)
diff --git a/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppContext.java b/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppContext.java
index a4046ac43a49..73127bbc0389 100644
--- a/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppContext.java
+++ b/jetty-ee11/jetty-ee11-webapp/src/main/java/org/eclipse/jetty/ee11/webapp/WebAppContext.java
@@ -77,7 +77,9 @@
* The handlers are configured by pluggable configuration classes, with
* the default being {@link WebXmlConfiguration} and
* {@link JettyWebXmlConfiguration}.
- *
+ * The class implements {@link WebAppClassLoader.Context} and thus the {@link org.eclipse.jetty.util.ClassVisibilityChecker}
+ * API, which is used by any {@link WebAppClassLoader} to control visibility of classes to the context.
- * These classes/packages are used to implement the server and are hidden
- * from the context. If the context needs to load these classes, it must have its
- * own copy of them in WEB-INF/lib or WEB-INF/classes.
+ * This {@link ClassMatcher} is used to implement the {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract
+ * for the context by determining which classes and resources from the server and environment classloader are hidden
+ * from the context. The context may have its own copy of these classes/resources in WEB-INF/lib or WEB-INF/classes.
*
* @param hiddenClasses the server classes pattern
*/
@@ -626,9 +628,10 @@ public void setHiddenClassMatcher(ClassMatcher hiddenClasses)
/**
* Set the protected (system) classes patterns.
*
- * These classes/packages are provided by the JVM and
- * cannot be replaced by classes of the same name from WEB-INF,
- * regardless of the value of {@link #setParentLoaderPriority(boolean)}.
+ *
+ * This {@link ClassMatcher} is used to implement the {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract
+ * for the context by determining which classes and resources from the server and environment classloader may not be
+ * overridden by the context. The context may not have its own copy of these classes/resources.
*
* @param protectedClasses the system classes pattern
*/
@@ -642,7 +645,9 @@ public void setProtectedClassMatcher(ClassMatcher protectedClasses)
* Add a ClassMatcher for hidden (server) classes by combining with
* any existing matcher.
*
- * @param hiddenClasses The class matcher of patterns to add to the server ClassMatcher
+ * @param hiddenClasses The class matcher of patterns to add to the hidden (server) ClassMatcher
+ * @see org.eclipse.jetty.util.ClassVisibilityChecker
+ * @see #setHiddenClassMatcher(ClassMatcher)
*/
public void addHiddenClassMatcher(ClassMatcher hiddenClasses)
{
@@ -654,6 +659,8 @@ public void addHiddenClassMatcher(ClassMatcher hiddenClasses)
* any existing matcher.
*
* @param protectedClasses The class matcher of patterns to add to the system ClassMatcher
+ * @see org.eclipse.jetty.util.ClassVisibilityChecker
+ * @see #setProtectedClassMatcher(ClassMatcher)
*/
public void addProtectedClassMatcher(ClassMatcher protectedClasses)
{
@@ -661,7 +668,9 @@ public void addProtectedClassMatcher(ClassMatcher protectedClasses)
}
/**
- * @return The ClassMatcher used to match System (protected) classes
+ * @return The ClassMatcher used to match protected (system) classes to implement the
+ * {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract.
+ * @see #setProtectedClassMatcher(ClassMatcher)
*/
public ClassMatcher getProtectedClassMatcher()
{
@@ -669,7 +678,9 @@ public ClassMatcher getProtectedClassMatcher()
}
/**
- * @return The ClassMatcher used to match Server (hidden) classes
+ * @return The ClassMatcher used to match hidden (server) classes to implement the
+ * {@link org.eclipse.jetty.util.ClassVisibilityChecker} contract.
+ * @see #setHiddenClassMatcher(ClassMatcher)
*/
public ClassMatcher getHiddenClassMatcher()
{