String of text/html and
- * calling this method with the String of UTF-8 is equivalent with calling
- * setContentType with the String of text/html; charset=UTF-8.
+ * 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 String of
+ * text/html and calling this method with the String of UTF-8 is equivalent to
+ * calling {@link #setContentType} with the String of text/html; charset=UTF-8.
*
* This method can be called repeatedly to change the character encoding. This method has no effect if it is called
* after getWriter has been called or after the response has been committed.
*
+ * 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. + *
+ * 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()}. + *
+ * Containers may choose to log calls to this method that use an invalid or unrecognised character encoding. + *
* 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
* Content-Type header for text media types. Note that the character encoding cannot be communicated via
@@ -150,7 +162,7 @@ public interface ServletResponse {
* 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, text/html;charset=UTF-8. The
* response's character encoding is only set from the given content type if this method is called before
- * getWriter is called.
+ * {@link #getWriter()} is called.
*
* 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
* getWriter has been called or after the response has been committed.
*
+ * 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. + *
+ * 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()}. + *
+ * Containers may choose to log calls to this method that use an invalid or unrecognised character encoding. + *
* 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 Content-Type header is
* used.
*
- * @param type a String specifying the MIME type of the content
+ * @param type a String 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 getWriter has been called, or after the response has been committed.
*
+ * 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. + *
* 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
* Content-Language header, the character encoding as part of the Content-Type 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