Document hidden and protected classes (#12511)

* Document hidden and protected classes Fix #12106 by documenting hidden and protected classes. * Apply suggestions from code review Co-authored-by: Jan Bartel <[email protected]> * Converted all documentation examples to EE11 --------- Co-authored-by: Jan Bartel <[email protected]>
jetty · Nov 13, 2024 · 64659c8 · 64659c8
1 parent 790e07b
commit 64659c8
Show file tree

Hide file tree

Showing 19 changed files with 165 additions and 96 deletions.
diff --git a/documentation/jetty/modules/code/examples/pom.xml b/documentation/jetty/modules/code/examples/pom.xml
@@ -71,18 +71,18 @@
       <artifactId>jetty-util-ajax</artifactId>
     </dependency>
     <dependency>
-      <groupId>org.eclipse.jetty.ee10</groupId>
-      <artifactId>jetty-ee10-servlet</artifactId>
+      <groupId>org.eclipse.jetty.ee11</groupId>
+      <artifactId>jetty-ee11-servlet</artifactId>
       <version>${project.version}</version>
     </dependency>
     <dependency>
-      <groupId>org.eclipse.jetty.ee10</groupId>
-      <artifactId>jetty-ee10-servlets</artifactId>
+      <groupId>org.eclipse.jetty.ee11</groupId>
+      <artifactId>jetty-ee11-servlets</artifactId>
       <version>${project.version}</version>
     </dependency>
     <dependency>
-      <groupId>org.eclipse.jetty.ee10.websocket</groupId>
-      <artifactId>jetty-ee10-websocket-jakarta-server</artifactId>
+      <groupId>org.eclipse.jetty.ee11.websocket</groupId>
+      <artifactId>jetty-ee11-websocket-jakarta-server</artifactId>
       <version>${project.version}</version>
     </dependency>
     <dependency>

diff --git a/...es/src/main/java/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereum.java b/...es/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/...a/org/eclipse/jetty/docs/programming/security/siwe/SignInWithEthereumEmbeddedExample.java b/...a/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/...examples/src/main/java/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java b/...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/...examples/src/main/java/org/eclipse/jetty/docs/programming/server/session/SessionDocs.java b/...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/...rc/main/java/org/eclipse/jetty/docs/programming/server/websocket/WebSocketServerDocs.java b/...rc/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
@@ -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
@@ -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 `<env>-deploy` module configuration file, `$JETTY_BASE/start.d/<env>-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 `<env>-deploy` module configuration file, `$JETTY_BASE/start.d/<env>-deploy.ini` (eg: `ee11-deploy.ini`), uncomment the module property `jetty.deploy.scanInterval` and change the value to `1` second (or greater):
 
 .<env>-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
@@ -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
@@ -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
@@ -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
@@ -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/...n/jetty/modules/programming-guide/pages/maven-jetty/jetty-maven-helloworld.adoc b/...n/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
   <build>
     <plugins>
       <plugin>
-        <groupId>org.eclipse.jetty.ee10</groupId>
-        <artifactId>jetty-ee10-maven-plugin</artifactId>
+        <groupId>org.eclipse.jetty.ee11</groupId>
+        <artifactId>jetty-ee11-maven-plugin</artifactId>
         <version>$\{jettyVersion}</version>
       </plugin>
     </plugins>

diff --git 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]
 ----
-<Configure id="wac" class="org.eclipse.jetty.ee10.webapp.WebAppContext">
+<Configure id="wac" class="org.eclipse.jetty.ee11.webapp.WebAppContext">
   <Call id="ResourceFactory" class="org.eclipse.jetty.util.resource.ResourceFactory" name="of">
     <Arg><Ref refid="Server"/></Arg>
     <Call id="realmResource" name="newResource">