Fix jakartaee#415 - add overloaded setCharacterEncoding() supporting Charset

Author: markt-asf

api/src/main/java/jakarta/servlet/ServletContext.java

@@ -22,6 +22,7 @@
 import java.io.InputStream;
 import java.net.MalformedURLException;
 import java.net.URL;
+import java.nio.charset.Charset;
 import java.util.Enumeration;
 import java.util.EventListener;
 import java.util.Map;
@@ -1342,6 +1343,26 @@ public interface ServletContext {
      */
     public void setRequestCharacterEncoding(String encoding);
 
+    /**
+     * Sets the request character encoding for this ServletContext.
+     * <p>
+     * Implementations are strongly encouraged to override this default method and provide a more efficient implementation.
+     *
+     * @param encoding request character encoding
+     *
+     * @throws IllegalStateException if this ServletContext has already been initialized
+     *
+     * @throws UnsupportedOperationException if this ServletContext was passed to the
+     * {@link ServletContextListener#contextInitialized} method of a {@link ServletContextListener} that was neither
+     * declared in <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated with
+     * {@link jakarta.servlet.annotation.WebListener}
+     *
+     * @since Servlet 6.1
+     */
+    default public void setRequestCharacterEncoding(Charset encoding) {
+        setRequestCharacterEncoding(encoding.name());
+    }
+
     /**
      * Gets the response character encoding that are supported by default for this <tt>ServletContext</tt>. This method
      * returns null if no response encoding character encoding has been specified in deployment descriptor or container
@@ -1368,4 +1389,24 @@ public interface ServletContext {
      * @since Servlet 4.0
      */
     public void setResponseCharacterEncoding(String encoding);
+
+    /**
+     * Sets the response character encoding for this ServletContext.
+     * <p>
+     * Implementations are strongly encouraged to override this default method and provide a more efficient implementation.
+     *
+     * @param encoding response character encoding
+     *
+     * @throws IllegalStateException if this ServletContext has already been initialized
+     *
+     * @throws UnsupportedOperationException if this ServletContext was passed to the
+     * {@link ServletContextListener#contextInitialized} method of a {@link ServletContextListener} that was neither
+     * declared in <code>web.xml</code> or <code>web-fragment.xml</code>, nor annotated with
+     * {@link jakarta.servlet.annotation.WebListener}
+     *
+     * @since Servlet 6.1
+     */
+    default public void setResponseCharacterEncoding(Charset encoding) {
+        setResponseCharacterEncoding(encoding.name());
+    }
 }

api/src/main/java/jakarta/servlet/ServletRequest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2022 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -19,6 +19,7 @@
 package jakarta.servlet;
 
 import java.io.*;
+import java.nio.charset.Charset;
 import java.util.*;
 
 /**
@@ -83,12 +84,30 @@ public interface ServletRequest {
      * Overrides the name of the character encoding used in the body of this request. This method must be called prior to
      * reading request parameters or reading input using getReader(). Otherwise, it has no effect.
      * 
-     * @param env <code>String</code> containing the name of the character encoding.
+     * @param encoding <code>String</code> containing the name of the character encoding.
      *
      * @throws UnsupportedEncodingException if this ServletRequest is still in a state where a character encoding may be
      * set, but the specified encoding is invalid
      */
-    public void setCharacterEncoding(String env) throws UnsupportedEncodingException;
+    public void setCharacterEncoding(String encoding) throws UnsupportedEncodingException;
+
+    /**
+     * Overrides the character encoding used in the body of this request. This method must be called prior to reading
+     * request parameters or reading input using getReader(). Otherwise, it has no effect.
+     * <p>
+     * Implementations are strongly encouraged to override this default method and provide a more efficient implementation.
+     * 
+     * @param encoding <code>Charset</code> representing the character encoding.
+     * 
+     * @since Servlet 6.1
+     */
+    default public void setCharacterEncoding(Charset encoding) {
+        try {
+            setCharacterEncoding(encoding.name());
+        } catch (UnsupportedEncodingException e) {
+            // Unreachable code
+        }
+    }
 
     /**
      * Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not

api/src/main/java/jakarta/servlet/ServletRequestWrapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2022 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -21,6 +21,7 @@
 import java.io.BufferedReader;
 import java.io.IOException;
 import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
 import java.util.Enumeration;
 import java.util.Locale;
 import java.util.Map;
@@ -104,8 +105,16 @@ public String getCharacterEncoding() {
      * The default behavior of this method is to set the character encoding on the wrapped request object.
      */
     @Override
