Merge pull request #4740 from eclipse/jetty-9.4.x-4638-formcontentsize-doc

Issue #4638 - updating documentation about form limits

jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc

@@ -26,11 +26,37 @@ Thus Jetty limits the amount of data and keys that can be in a form posted to Je
 The default maximum size Jetty permits is 200000 bytes and 1000 keys.
 You can change this default for a particular webapp or for all webapps on a particular Server instance.
 
+==== Configuring Default Form Limits via System Properties
+
+There exists 2 system properties that will adjust the default maximum form sizes.
+
+* `org.eclipse.jetty.server.Request.maxFormKeys` - the maximum number of Form Keys allowed
+* `org.eclipse.jetty.server.Request.maxFormContentSize` - the maximum size of Form Content allowed
+
+Used from command line as such:
+
+[source,shell,subs="{sub-order}"]
+----
+$ java -Dorg.eclipse.jetty.server.Request.maxFormKeys=200 -jar ...
+
+$ java -Dorg.eclipse.jetty.server.Request.maxFormContentSize=400000 -jar ...
+
+----
+
+Or via Java code (make sure you do this before you instantiate any `ContextHandler`, `ServletContextHandler`, or `WebAppContext`)
+
+[source,java,subs="{sub-order}"]
+----
+System.setProperty(ContextHandler.MAX_FORM_KEYS_KEY, "200");
+System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000");
+
+----
+
 ==== Configuring Form Limits for a Webapp
 
 To configure the form limits for a single web application, the context handler (or webappContext) instance must be configured using the following methods:
 
-[source, java, subs="{sub-order}"]
+[source,java,subs="{sub-order}"]
 ----
 ContextHandler.setMaxFormContentSize(int maxSizeInBytes);
 ContextHandler.setMaxFormKeys(int formKeys);
@@ -50,26 +76,3 @@ These methods may be called directly when embedding Jetty, but more commonly are
 </Configure>
 
 ----
-
-==== Configuring Form Limits for the Server
-
-If a context does not have specific form limits configured, then the server attributes are inspected to see if a server wide limit has been set on the size or keys.
-The following XML shows how these attributes can be set in `jetty.xml`:
-
-[source, xml, subs="{sub-order}"]
-----
-<configure class="org.eclipse.jetty.server.Server">
-
-  ...
-
-  <Call name="setAttribute">
-    <Arg>org.eclipse.jetty.server.Request.maxFormContentSize</Arg>
-    <Arg>100000</Arg>
-   </Call>
-  <Call name="setAttribute">
-    <Arg>org.eclipse.jetty.server.Request.maxFormKeys</Arg>
-    <Arg>2000</Arg>
-   </Call>
-</configure>
-
-----

jetty-server/src/main/java/org/eclipse/jetty/server/handler/ContextHandler.java

@@ -93,19 +93,24 @@ import org.eclipse.jetty.util.resource.Resource;
 /**
  * ContextHandler.
  *
+ * <p>
  * This handler wraps a call to handle by setting the context and servlet path, plus setting the context classloader.
- *
+ * </p>
  * <p>
- * If the context init parameter "org.eclipse.jetty.server.context.ManagedAttributes" is set to a comma separated list of names, then they are treated as
+ * If the context init parameter {@code org.eclipse.jetty.server.context.ManagedAttributes} is set to a comma separated list of names, then they are treated as
  * context attribute names, which if set as attributes are passed to the servers Container so that they may be managed with JMX.
+ * </p>
  * <p>
- * The maximum size of a form that can be processed by this context is controlled by the system properties org.eclipse.jetty.server.Request.maxFormKeys and
- * org.eclipse.jetty.server.Request.maxFormContentSize. These can also be configured with {@link #setMaxFormContentSize(int)} and {@link #setMaxFormKeys(int)}
+ * The maximum size of a form that can be processed by this context is controlled by the system properties {@code org.eclipse.jetty.server.Request.maxFormKeys} and
+ * {@code org.eclipse.jetty.server.Request.maxFormContentSize}. These can also be configured with {@link #setMaxFormContentSize(int)} and {@link #setMaxFormKeys(int)}
+ * </p>
  * <p>
- * This servers executor is made available via a context attributed "org.eclipse.jetty.server.Executor".
+ * The executor is made available via a context attributed {@code org.eclipse.jetty.server.Executor}.
+ * </p>
  * <p>
  * By default, the context is created with alias checkers for {@link AllowSymLinkAliasChecker} (unix only) and {@link ApproveNonExistentDirectoryAliases}. If
  * these alias checkers are not required, then {@link #clearAliasChecks()} or {@link #setAliasChecks(List)} should be called.
+ * </p>
  */
 @ManagedObject("URI Context")
 public class ContextHandler extends ScopedHandler implements Attributes, Graceful