Fix jakartaee#74 - provide more control over redirects

Author: markt-asf

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -145,9 +145,57 @@ public interface HttpServletResponse extends ServletResponse {
     public void sendError(int sc) throws IOException;
 
     /**
-     * Sends a temporary redirect response to the client using the specified redirect location URL and clears the buffer.
-     * The buffer will be replaced with the data set by this method. Calling this method sets the status code to
+     * Sends a temporary redirect response to the client using the specified redirect location URL using the status code
+     * {@link #SC_FOUND} 302 (Found) and clears the buffer. The buffer will be replaced with the data set by this method.
+     *
+     * @param location the redirect location URL
+     * 
+     * @exception IOException If an input or output exception occurs
+     * @exception IllegalStateException If the response was committed or if a partial URL is given and cannot be converted
+     * into a valid URL
+     * 
+     * @see #sendRedirect(String, int, boolean)
+     */
+    public default void sendRedirect(String location) throws IOException {
+        sendRedirect(location, SC_FOUND, true);
+    }
+
+    /**
+     * Sends a temporary redirect response to the client using the specified redirect location URL using the status code
      * {@link #SC_FOUND} 302 (Found).
+     *
+     * @param location the redirect location URL
+     * @param clearBuffer if {@code true}, clear the buffer and replace it with the data set by this method otherwise retain
+     * the existing buffer
+     * 
+     * @exception IOException If an input or output exception occurs
+     * @exception IllegalStateException If the response was committed or if a partial URL is given and cannot be converted
+     * into a valid URL
+     * 
+     * @see #sendRedirect(String, int, boolean)
+     */
+    public default void sendRedirect(String location, boolean clearBuffer) throws IOException {
+        sendRedirect(location, SC_FOUND, clearBuffer);
+    }
+
+    /**
+     * Sends a temporary redirect response to the client using the specified redirect location URL using the given status
+     * code and clears the buffer. The buffer will be replaced with the data set by this method.
+     *
+     * @param location the redirect location URL
+     * @param sc the status code to use for the redirect
+     * 
+     * @exception IOException If an input or output exception occurs
+     * @exception IllegalStateException If the response was committed or if a partial URL is given and cannot be converted
+     * into a valid URL
+     * 
+     * @see #sendRedirect(String, int, boolean)
+     */
+    public default void sendRedirect(String location, int sc) throws IOException {
+        sendRedirect(location, sc, true);
+    }
+
+    /**
      * <p>
      * This method accepts both relative and absolute URLs. Absolute URLs passed to this method are used as provided as the
      * redirect location URL. Relative URLs are converted to absolute URLs unless a container specific feature/option is
@@ -162,17 +210,21 @@ public interface HttpServletResponse extends ServletResponse {
      * <a href="http://www.ietf.org/rfc/rfc3986.txt"> RFC 3986: Uniform Resource Identifier (URI): Generic Syntax</a>,
      * section 4.2 &quot;Relative Reference&quot;).</li>
      * </ul>
-     *
+     * 
      * <p>
      * If the response has already been committed, this method throws an IllegalStateException. After using this method, the
      * response should be considered to be committed and should not be written to.
-     *
+     * 
      * @param location the redirect location URL
+     * @param sc the status code to use for the redirect
+     * @param clearBuffer if {@code true}, clear the buffer and replace it with the data set by this method otherwise retain
+     * the existing buffer
+     * 
      * @exception IOException If an input or output exception occurs
      * @exception IllegalStateException If the response was committed or if a partial URL is given and cannot be converted
      * into a valid URL
      */
-    public void sendRedirect(String location) throws IOException;
+    public void sendRedirect(String location, int sc, boolean clearBuffer) throws IOException;
 
     /**
      * Sets a response header with the given name and date-value. The date is specified in terms of milliseconds since the

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2021 Oracle and/or its affiliates and others.
+ * Copyright (c) 1997, 2023 Oracle and/or its affiliates and others.
  * All rights reserved.
  * Copyright 2004 The Apache Software Foundation
  *
@@ -108,6 +108,33 @@ public void sendRedirect(String location) throws IOException {
         this._getHttpServletResponse().sendRedirect(location);
     }
 
+    /**
+     * The default behavior of this method is to return sendRedirect(String location, int sc) on the wrapped response
+     * object.
+     */
+    @Override
+    public void sendRedirect(String location, int sc) throws IOException {
+        this._getHttpServletResponse().sendRedirect(location, sc);
+    }
+
+    /**
+     * The default behavior of this method is to return sendRedirect(String location, boolean clearBuffer) on the wrapped
+     * response object.
+     */
+    @Override
+    public void sendRedirect(String location, boolean clearBuffer) throws IOException {
+        this._getHttpServletResponse().sendRedirect(location, clearBuffer);
+    }
+
+    /**
+     * The default behavior of this method is to return sendRedirect(String location, int sc, boolean clearBuffer) on the
+     * wrapped response object.
+     */
+    @Override
+    public void sendRedirect(String location, int sc, boolean clearBuffer) throws IOException {
+        this._getHttpServletResponse().sendRedirect(location, sc, clearBuffer);
+    }
+
     /**
      * The default behavior of this method is to call setDateHeader(String name, long date) on the wrapped response object.
      */

api/src/test/java/jakarta/servlet/http/MockHttpServletResponse.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Contributors to the Eclipse Foundation.
+ * Copyright (c) 2023 Contributors to the Eclipse Foundation.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -56,6 +56,21 @@ public void sendRedirect(String location) throws IOException {
 
     }
 
+    @Override
+    public void sendRedirect(String location, boolean clearBuffer) throws IOException {
+
+    }
+
+    @Override
+    public void sendRedirect(String location, int sc) throws IOException {
+
+    }
+
+    @Override
+    public void sendRedirect(String location, int sc, boolean clearBuffer) throws IOException {
+
+    }
+
     @Override
     public void setDateHeader(String name, long date) {
 

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

@@ -2499,14 +2499,14 @@ The following convenience methods exist in the
 
 * `sendError`
 
-The `sendRedirect` method will set the appropriate headers and content body to
+The `sendRedirect` methods will set the appropriate headers and content body to
 redirect the client to a different URL.
-It is legal to call this method with a relative URL path.
+It is legal to call these methods with a relative URL path.
 The underlying container may provide an option to use the relative URL path as
 provided but if no such option is provided it must translate the relative path
 to a fully qualified URL for transmission back to the client.
 If a partial URL is given and, for whatever reason, cannot be converted into a
-valid URL, then this method must throw an `IllegalArgumentException`.
+valid URL, then these methods must throw an `IllegalArgumentException`.
 
 The `sendError` method will set the
 appropriate headers and content body for an error message to return to
@@ -8541,6 +8541,11 @@ link:https://github.com/eclipse-ee4j/servlet-api/issues/59[Issue 59]::
 A new attribute, `jakarta.servlet.error.query_string`, has been added to the
 attributes that must be set on the request as part of an error dispatch.
 
+link:https://github.com/eclipse-ee4j/servlet-api/issues/74[Issue 74]::
+Add additional methods to `HttpServeltResponse` to allow the status code used
+with the redirect to be chosen and/or the response body used for the redirect to
+be controlled.
+ 
 link:https://github.com/eclipse-ee4j/servlet-api/issues/95[Issue 95]::
 Clarify that Servlet containers are required to support HTTPS.