-    public void setCharacterEncoding(String enc) throws UnsupportedEncodingException {
-        this.request.setCharacterEncoding(enc);
+    public void setCharacterEncoding(String encoding) throws UnsupportedEncodingException {
+        this.request.setCharacterEncoding(encoding);
+    }
+
+    /**
+     * The default behavior of this method is to set the character encoding on the wrapped request object.
+     */
+    @Override
+    public void setCharacterEncoding(Charset encoding) {
+        this.request.setCharacterEncoding(encoding);
     }
 
     /**

api/src/main/java/jakarta/servlet/ServletResponse.java

@@ -21,6 +21,8 @@
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.util.Locale;
 
 /**
@@ -38,11 +40,12 @@
  * request, per web-app (using {@link ServletContext#setRequestCharacterEncoding}, deployment descriptor), and per
  * container (for all web applications deployed in that container, using vendor specific configuration). If multiple of
  * the preceding techniques have been employed, the priority is the order listed. For per request, the charset for the
- * response can be specified explicitly using the {@link #setCharacterEncoding} and {@link #setContentType} methods, or
- * implicitly using the {@link #setLocale} method. Explicit specifications take precedence over implicit specifications.
- * If no charset is explicitly specified, ISO-8859-1 will be used. The <code>setCharacterEncoding</code>,
- * <code>setContentType</code>, or <code>setLocale</code> method must be called before <code>getWriter</code> and before
- * committing the response for the character encoding to be used.
+ * response can be specified explicitly using the {@link #setCharacterEncoding(String)},
+ * {@link #setCharacterEncoding(Charset)} and {@link #setContentType} methods, or implicitly using the
+ * {@link #setLocale} method. Explicit specifications take precedence over implicit specifications. If no charset is
+ * explicitly specified, ISO-8859-1 will be used. The <code>setCharacterEncoding</code>, <code>setContentType</code>, or
+ * <code>setLocale</code> method must be called before <code>getWriter</code> and before committing the response for the
+ * character encoding to be used.
  * 
  * <p>
  * See the Internet RFCs such as <a href="http://www.ietf.org/rfc/rfc2045.txt"> RFC 2045</a> for more information on
@@ -60,10 +63,11 @@ public interface ServletResponse {
      * perweb-app (using {@link ServletContext#setResponseCharacterEncoding}, deployment descriptor), and per container (for
      * all web applications deployed in that container, using vendor specific configuration). The first one of these methods
      * that yields a result is returned. Per-request, the charset for the response can be specified explicitly using the
-     * {@link #setCharacterEncoding} and {@link #setContentType} methods, or implicitly using the
-     * setLocale(java.util.Locale) method. Explicit specifications take precedence over implicit specifications. Calls made
-     * to these methods after <code>getWriter</code> has been called or after the response has been committed have no effect
-     * on the character encoding. If no character encoding has been specified, <code>ISO-8859-1</code> is returned.
+     * {@link #setCharacterEncoding(String)}, {@link #setCharacterEncoding(Charset)} and {@link #setContentType} methods, or
+     * implicitly using the setLocale(java.util.Locale) method. Explicit specifications take precedence over implicit
+     * specifications. Calls made to these methods after <code>getWriter</code> has been called or after the response has
+     * been committed have no effect on the character encoding. If no character encoding has been specified,
+     * <code>ISO-8859-1</code> is returned.
      * <p>
      * See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information about character encoding and MIME.
      *
@@ -136,18 +140,19 @@ public interface ServletResponse {
     /**
      * Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8. If the
      * response character encoding has already been set by {@link ServletContext#setResponseCharacterEncoding}, the
-     * deployment descriptor, or using the {@link #setContentType} or {@link #setLocale} methods, the value set in this
-     * method overrides all of those values. Calling {@link #setContentType} with the <code>String</code> of
-     * <code>text/html</code> and calling this method with the <code>String</code> of <code>UTF-8</code> is equivalent to
-     * calling {@link #setContentType} with the <code>String</code> of <code>text/html; charset=UTF-8</code>.
+     * deployment descriptor, or using the {@link #setCharacterEncoding(Charset)}, {@link #setContentType} or
+     * {@link #setLocale} methods, the value set in this method overrides all of those values. Calling
+     * {@link #setContentType} with the <code>String</code> of <code>text/html</code> and calling this method with the
+     * <code>String</code> of <code>UTF-8</code> is equivalent to calling {@link #setContentType} with the
+     * <code>String</code> of <code>text/html; charset=UTF-8</code>.
      * <p>
      * This method can be called repeatedly to change the character encoding. This method has no effect if it is called
      * after <code>getWriter</code> has been called or after the response has been committed.
      * <p>
      * If calling this method has an effect (as per the previous paragraph), calling this method with {@code null} clears
-     * any character encoding set via a previous call to this method, {@link #setContentType} or {@link #setLocale} but does
-     * not affect any default character encoding configured via {@link ServletContext#setResponseCharacterEncoding} or the
-     * deployment descriptor.
+     * any character encoding set via a previous call to this method, {@link #setCharacterEncoding(Charset)},
+     * {@link #setContentType} or {@link #setLocale} but does not affect any default character encoding configured via
+     * {@link ServletContext#setResponseCharacterEncoding} or the deployment descriptor.
      * <p>
      * If this method is called with an invalid or unrecognised character encoding, then a subsequent call to
      * {@link #getWriter()} will throw a {@link UnsupportedEncodingException}. Content for an unknown encoding can be sent
@@ -161,15 +166,53 @@ public interface ServletResponse {
      * HTTP headers if the servlet does not specify a content type; however, it is still used to encode text written via the
      * servlet response's writer.
      *
-     * @param charset a String specifying only the character set defined by IANA Character Sets
+     * @param encoding a String specifying only the character set defined by IANA Character Sets
      * (http://www.iana.org/assignments/character-sets) or {@code null}
      *
+     * @see #setCharacterEncoding(Charset)
      * @see #setContentType
      * @see #setLocale
      *
      * @since Servlet 2.4
      */
-    public void setCharacterEncoding(String charset);
+    public void setCharacterEncoding(String encoding);
+
+    /**
+     * Sets the character encoding (MIME charset) of the response being sent to the client, for example, to UTF-8. If the
+     * response character encoding has already been set by {@link ServletContext#setResponseCharacterEncoding}, the
+     * deployment descriptor, or using the {@link #setCharacterEncoding(String)}, {@link #setContentType} or
+     * {@link #setLocale} methods, the value set in this method overrides all of those values. Calling
+     * {@link #setContentType} with the <code>String</code> of <code>text/html</code> and calling this method with
+     * {@link StandardCharsets#UTF_8} is equivalent to calling {@link #setContentType} with the <code>String</code> of
+     * <code>text/html; charset=UTF-8</code>.
+     * <p>
+     * This method can be called repeatedly to change the character encoding. This method has no effect if it is called
+     * after <code>getWriter</code> has been called or after the response has been committed.
+     * <p>
+     * If calling this method has an effect (as per the previous paragraph), calling this method with {@code null} clears
+     * any character encoding set via a previous call to this method, {@link #setCharacterEncoding(String)},
+     * {@link #setContentType} or {@link #setLocale} but does not affect any default character encoding configured via
+     * {@link ServletContext#setResponseCharacterEncoding} or the deployment descriptor.
+     * <p>
+     * Containers must communicate the character encoding used for the servlet response's writer to the client if the
+     * protocol provides a way for doing so. In the case of HTTP, the character encoding is communicated as part of the
+     * <code>Content-Type</code> header for text media types. Note that the character encoding cannot be communicated via
+     * HTTP headers if the servlet does not specify a content type; however, it is still used to encode text written via the
+     * servlet response's writer.
+     * <p>
+     * Implementations are strongly encouraged to override this default method and provide a more efficient implementation.
+     *
+     * @param encoding a Charset instance representing the encoding to use or {@code null}
+     *
+     * @see #setCharacterEncoding(String)
+     * @see #setContentType
+     * @see #setLocale
+     *
+     * @since Servlet 6.1
+     */
+    default public void setCharacterEncoding(Charset encoding) {
+        setCharacterEncoding(encoding.name());
+    }
 
     /**
      * Sets the length of the content body in the response In HTTP servlets, this method sets the HTTP Content-Length
@@ -208,8 +251,9 @@ public interface ServletResponse {
      * <p>
      * If calling this method has an effect (as per the previous paragraph), calling this method with {@code null} clears
      * any content type set via a previous call to this method and clears any character encoding set via a previous call to
-     * this method, {@link #setCharacterEncoding} or {@link #setLocale} but does not affect any default character encoding
-     * configured via {@link ServletContext#setResponseCharacterEncoding} or the deployment descriptor.
+     * this method, {@link #setCharacterEncoding(String)}, {@link #setCharacterEncoding(Charset)} or {@link #setLocale} but
+     * does not affect any default character encoding configured via {@link ServletContext#setResponseCharacterEncoding} or
+     * the deployment descriptor.
      * <p>
      * If this method is called with an invalid or unrecognised character encoding, then a subsequent call to
      * {@link #getWriter()} will throw a {@link UnsupportedEncodingException}. Content for an unknown encoding can be sent
@@ -224,7 +268,8 @@ public interface ServletResponse {
      * @param type a <code>String</code> specifying the MIME type of the content or {@code null}
      *
      * @see #setLocale
-     * @see #setCharacterEncoding
+     * @see #setCharacterEncoding(String)
+     * @see #setCharacterEncoding(Charset)
      * @see #getOutputStream
      * @see #getWriter
      *
@@ -328,15 +373,16 @@ public interface ServletResponse {
     /**
      * Sets the locale of the response, if the response has not been committed yet. It also sets the response's character
      * encoding appropriately for the locale, if the character encoding has not been explicitly set using
-     * {@link #setContentType} or {@link #setCharacterEncoding}, <code>getWriter</code> hasn't been called yet, and the
-     * response hasn't been committed yet. If the deployment descriptor contains a <code>locale-encoding-mapping-list</code>
-     * element, and that element provides a mapping for the given locale, that mapping is used. Otherwise, the mapping from
-     * locale to character encoding is container dependent.
+     * {@link #setContentType}, {@link #setCharacterEncoding(String)} or {@link #setCharacterEncoding(Charset)},
+     * <code>getWriter</code> hasn't been called yet, and the response hasn't been committed yet. If the deployment
+     * descriptor contains a <code>locale-encoding-mapping-list</code> element, and that element provides a mapping for the
+     * given locale, that mapping is used. Otherwise, the mapping from locale to character encoding is container dependent.
      * <p>
      * This method may be called repeatedly to change locale and character encoding. The method has no effect if called
      * after the response has been committed. It does not set the response's character encoding if it is called after
-     * {@link #setContentType} has been called with a charset specification, after {@link #setCharacterEncoding} has been
-     * called, after <code>getWriter</code> has been called, or after the response has been committed.
+     * {@link #setContentType} has been called with a charset specification, after {@link #setCharacterEncoding(String} has
+     * been called, after {@link #setCharacterEncoding(Charset} has been called, after <code>getWriter</code> has been
+     * called, or after the response has been committed.
      * <p>
      * If calling this method has an effect on the locale (as per the previous paragraph), calling this method with
      * {@code null} clears any locale set via a previous call to this method. If calling this method has an effect on the
@@ -352,7 +398,8 @@ public interface ServletResponse {
      *
      * @see #getLocale
      * @see #setContentType
-     * @see #setCharacterEncoding
+     * @see #setCharacterEncoding(String)
+     * @see #setCharacterEncoding(Charset)
      */
     public void setLocale(Locale loc);