Fix jakartaee#159 - Clarify behaviour of header methods with null or ""

api/src/main/java/jakarta/servlet/http/HttpServletResponse.java

@@ -175,12 +175,13 @@ public interface HttpServletResponse extends ServletResponse {
     public void sendRedirect(String location) throws IOException;
 
     /**
-     * 
      * Sets a response header with the given name and date-value. The date is specified in terms of milliseconds since the
-     * epoch. If the header had already been set, the new value overwrites the previous one. The <code>containsHeader</code>
+     * epoch. If the header had already been set, the new value overwrites all previous values. The <code>containsHeader</code>
      * method can be used to test for the presence of a header before setting its value.
      * <p>
      * This method has no effect if called after the response has been committed.
+     * <p>
+     * This method has no effect if {@code null} is passed for the {@code name} parameter.
      * 
      * @param name the name of the header to set
      * @param date the assigned date value
@@ -191,11 +192,12 @@ public interface HttpServletResponse extends ServletResponse {
     public void setDateHeader(String name, long date);
 
     /**
-     * 
      * Adds a response header with the given name and date-value. The date is specified in terms of milliseconds since the
      * epoch. This method allows response headers to have multiple values.
      * <p>
      * This method has no effect if called after the response has been committed.
+     * <p>
+     * This method has no effect if {@code null} is passed for the {@code name} parameter.
      * 
      * @param name the name of the header to set
      * @param date the additional date value
@@ -205,13 +207,18 @@ public interface HttpServletResponse extends ServletResponse {
     public void addDateHeader(String name, long date);
 
     /**
-     *
      * Sets a response header with the given name and value. If the header had already been set, the new value overwrites
-     * the previous one. The <code>containsHeader</code> method can be used to test for the presence of a header before
+     * all previous values. The <code>containsHeader</code> method can be used to test for the presence of a header before
      * setting its value.
      * <p>
      * This method has no effect if called after the response has been committed.
-     * 
+     * <p>
+     * This method has no effect if {@code null} is passed for the {@code name} parameter.
+     * <p>
+     * Passing {@code null} as the value removes all headers with the given name.
+     * <p>
+     * Note that the empty string is a valid header value.
+     *  
      * @param name the name of the header
      * @param value the header value If it contains octet string, it should be encoded according to RFC 2047
      * (http://www.ietf.org/rfc/rfc2047.txt)
@@ -223,6 +230,12 @@ public interface HttpServletResponse extends ServletResponse {
 
     /**
      * Adds a response header with the given name and value. This method allows response headers to have multiple values.
+     * <p>
+     * This method has no effect if called after the response has been committed.
+     * <p>
+     * This method has no effect if {@code null} is passed for either the {@code name} or {@code value} parameters.
+     * <p>
+     * Note that the empty string is a valid header value.
      * 
      * @param name the name of the header
      * @param value the additional header value If it contains octet string, it should be encoded according to RFC 2047
@@ -234,10 +247,12 @@ public interface HttpServletResponse extends ServletResponse {
 
     /**
      * Sets a response header with the given name and integer value. If the header had already been set, the new value
-     * overwrites the previous one. The <code>containsHeader</code> method can be used to test for the presence of a header
+     * overwrites all previous values. The <code>containsHeader</code> method can be used to test for the presence of a header
      * before setting its value.
      * <p>
      * This method has no effect if called after the response has been committed.
+     * <p>
+     * This method has no effect if {@code null} is passed for the {@code name} parameter.
      *
      * @param name the name of the header
      * @param value the assigned integer value
@@ -252,6 +267,8 @@ public interface HttpServletResponse extends ServletResponse {
      * values.
      * <p>
      * This method has no effect if called after the response has been committed.
+     * <p>
+     * This method has no effect if {@code null} is passed for the {@code name} parameter.
      *
      * @param name the name of the header
      * @param value the assigned integer value

spec/src/main/asciidoc/servlet-spec-body.adoc

@@ -8553,6 +8553,10 @@ attributes that must be set on the request as part of an error dispatch.
 link:https://github.com/eclipse-ee4j/servlet-api/issues/95[Issue 95]::
 Clarify that Servlet containers are required to support HTTPS.
 
+link:https://github.com/eclipse-ee4j/servlet-api/issues/159[Issue 159]::
+Clarify the behaviour of the various methods for adding headers when passed
+`null` or the empty string.
+
 link:https://github.com/eclipse-ee4j/servlet-api/issues/164[Issue 164]::
 Clarify Javadoc for `ServletResponse` and `HttpServletResponse` methods that are
 NO-OPs once the response has been committed.