Merge branch 'jetty-12.0.x' of https://github.com/eclipse/jetty.project…

… into jetty-12.0.x-old-docs-remove-logging-sections

* 'jetty-12.0.x' of https://github.com/eclipse/jetty.project:
  Issue jetty#9182 - make JakartaWSSCI.initialize() and JakartaWebSocketServerContainer public
  ensure the WebSocketConnection is set on the WebSocketCoreSession
  remove osgi internal imports for websocket-core
  rename WebSocketUtil to WebSocketUtils
  make WebSocketCoreSession public & other fixes
  Javadocs for Response and Context. (jetty#9388)
  Moved implementation methods ensure*() from the Response interface (jetty#9390)
  Reinstate ee9 jetty runner. (jetty#9383)
  Fix jetty#9387
  remove setClassLoader from CoreSession interface
  remove exporting of internal packages in ee9 & ee10 websocket
  fix remaining JPMS issues in websocket-core
  resolve JPMS issues with CoreSession and WebSocketCoreSession
  move websocket-core-common messages and util packages out of internal

jetty-core/jetty-server/src/main/java/org/eclipse/jetty/server/Context.java

@@ -18,21 +18,22 @@
 import java.util.concurrent.Executor;
 
 import org.eclipse.jetty.http.MimeTypes;
+import org.eclipse.jetty.server.handler.ContextHandler;
 import org.eclipse.jetty.util.Attributes;
 import org.eclipse.jetty.util.Decorator;
 import org.eclipse.jetty.util.resource.Resource;
 
 /**
- * A Context for handling a request.
- * Every request will always have a non-null context, which may initially be the Server context, or
- * a context provided by a ContextHandler.
- * <p>
- * A Context is also an {@link Executor}, which allows tasks to be run by a thread pool, but scoped
- * to the classloader and any other aspects of the context.   Method {@link #run(Runnable)}
- * is also provided to allow the current Thread to be scoped to the context.
- * <p>
- * A Context is also a {@link Decorator}, allowing objects to be decorated in a context scope.
- *
+ * <p>The context for handling an HTTP request.</p>
+ * <p>Every request has a non-{@code null} context, which may initially
+ * be the {@link Server#getContext() server context}, or
+ * a context provided by a {@link ContextHandler}.</p>
+ * <p>A context is also an {@link Executor}, which allows tasks to be run by a
+ * thread pool, but scoped to the ClassLoader and any other context property.</p>
+ * <p>Method {@link #run(Runnable)} is also provided to allow the current thread
+ * to be scoped to the context for the execution of the task.</p>
+ * <p>A Context is also a {@link Decorator}, allowing objects to be decorated
+ * in a context scope.</p>
  */
 public interface Context extends Attributes, Decorator, Executor
 {
@@ -41,39 +42,70 @@ public interface Context extends Attributes, Decorator, Executor
      */
     String getContextPath();
 
+    /**
+     * @return the {@link ClassLoader} associated with this Context
+     */
     ClassLoader getClassLoader();
 
+    /**
+     * @return the base resource used to lookup other resources
+     * specified by the request URI path
+     */
     Resource getBaseResource();
 
+    /**
+     * @return the error {@link Request.Handler} associated with this Context
+     */
     Request.Handler getErrorHandler();
 
+    /**
+     * @return a list of virtual host names associated with this Context
+     */
     List<String> getVirtualHosts();
 
+    /**
+     * @return the mime types associated with this Context
+     */
     MimeTypes getMimeTypes();
 
-    /** execute runnable in container thread scoped to context */
+    /**
+     * <p>Executes the given task in a thread scoped to this Context.</p>
+     *
+     * @param task the task to run
+     * @see #run(Runnable)
+     */
     @Override
-    void execute(Runnable runnable);
+    void execute(Runnable task);
 
-    /** scope the calling thread to the context and run the runnable. */
-    void run(Runnable runnable);
+    /**
+     * <p>Runs the given task in the current thread scoped to this Context.</p>
+     *
+     * @param task the task to run
+     * @see #run(Runnable, Request)
+     */
+    void run(Runnable task);
 
-    /** scope the calling thread to the context and request and run the runnable. */
-    void run(Runnable runnable, Request request);
+    /**
+     * <p>Runs the given task in the current thread scoped to this Context and the given Request.</p>
+     *
+     * @param task the task to run
+     * @param request the HTTP request to use in the scope
+     */
+    void run(Runnable task, Request request);
 
     /**
      * <p>Returns a URI path scoped to this Context.</p>
      * <p>For example, if the context path is {@code /ctx} then a
      * full path of {@code /ctx/foo/bar} will return {@code /foo/bar}.</p>
      *
-     * @param fullPath A full URI path
-     * @return The URI path scoped to this Context, or {@code null} if the full path does not match this Context.
-     *         The empty string is returned if the full path is exactly the context path.
+     * @param fullPath a full URI path
+     * @return the URI path scoped to this Context, or {@code null} if the full path does not match this Context.
+     * The empty string is returned if the full path is exactly the context path.
      */
     String getPathInContext(String fullPath);
 
     /**
-     * @return A temporary directory, configured either for the context, the server or the JVM. Never null.
+     * @return a non-{@code null} temporary directory, configured either for the context, the server or the JVM
      */
     File getTempDirectory();
 }

jetty-core/jetty-server/src/main/java/org/eclipse/jetty/server/Request.java

@@ -19,7 +19,6 @@
 import java.net.SocketAddress;
 import java.nio.ByteBuffer;
 import java.nio.charset.Charset;
-import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
 import java.util.function.Function;
@@ -113,7 +112,6 @@
  */
 public interface Request extends Attributes, Content.Source
 {
-    List<Locale> __defaultLocale = Collections.singletonList(Locale.getDefault());
     String CACHE_ATTRIBUTE = Request.class.getCanonicalName() + ".CookieCache";
     String COOKIE_ATTRIBUTE = Request.class.getCanonicalName() + ".Cookies";
 
@@ -382,13 +380,13 @@ static List<Locale> getLocales(Request request)
     {
         HttpFields fields = request.getHeaders();
         if (fields == null)
-            return __defaultLocale;
+            return List.of(Locale.getDefault());
 
         List<String> acceptable = fields.getQualityCSV(HttpHeader.ACCEPT_LANGUAGE);
 
         // handle no locale
         if (acceptable.isEmpty())
-            return __defaultLocale;
+            return List.of(Locale.getDefault());
 
         return acceptable.stream().map(language ->
         {
@@ -506,7 +504,7 @@ interface Handler extends Invocable
          * completing the passed callback. The handling may be asynchronous, i.e. this method may return true and
          * complete the given callback later, possibly from a different thread.  If this method returns false,
          * then the callback must not be invoked and any mutation on the response reversed.</p>
-         * <p>Exceptions thrown by this method may be subsequently handled by an {@link ErrorHandler},
+         * <p>Exceptions thrown by this method may be subsequently handled by an error {@link Request.Handler},
          * if present, otherwise a default HTTP 500 error is generated and the
          * callback completed while writing the error response.</p>
          * <p>The simplest implementation is:</p>