diff --git a/documentation/jetty/modules/code/examples/pom.xml b/documentation/jetty/modules/code/examples/pom.xml index ae7103350cf5..c50f3707ab85 100644 --- a/documentation/jetty/modules/code/examples/pom.xml +++ b/documentation/jetty/modules/code/examples/pom.xml @@ -71,18 +71,18 @@ jetty-util-ajax - org.eclipse.jetty.ee10 - jetty-ee10-servlet + org.eclipse.jetty.ee11 + jetty-ee11-servlet ${project.version} - org.eclipse.jetty.ee10 - jetty-ee10-servlets + org.eclipse.jetty.ee11 + jetty-ee11-servlets ${project.version} - org.eclipse.jetty.ee10.websocket - jetty-ee10-websocket-jakarta-server + org.eclipse.jetty.ee11.websocket + jetty-ee11-websocket-jakarta-server ${project.version} diff --git a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereum.java b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereum.java index 4599346ae444..c1556b583b4e 100644 --- a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereum.java +++ b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereum.java @@ -23,7 +23,7 @@ public class SignInWithEthereum public static SecurityHandler createSecurityHandler(Handler handler) { // tag::configureSecurityHandler[] - // This uses jetty-core, but you can configure a ConstraintSecurityHandler for use with EE10. + // This uses jetty-core, but you can configure a ConstraintSecurityHandler for use with EE11. SecurityHandler.PathMapped securityHandler = new SecurityHandler.PathMapped(); securityHandler.setHandler(handler); securityHandler.put("/*", Constraint.ANY_USER); diff --git a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereumEmbeddedExample.java b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereumEmbeddedExample.java index 7cebeafd0459..2edc3437592d 100644 --- a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereumEmbeddedExample.java +++ b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereumEmbeddedExample.java @@ -96,7 +96,7 @@ else if ("/logout".equals(pathInContext)) public static SecurityHandler createSecurityHandler(Handler handler) { // tag::configureSecurityHandler[] - // This uses jetty-core, but you can configure a ConstraintSecurityHandler for use with EE10. + // This uses jetty-core, but you can configure a ConstraintSecurityHandler for use with EE11. SecurityHandler.PathMapped securityHandler = new SecurityHandler.PathMapped(); securityHandler.setHandler(handler); securityHandler.put("/*", Constraint.ANY_USER); diff --git a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java index 7d8b60ec686e..8427ea9d8a52 100644 --- a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java +++ b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java @@ -33,11 +33,11 @@ import org.eclipse.jetty.alpn.server.ALPNServerConnectionFactory; import org.eclipse.jetty.client.ContentResponse; import org.eclipse.jetty.client.HttpClient; -import org.eclipse.jetty.ee10.servlet.DefaultServlet; -import org.eclipse.jetty.ee10.servlet.ResourceServlet; -import org.eclipse.jetty.ee10.servlet.ServletContextHandler; -import org.eclipse.jetty.ee10.servlet.ServletHolder; -import org.eclipse.jetty.ee10.webapp.WebAppContext; +import org.eclipse.jetty.ee11.servlet.DefaultServlet; +import org.eclipse.jetty.ee11.servlet.ResourceServlet; +import org.eclipse.jetty.ee11.servlet.ServletContextHandler; +import org.eclipse.jetty.ee11.servlet.ServletHolder; +import org.eclipse.jetty.ee11.webapp.WebAppContext; import org.eclipse.jetty.http.HttpCompliance; import org.eclipse.jetty.http.HttpFields; import org.eclipse.jetty.http.HttpHeader; @@ -92,6 +92,7 @@ import org.eclipse.jetty.server.handler.gzip.GzipHandler; import org.eclipse.jetty.unixdomain.server.UnixDomainServerConnector; import org.eclipse.jetty.util.Callback; +import org.eclipse.jetty.util.ClassMatcher; import org.eclipse.jetty.util.Fields; import org.eclipse.jetty.util.NanoTime; import org.eclipse.jetty.util.Promise; @@ -1205,6 +1206,48 @@ public void webAppContextHandler() throws Exception // end::webAppContextHandler[] } + public void webAppContextClassLoader() throws Exception + { + // tag::webAppContextClassLoader[] + Server server = new Server(); + Connector connector = new ServerConnector(server); + server.addConnector(connector); + + // Create a WebAppContext. + WebAppContext context = new WebAppContext(); + + // Keep Servlet specification behaviour + context.setParentLoaderPriority(false); + + // Add hidden classes by package (with exclusion) and by location + context.addHiddenClassMatcher(new ClassMatcher( + "org.example.package.", + "-org.example.package.SpecificClass", + "file:/usr/local/server/lib/some.jar" + )); + + // Add protected classes by class name and JPMS module + context.addProtectedClassMatcher(new ClassMatcher( + "org.example.package.SpecificClass", + "jrt:/modulename" + )); + + // Add addition class path items to the context loader + context.setExtraClasspath("file:/usr/local/server/context/lib/context.jar;file:/usr/local/server/context/classes/"); + + // end::webAppContextClassLoader[] + + // Link the context to the server. + server.setHandler(context); + + // Configure the path of the packaged web application (file or directory). + context.setWar("/path/to/webapp.war"); + // Configure the contextPath. + context.setContextPath("/app"); + + server.start(); + } + public void resourceHandler() throws Exception { // tag::resourceHandler[] diff --git a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java index 51264ad11807..db317eb44ecf 100644 --- a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java +++ b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java @@ -18,8 +18,8 @@ import java.net.InetSocketAddress; import java.util.Properties; -import org.eclipse.jetty.ee10.servlet.ServletContextHandler; -import org.eclipse.jetty.ee10.webapp.WebAppContext; +import org.eclipse.jetty.ee11.servlet.ServletContextHandler; +import org.eclipse.jetty.ee11.webapp.WebAppContext; import org.eclipse.jetty.gcloud.session.GCloudSessionDataStoreFactory; import org.eclipse.jetty.io.Content; import org.eclipse.jetty.memcached.session.MemcachedSessionDataMapFactory; diff --git a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/websocket/WebSocketServerDocs.java b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/websocket/WebSocketServerDocs.java index c50d54520e8e..9e3b9e006a70 100644 --- a/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/websocket/WebSocketServerDocs.java +++ b/documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/websocket/WebSocketServerDocs.java @@ -22,9 +22,9 @@ import jakarta.websocket.server.ServerContainer; import jakarta.websocket.server.ServerEndpoint; import jakarta.websocket.server.ServerEndpointConfig; -import org.eclipse.jetty.ee10.servlet.ServletContextHandler; -import org.eclipse.jetty.ee10.webapp.WebAppContext; -import org.eclipse.jetty.ee10.websocket.jakarta.server.config.JakartaWebSocketServletContainerInitializer; +import org.eclipse.jetty.ee11.servlet.ServletContextHandler; +import org.eclipse.jetty.ee11.webapp.WebAppContext; +import org.eclipse.jetty.ee11.websocket.jakarta.server.config.JakartaWebSocketServletContainerInitializer; import org.eclipse.jetty.http.HttpStatus; import org.eclipse.jetty.http.pathmap.PathSpec; import org.eclipse.jetty.http.pathmap.UriTemplatePathSpec; diff --git a/documentation/jetty/modules/operations-guide/pages/begin/index.adoc b/documentation/jetty/modules/operations-guide/pages/begin/index.adoc index 125094101097..9b0ddd1f0ffa 100644 --- a/documentation/jetty/modules/operations-guide/pages/begin/index.adoc +++ b/documentation/jetty/modules/operations-guide/pages/begin/index.adoc @@ -22,18 +22,18 @@ Jetty is distributed in an artifact that expands in a directory called `$JETTY_H Configuration for Jetty is typically done in a directory called `$JETTY_BASE`. There may be more than one `$JETTY_BASE` directories with different configurations. -Jetty supports the deployment of EE8, EE9 and EE10 standard web applications, as well as the deployment of Jetty-specific web applications. +Jetty supports the deployment of EE8, EE9, EE10 and EE11 standard web applications, as well as the deployment of Jetty-specific web applications. -For example, the following commands can be used to set up a `$JETTY_BASE` directory that supports deployment of EE10 `+*.war+` files and a clear-text HTTP connector: +For example, the following commands can be used to set up a `$JETTY_BASE` directory that supports deployment of EE11 `+*.war+` files and a clear-text HTTP connector: ---- $ export JETTY_HOME=/path/to/jetty-home $ mkdir /path/to/jetty-base $ cd /path/to/jetty-base -$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,ee10-deploy +$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,ee11-deploy ---- -The last command creates a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard EE10 `+*.war+` files can be deployed. +The last command creates a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard EE11 `+*.war+` files can be deployed. To deploy Jetty's demo web applications, run this command: diff --git a/documentation/jetty/modules/operations-guide/pages/deploy/index.adoc b/documentation/jetty/modules/operations-guide/pages/deploy/index.adoc index 2e43458416bb..c5b5c3638fc8 100644 --- a/documentation/jetty/modules/operations-guide/pages/deploy/index.adoc +++ b/documentation/jetty/modules/operations-guide/pages/deploy/index.adoc @@ -54,7 +54,7 @@ The following command line enables _hot_ deployment by specifying the `jetty.dep $ java -jar $JETTY_HOME/start.jar jetty.deploy.scanInterval=1 ---- -To make _hot_ deployment persistent, you need to edit the appropriate `-deploy` module configuration file, `$JETTY_BASE/start.d/-deploy.ini` (eg: `ee10-deploy.ini`), uncomment the module property `jetty.deploy.scanInterval` and change the value to `1` second (or greater): +To make _hot_ deployment persistent, you need to edit the appropriate `-deploy` module configuration file, `$JETTY_BASE/start.d/-deploy.ini` (eg: `ee11-deploy.ini`), uncomment the module property `jetty.deploy.scanInterval` and change the value to `1` second (or greater): .-deploy.ini [source,subs=+quotes] diff --git a/documentation/jetty/modules/operations-guide/pages/jaspi/index.adoc b/documentation/jetty/modules/operations-guide/pages/jaspi/index.adoc index 32a18ab5cfd0..cd087e5321a2 100644 --- a/documentation/jetty/modules/operations-guide/pages/jaspi/index.adoc +++ b/documentation/jetty/modules/operations-guide/pages/jaspi/index.adoc @@ -26,7 +26,7 @@ Only modules conforming to the "Servlet Container Profile" with the ServerAuthMo Enable the `jaspi` module: ---- -include::{jetty-home}/modules/ee10-jaspi.mod[] +include::{jetty-home}/modules/ee11-jaspi.mod[] ---- [[xml]] @@ -48,7 +48,7 @@ The following example uses Jetty's {ee-current-caps} implementation of `AuthConf [,xml] ---- -include::{jetty-home}/etc/jaspi/jetty-ee10-jaspi-demo.xml[] +include::{jetty-home}/etc/jaspi/jetty-ee11-jaspi-demo.xml[] ---- Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way. @@ -66,5 +66,5 @@ This custom module must reference an XML file which sets a new instance of the ` For an example of this see the `{ee-current}-jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty. ---- -include::{jetty-home}/modules/ee10-jaspi-default-auth-config-factory.mod[] +include::{jetty-home}/modules/ee11-jaspi-default-auth-config-factory.mod[] ---- diff --git a/documentation/jetty/modules/operations-guide/pages/jsp/index.adoc b/documentation/jetty/modules/operations-guide/pages/jsp/index.adoc index e3a71dd4902f..9e9ab8183520 100644 --- a/documentation/jetty/modules/operations-guide/pages/jsp/index.adoc +++ b/documentation/jetty/modules/operations-guide/pages/jsp/index.adoc @@ -17,7 +17,7 @@ Jetty supports JSP via the `{ee-all}-jsp` modules, which are based on Apache Jas [source,subs=attributes+] ---- -include::{jetty-home}/modules/ee10-jsp.mod[] +include::{jetty-home}/modules/ee11-jsp.mod[] ---- Logging has been bridged to Jetty logging, so you can enable logging for the `org.apache.jasper` package, subpackages and classes as usual. diff --git a/documentation/jetty/modules/operations-guide/pages/jstl/index.adoc b/documentation/jetty/modules/operations-guide/pages/jstl/index.adoc index 1032798aaea6..2fc3dc11d032 100644 --- a/documentation/jetty/modules/operations-guide/pages/jstl/index.adoc +++ b/documentation/jetty/modules/operations-guide/pages/jstl/index.adoc @@ -17,7 +17,7 @@ The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distributi [source,subs=attributes+] ---- -include::{jetty-home}/modules/ee10-jstl.mod[] +include::{jetty-home}/modules/ee11-jstl.mod[] ---- When enabled, Jetty will make the JSTL tags available for your webapps. diff --git a/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc b/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc index fa4f041a23d0..730fb220e530 100644 --- a/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc +++ b/documentation/jetty/modules/operations-guide/pages/modules/standard.adoc @@ -87,7 +87,7 @@ include::{jetty-home}/modules/console-capture.mod[tags=documentation] [[core-deploy]] == Module `core-deploy` -include::{jetty-home}/modules/ee10-deploy.mod[tags=description] +include::{jetty-home}/modules/ee11-deploy.mod[tags=description] Deployment is managed via a `DeploymentManager` component that watches a directory for changes. See xref:deploy/index.adoc[how to deploy web applications] for more information. @@ -133,7 +133,7 @@ include::{jetty-home}/modules/debuglog.mod[tags=documentation] [[eeN-deploy]] == Module `{ee-all}-deploy` -include::{jetty-home}/modules/ee10-deploy.mod[tags=description] +include::{jetty-home}/modules/ee11-deploy.mod[tags=description] Deployment is managed via a `DeploymentManager` component that watches a directory for changes. See xref:deploy/index.adoc[how to deploy web applications] for more information. @@ -145,7 +145,7 @@ Multiple versions of this module exist (`{ee-all}-deploy`) to support each Jakar Jetty's configuration properties are nearly identical across these versions; the configuration properties for the `{ee-current}-deploy` Jetty module are: ---- -include::{jetty-home}/modules/ee10-deploy.mod[tags=ini-template] +include::{jetty-home}/modules/ee11-deploy.mod[tags=ini-template] ---- Among the configurable properties, the most relevant are: @@ -159,13 +159,13 @@ Setting `jetty.deploy.scanInterval=0` disabled _hot_ deployment so that only sta [[eeN-webapp]] == Module `{ee-all}-webapp` -include::{jetty-home}/modules/ee10-webapp.mod[tags=description] +include::{jetty-home}/modules/ee11-webapp.mod[tags=description] Multiple versions of this module exist (`{ee-all}-webapp`) to support each Jakarta EE platform's version of the Java Servlet specification. Jetty's configuration properties are identical across all versions of this module, and are as follows: ---- -include::{jetty-home}/modules/ee10-webapp.mod[tags=ini-template] +include::{jetty-home}/modules/ee11-webapp.mod[tags=ini-template] ---- [[http]] @@ -296,7 +296,7 @@ include::{jetty-home}/modules/https.mod[] [[jmx]] == Module `jmx` -include::{jetty-home}/modules/ee10-webapp.mod[tags=description] +include::{jetty-home}/modules/ee11-webapp.mod[tags=description] This configuration is useful for xref:jmx/index.adoc#local[local development and testing]. If you need to xref:jmx/index.adoc#remote[enable remote access], use the xref:jmx/index.adoc#remote[`jmx-remote` module]. diff --git a/documentation/jetty/modules/programming-guide/pages/maven-jetty/jetty-maven-helloworld.adoc b/documentation/jetty/modules/programming-guide/pages/maven-jetty/jetty-maven-helloworld.adoc index 17951f82c02a..d6db5c12995e 100644 --- a/documentation/jetty/modules/programming-guide/pages/maven-jetty/jetty-maven-helloworld.adoc +++ b/documentation/jetty/modules/programming-guide/pages/maven-jetty/jetty-maven-helloworld.adoc @@ -248,8 +248,8 @@ Use an editor to create the file `pom.xml` with the following contents in the `J - org.eclipse.jetty.ee10 - jetty-ee10-maven-plugin + org.eclipse.jetty.ee11 + jetty-ee11-maven-plugin $\{jettyVersion} diff --git a/documentation/jetty/modules/programming-guide/pages/security/siwe-support.adoc b/documentation/jetty/modules/programming-guide/pages/security/siwe-support.adoc index 715f8f8283af..bd9cc690677d 100644 --- a/documentation/jetty/modules/programming-guide/pages/security/siwe-support.adoc +++ b/documentation/jetty/modules/programming-guide/pages/security/siwe-support.adoc @@ -26,7 +26,7 @@ Typically, you would rely on a browser extension such as MetaMask to provide a u === Support -Currently Jetty only provides support SIWE in Jetty 12.1+ and only for `jetty-core`, and `ee10`+ environments. It is enabled by adding the `EtheremAuthenticator` to the `SecurityHandler` of your web application. +Currently Jetty only provides support SIWE in Jetty 12.1+ and only for `jetty-core`, and `ee11`+ environments. It is enabled by adding the `EtheremAuthenticator` to the `SecurityHandler` of your web application. == Usage @@ -87,10 +87,10 @@ Chain IDs:: A nested `LoginService` may be used to assign roles to users of a known Ethereum Address. Or the nested `LoginService` may be combined with the setting `authenticateNewUsers == false` to only allow authentication of known users. -For example a `HashLoginService` may be configured through the `jetty-ee10-web.xml` file: +For example a `HashLoginService` may be configured through the `jetty-ee11-web.xml` file: [, xml, indent=0] ---- - + diff --git a/documentation/jetty/modules/programming-guide/pages/server/http.adoc b/documentation/jetty/modules/programming-guide/pages/server/http.adoc index a6f990633459..19319cd45fc5 100644 --- a/documentation/jetty/modules/programming-guide/pages/server/http.adoc +++ b/documentation/jetty/modules/programming-guide/pages/server/http.adoc @@ -1284,32 +1284,34 @@ include::code:example$src/main/java/org/eclipse/jetty/docs/programming/server/ht ---- [[handler-use-webapp-context-class-loading]] -.WebAppContext Class Loading +==== WebAppContext Class Loading -The Servlet specification requires that a web application class loader must load the web application classes from `WEB-INF/classes` and `WEB_INF/lib`. -The web application class loader is special because it behaves differently from typical class loaders: where typical class loaders first delegate to their parent class loader and then try to find the class locally, the web application class loader first tries to find the class locally and then delegates to the parent class loader. -The typical class loading model, parent-first, is _inverted_ for web application class loaders, as they use a child-first model. +The Servlet specification requires that a web application class loader must load classes found in the web application `WEB-INF/classes` and `WEB_INF/lib` in preference to using the parent class loader. +This is significantly different to typical java class loaders where loaders first delegate to their parent class loader. +For Servlet specification compliant web applications, the typical parent-first class loading model is _inverted_. -Furthermore, the Servlet specification requires that web applications cannot load or otherwise access the Servlet container implementation classes, also called _server classes_. +Furthermore, the Servlet specification requires that web applications cannot load or otherwise access the Servlet container implementation classes, also called _hidden classes_ (previously called _server classes_). Web applications receive the HTTP request object as an instance of the `jakarta.servlet.http.HttpServletRequest` interface, and cannot downcast it to the Jetty specific implementation of that interface to access Jetty specific features -- this ensures maximum web application portability across Servlet container implementations. -Lastly, the Servlet specification requires that other classes, also called _system classes_, such as `jakarta.servlet.http.HttpServletRequest` or JDK classes such as `java.lang.String` or `java.sql.Connection` cannot be modified by web applications by putting, for example, modified versions of those classes in `WEB-INF/classes` so that they are loaded first by the web application class loader (instead of the class-path class loader where they are normally loaded from). +Lastly, the Servlet specification requires that specific classes are _protected classes_ (previously called _system classes_), in that they cannot be replaced by the web application loader and normal class loader priority applies. These are classes such as `jakarta.servlet.http.HttpServletRequest`; JDK classes such as `java.lang.String` or `java.sql.Connection`. -`WebAppContext` implements this class loader logic using a single class loader, `WebAppClassLoader`, with filtering capabilities: when it loads a class, it checks whether the class is a _system class_ or a _server class_ and acts according to the Servlet specification. +`WebAppContext` implements this class loader logic using a single class loader, `WebAppClassLoader`, with filtering capabilities: when it loads a class, it checks whether the class is a _protected class_ or a _hidden class_ by delegating to the `ClassVisibilityChecker` of the context. -When `WebAppClassLoader` is asked to load a class, it first tries to find the class locally (since it must use the inverted child-first model); if the class is found, and it is not a _system class_, the class is loaded; otherwise the class is not found locally. +When `WebAppClassLoader` is asked to load a class, it first tries to find the class locally (since it must use the inverted child-first model); if the class is found, and it is not a _protected class_, the class is loaded; otherwise the class is not found locally. If the class is not found locally, the parent class loader is asked to load the class; the parent class loader uses the standard parent-first model, so it delegates the class loading to its parent, and so on. -If the class is found, and it is not a _server class_, the class is loaded; otherwise the class is not found and a `ClassNotFoundException` is thrown. +If the class is found, and it is not a _hidden class_, the class is loaded; otherwise the class is not found and a `ClassNotFoundException` is thrown. -Unfortunately, the Servlet specification does not define exactly which classes are _system classes_ and which classes are _server classes_. -However, Jetty picks good defaults and allows server applications to customize _system classes_ and _server classes_ in `WebAppContext`. +Unfortunately, the Servlet specification does not define exactly which classes are _hidden classes_ and which classes are _protected classes_. +However, Jetty picks good defaults and allows server applications to customize _hidden classes_ and _protected classes_ in `WebAppContext`. -// TODO: add a section on parentLoaderPriority. -// TODO: add a code example about how to set system/server classes. -// TODO: add a code example about how to configure extra classpath -// TODO: add a section on ClassLoading (see old docs) +Below you can find an example of how to set up additional classloading configuration, including hidden and protected classes in code: + +[,java,indent=0] +---- +include::code:example$src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=webAppContextClassLoader] +---- -// TODO: add a section on Configuration (system/server classes) +// TODO: add a section on ClassLoading (see old docs) // TODO: add a section about how to setup JSP support [[handler-use-default-servlet]] diff --git a/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppClassLoader.java b/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppClassLoader.java index 0a2788223c6e..27cf64ec8aa7 100644 --- a/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppClassLoader.java +++ b/jetty-ee10/jetty-ee10-webapp/src/main/java/org/eclipse/jetty/ee10/webapp/WebAppClassLoader.java @@ -51,17 +51,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 { @@ -169,6 +165,9 @@ public static T runWithServerClassAccess(PrivilegedExceptionAction action /** * Constructor. + *

+ * 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.

*/ @ManagedObject("Web Application ContextHandler") public class WebAppContext extends ServletContextHandler implements WebAppClassLoader.Context, Deployable @@ -629,9 +631,9 @@ public PermissionCollection getPermissions() /** * Set the hidden (server) classes patterns. *

- * 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 T runWithHiddenClassAccess(PrivilegedExceptionAction action /** * Constructor. + *

+ * 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.

*/ @ManagedObject("Web Application ContextHandler") public class WebAppContext extends ServletContextHandler implements WebAppClassLoader.Context, Deployable @@ -611,9 +613,9 @@ public PermissionCollection getPermissions() /** * Set the hidden (server) classes patterns. *

- * 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() {