Fix #377 - clarify setCharacterEncoding(null) and related

Signed-off-by: Mark Thomas <[email protected]>

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -20,6 +20,7 @@
 
 import java.io.IOException;
 import java.io.PrintWriter;
+import java.io.UnsupportedEncodingException;
 import java.util.Locale;
 
 /**
@@ -134,23 +135,34 @@ 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 the {@link ServletContext#setResponseCharacterEncoding},
-     * deployment descriptor, or using the setContentType() or setLocale() methods, the value set in this method overrides
-     * any 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 with calling
-     * <code>setContentType</code> with the <code>String</code> of <code>text/html; charset=UTF-8</code>.
+     * 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>.
      * <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.
+     * <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
+     * with the {@link ServletOutputStream} returned from {@link #getOutputStream()}.
+     * <p>
+     * Containers may choose to log calls to this method that use an invalid or unrecognised character encoding.
+     * <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.
      *
      * @param charset a String specifying only the character set defined by IANA Character Sets
-     * (http://www.iana.org/assignments/character-sets)
+     * (http://www.iana.org/assignments/character-sets) or {@code null}
      *
      * @see #setContentType
      * @see #setLocale
@@ -182,17 +194,28 @@ public interface ServletResponse {
      * Sets the content type of the response being sent to the client, if the response has not been committed yet. The given
      * content type may include a character encoding specification, for example, <code>text/html;charset=UTF-8</code>. The
      * response's character encoding is only set from the given content type if this method is called before
-     * <code>getWriter</code> is called.
+     * {@link #getWriter()} is called.
      * <p>
      * This method may be called repeatedly to change content type and character encoding. This 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
      * <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 content type set via a previous call to this method and 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.
+     * <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
+     * with the {@link ServletOutputStream} returned from {@link #getOutputStream()}.
+     * <p>
+     * Containers may choose to log calls to this method that use an invalid or unrecognised character encoding.
+     * <p>
      * Containers must communicate the content type and 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 <code>Content-Type</code> header is
      * used.
      *
-     * @param type a <code>String</code> specifying the MIME type of the content
+     * @param type a <code>String</code> specifying the MIME type of the content or {@code null}
      *
      * @see #setLocale
      * @see #setCharacterEncoding
@@ -309,13 +332,17 @@ public interface ServletResponse {
      * {@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.
      * <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
+     * character encoding, calling this method with {@code null} clears the previously set character encoding.
+     * <p>
      * Containers must communicate the locale and 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 locale is communicated via the
      * <code>Content-Language</code> header, the character encoding 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.
      * 
-     * @param loc the locale of the response
+     * @param loc the locale of the response or {code @null}
      *
      * @see #getLocale
      * @see #setContentType