jakartaee#175 Add support for SameSite cookies

Signed-off-by: Peter Major <peter.major@forgerock.com>

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

@@ -92,6 +92,7 @@ public class Cookie implements Cloneable, Serializable {
     private boolean secure; // ;Secure ... e.g. use SSL
     private int version = 0; // ;Version=1 ... means RFC 2109++ style
     private boolean isHttpOnly = false;
+    private SameSiteMode sameSiteMode = null;
 
     /**
      * Constructs a cookie with the specified name and value.
@@ -422,4 +423,82 @@ public void setHttpOnly(boolean isHttpOnly) {
     public boolean isHttpOnly() {
         return isHttpOnly;
     }
+
+    /**
+     * Sets the <i>SameSite</i> flag for this cookie with the provided value.
+     *
+     * <p>
+     *     When <code>sameSiteMode</code> is not <code>null</code>, this cookie will have its <code>SameSite</code>
+     *     attribute set with the provided value.
+     * </p>
+     *
+     * @param sameSiteMode The <i>SameSite</i> attribute's value. May be null if the attribute should not be set.
+     *
+     * @since Servlet 4.x
+     */
+    public void setSameSiteMode(SameSiteMode sameSiteMode) {
+        this.sameSiteMode = sameSiteMode;
+    }
+
+    /**
+     * Returns the <i>SameSite</i>> mode associated with this cookie.
+     *
+     * @return The <i>SameSite</i> mode associated with this cookie. May be null.
+     *
+     * @since Servlet 4.x
+     */
+    public SameSiteMode getSameSiteMode() {
+        return sameSiteMode;
+    }
+
+    /**
+     * The available values that can be used with the cookie's <i>SameSite</i> attribute.
+     */
+    public enum SameSiteMode {
+
+        /**
+         * This mode effectively disables the protection provided by SameSite cookies.
+         *
+         * <p>
+         *     When SameSiteMode is {@literal None}, applications should have additional measures to protect cookies
+         *     from CSRF attacks.
+         * </p>
+         *
+         * <p>
+         *     Browsers may default to {@link SameSiteMode#Lax} or {@link SameSiteMode#Strict} when the flag is not
+         *     explicitly set by applications in the Set-Cookie header. Setting the {@literal SameSite} flag to
+         *     {@literal None} ensures that this default behavior is disabled in browsers.
+         * </p>
+         *
+         * <p>
+         *     Note that this mode is browser dependent, and browsers may require cookies to have the {@literal Secure}
+         *     flag to be set at the same time.
+         * </p>
+         */
+        None,
+        /**
+         * This mode allows sending cookies along for cross-site top level navigation requests.
+         *
+         * <p>
+         *     When SameSiteMode is {@literal Lax}, the browser is allowed to send the cookie value along with top level
+         *     navigation requests when making requests cross-site.
+         * </p>
+         */
+        Lax,
+        /**
+         * This mode prevents browsers from sending cookies along with any kind of cross-site requests.
+         *
+         * <p>
+         *     When SameSiteMode is {@literal Strict}, the browser is not allowed to send the cookie value along with
+         *     cross-site requests.
+         * </p>
+         *
+         * <p>
+         *     This behaviour could prevent applications seeing the end-user's session when a cross-site navigation
+         *     takes place. To overcome this, applications should consider utilising multiple cookies to keep track of
+         *     sessions.
+         * </p>
+         */
+        Strict
+    }
 }