You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2023/06/22 18:32:22 UTC
[tomcat] 02/04: Update Servlet API for parameter error handling changes
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch tmp
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit 34d4ed59f50fa1eb4b373730e20bdb821f30a353
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Thu Jun 15 12:15:08 2023 +0100
Update Servlet API for parameter error handling changes
---
java/jakarta/servlet/ServletRequest.java | 56 ++++++++++++++++++++++++++++++++
1 file changed, 56 insertions(+)
diff --git a/java/jakarta/servlet/ServletRequest.java b/java/jakarta/servlet/ServletRequest.java
index 795502f3b4..1e700dd900 100644
--- a/java/jakarta/servlet/ServletRequest.java
+++ b/java/jakarta/servlet/ServletRequest.java
@@ -162,11 +162,25 @@ public interface ServletRequest {
* <p>
* If the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the
* body directly via {@link #getInputStream} or {@link #getReader} can interfere with the execution of this method.
+ * <p>
+ * If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
+ * the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
+ * the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
+ * {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
+ * deployment descriptor.
*
* @param name a <code>String</code> specifying the name of the parameter
*
* @return a <code>String</code> representing the single value of the parameter
*
+ * @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
+ * parameters including, but not limited to: invalid percent (%nn) encoding;
+ * invalid byte sequence for the specified character set; I/O errors reading the
+ * request body; and triggering a container defined limit related to parameter
+ * parsing. Containers may provide container specific options to handle some or
+ * all of these errors in an alternative manner that may include not throwing an
+ * exception.
+ *
* @see #getParameterValues
*/
String getParameter(String name);
@@ -175,9 +189,23 @@ public interface ServletRequest {
* Returns an <code>Enumeration</code> of <code>String</code> objects containing the names of the parameters
* contained in this request. If the request has no parameters, the method returns an empty
* <code>Enumeration</code>.
+ * <p>
+ * If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
+ * the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
+ * the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
+ * {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
+ * deployment descriptor.
*
* @return an <code>Enumeration</code> of <code>String</code> objects, each <code>String</code> containing the name
* of a request parameter; or an empty <code>Enumeration</code> if the request has no parameters
+ *
+ * @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
+ * parameters including, but not limited to: invalid percent (%nn) encoding;
+ * invalid byte sequence for the specified character set; I/O errors reading the
+ * request body; and triggering a container defined limit related to parameter
+ * parsing. Containers may provide container specific options to handle some or
+ * all of these errors in an alternative manner that may include not throwing an
+ * exception.
*/
Enumeration<String> getParameterNames();
@@ -186,11 +214,25 @@ public interface ServletRequest {
* <code>null</code> if the parameter does not exist.
* <p>
* If the parameter has a single value, the array has a length of 1.
+ * <p>
+ * If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
+ * the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
+ * the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
+ * {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
+ * deployment descriptor.
*
* @param name a <code>String</code> containing the name of the parameter whose value is requested
*
* @return an array of <code>String</code> objects containing the parameter's values
*
+ * @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
+ * parameters including, but not limited to: invalid percent (%nn) encoding;
+ * invalid byte sequence for the specified character set; I/O errors reading the
+ * request body; and triggering a container defined limit related to parameter
+ * parsing. Containers may provide container specific options to handle some or
+ * all of these errors in an alternative manner that may include not throwing an
+ * exception.
+ *
* @see #getParameter
*/
String[] getParameterValues(String name);
@@ -198,10 +240,24 @@ public interface ServletRequest {
/**
* Returns a java.util.Map of the parameters of this request. Request parameters are extra information sent with the
* request. For HTTP servlets, parameters are contained in the query string or posted form data.
+ * <p>
+ * If not already parsed, calling this method will trigger the parsing of the query string, POSTed form data where
+ * the request body has content type is <code>application/x-www-form-urlencoded</code> and POSTed form data where
+ * the request body has content-type <code>multipart/form-data</code> and the Servlet is configured with a
+ * {@link jakarta.servlet.annotation.MultipartConfig} annotation or a <code>multipart-config</code> element in the
+ * deployment descriptor.
*
* @return an immutable java.util.Map containing parameter names as keys and parameter values as map values. The
* keys in the parameter map are of type String. The values in the parameter map are of type String
* array.
+ *
+ * @throws IllegalStateException if parameter parsing is triggered and a problem is encountered parsing the
+ * parameters including, but not limited to: invalid percent (%nn) encoding;
+ * invalid byte sequence for the specified character set; I/O errors reading the
+ * request body; and triggering a container defined limit related to parameter
+ * parsing. Containers may provide container specific options to handle some or
+ * all of these errors in an alternative manner that may include not throwing an
+ * exception.
*/
Map<String,String[]> getParameterMap();
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org