EagerContentHandler. #9051 (#12077)

Fix #9051 with EagerContentHandler to replace DelayedHandler

The make the EagerContentHandler.RetainedContentLoader work efficiently this PR adjusted the buffering strategy of h1, h2 and h3 to keep and reuse a retained buffer until it is mostly full.

Also fixed several bugs in XmlConfiguration:

 + A Set could not be used with a builder style method (kind of missing feature more than a bug)
 + If a property element was used in a Set it could only be a string and the type element was ignored.
 + When trying to find a native match, the vClass local variable was overwritten with the native TYPE being tried. This affected subsequent match attempts using the wrong vClass

---------

Signed-off-by: Lachlan Roberts <lachlan.p.roberts@gmail.com>
Signed-off-by: gregw <gregw@webtide.com>
Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
Co-authored-by: Lachlan Roberts <lachlan.p.roberts@gmail.com>
Co-authored-by: Simone Bordet <simone.bordet@gmail.com>
Co-authored-by: Ludovic Orban <lorban@bitronix.be>

Author: 4 people

documentation/jetty/modules/operations-guide/pages/modules/standard.adoc

@@ -129,6 +129,21 @@ The module properties are:
 include::{jetty-home}/modules/debuglog.mod[tags=documentation]
 ----
 
+[[eager-content]]
+== Module `eager-content`
+
+The `eager-content` module installs the `org.eclipse.jetty.server.handler.EagerContentHandler` at the root of the `Handler` tree.
+
+The `EagerContentHandler` can eagerly load request content, asynchronously, before calling the next `Handler`.
+For more information see xref:programming-guide:server/http.adoc#handler-use-eager[this section].
+
+`EagerContentHandler` can eagerly load content for form uploads, multipart uploads and any request content, and you can configure it with different properties for these three cases.
+
+The module properties are:
+
+----
+include::{jetty-home}/modules/eager-content.mod[tags=documentation]
+----
 
 [[eeN-deploy]]
 == Module `{ee-all}-deploy`

documentation/jetty/modules/programming-guide/pages/server/http.adoc

@@ -1198,6 +1198,44 @@ In the example above, `ContextHandlerCollection` will try to match a request to
 NOTE: `DefaultHandler` just sends a nicer HTTP `404` response in case of wrong requests from clients.
 Jetty will send an HTTP `404` response anyway if `DefaultHandler` has not been set.
 
+[[handler-use-eager]]
+==== EagerContentHandler
+
+`EagerContentHandler` reads eagerly the HTTP request content, and invokes the next `Handler` in the `Handler` tree when the request content has been read.
+
+`EagerContentHandler` should be installed when web applications use blocking I/O to read the request content, which is the typical case for Servlet or RESTful (JAX-RS) web applications.
+
+Because the request content is read eagerly and asynchronously, the web application will never (or rarely) block while reading the request content.
+In this way, the application obtains the benefits of asynchronous I/O without forcing web application developers to use more complicated asynchronous I/O APIs.
+
+The `Handler` tree structure looks like the following:
+
+[,screen]
+----
+Server
+└── (GzipHandler) // optional
+    └── EagerContentHandler
+        └── ContextHandler /app
+            └── AppHandler
+----
+
+`EagerContentHandler` should be installed in the `Handler` tree _after_ other ``Handler``s that may modify or transform the request content, like for example the `GzipHandler`.
+
+`EagerContentHandler` eagerly reads request content in the following cases:
+
+* Form request content.
+* MultiPart request content.
+* Any other type of request content.
+
+For Form request content, `EagerContentHandler` reads the whole request content, parses it into a `Fields` object, and then invokes the next `Handler`.
+This allows web applications that use blocking API calls such as `HttpServletRequest.getParameterMap()` to avoid blocking, since they can directly use the already created `Fields` object.
+
+Similarly, for MultiPart request content, `EagerContentHandler` reads the whole request content, parses it into `MultiPartFormData.Parts`, and then invokes the next `Handler`.
+This allows web applications that use blocking API calls such as `HttpServletRequest.getParts()` to avoid blocking, since the can directly use the already created `MultiPartFormData.Parts` object.
+
+For other types of request content, `EagerContentHandler` reads and retains request content bytes up to a configurable amount, and then invokes the next `Handler`, without any further processing of the request content bytes.
+This allows web applications that use blocking API calls such as `HttpServletRequest.getInputStream()` to avoid blocking in most cases (if the request is smaller than what has been configured in `EagerContentHandler`).
+
 [[handler-use-servlet]]
 === Servlet API Handlers