* An instance of this class is acquired by a call to {@link ServletContext#getSessionCookieConfig}. * * @since Servlet 3.0 */ public interface SessionCookieConfig { /** * Sets the name that will be assigned to any session tracking cookies created on behalf of the application represented * by the ServletContext from which this SessionCookieConfig was acquired. * *
* NOTE: Changing the name of session tracking cookies may break other tiers (for example, a load balancing frontend) * that assume the cookie name to be equal to the default JSESSIONID, and therefore should only be done * cautiously. * * @param name the cookie name to use * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized */ public void setName(String name); /** * Gets the name that will be assigned to any session tracking cookies created on behalf of the application represented * by the ServletContext from which this SessionCookieConfig was acquired. * *
* By default, JSESSIONID will be used as the cookie name. * * @return the cookie name set via {@link #setName}, or null if {@link #setName} was never called * * @see jakarta.servlet.http.Cookie#getName() */ public String getName(); /** * Sets the domain name that will be assigned to any session tracking cookies created on behalf of the application * represented by the ServletContext from which this SessionCookieConfig was acquired. * * @param domain the cookie domain to use * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setDomain(String) */ public void setDomain(String domain); /** * Gets the domain name that will be assigned to any session tracking cookies created on behalf of the application * represented by the ServletContext from which this SessionCookieConfig was acquired. * * @return the cookie domain set via {@link #setDomain}, or null if {@link #setDomain} was never called * * @see jakarta.servlet.http.Cookie#getDomain() */ public String getDomain(); /** * Sets the path that will be assigned to any session tracking cookies created on behalf of the application represented * by the ServletContext from which this SessionCookieConfig was acquired. * * @param path the cookie path to use * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setPath(String) */ public void setPath(String path); /** * Gets the path that will be assigned to any session tracking cookies created on behalf of the application represented * by the ServletContext from which this SessionCookieConfig was acquired. * *
* By default, the context path of the ServletContext from which this SessionCookieConfig was acquired * will be used. * * @return the cookie path set via {@link #setPath}, or null if {@link #setPath} was never called * * @see jakarta.servlet.http.Cookie#getPath() */ public String getPath(); /** * With the adoption of support for RFC 6265, this method should no longer be used. *
* If called, this method has no effect. * * @param comment ignore * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setComment(String) * @see jakarta.servlet.http.Cookie#getVersion * * @deprecated This is no longer required with RFC 6265 */ @Deprecated(since = "Servlet 6.0", forRemoval = true) public void setComment(String comment); /** * With the adoption of support for RFC 6265, this method should no longer be used. * * @return Always {@code null} * * @see jakarta.servlet.http.Cookie#getComment() * * @deprecated This is no longer required with RFC 6265 */ @Deprecated(since = "Servlet 6.0", forRemoval = true) public String getComment(); /** * Marks or unmarks the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired as HttpOnly. * *
* A cookie is marked as HttpOnly by adding the HttpOnly attribute to it. HttpOnly cookies are * not supposed to be exposed to client-side scripting code, and may therefore help mitigate certain kinds of cross-site * scripting attacks. * * @param httpOnly true if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired shall be marked as HttpOnly, * false otherwise * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setHttpOnly(boolean) */ public void setHttpOnly(boolean httpOnly); /** * Checks if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired will be marked as HttpOnly. * * @return true if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired will be marked as HttpOnly, * false otherwise * * @see jakarta.servlet.http.Cookie#isHttpOnly() */ public boolean isHttpOnly(); /** * Marks or unmarks the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired as secure. * *
* One use case for marking a session tracking cookie as secure, even though the request that initiated the * session came over HTTP, is to support a topology where the web container is front-ended by an SSL offloading load * balancer. In this case, the traffic between the client and the load balancer will be over HTTPS, whereas the traffic * between the load balancer and the web container will be over HTTP. * * @param secure true if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired shall be marked as secure * even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS, and false if they * shall be marked as secure only if the request that initiated the corresponding session was also secure * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setSecure(boolean) * @see ServletRequest#isSecure() */ public void setSecure(boolean secure); /** * Checks if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired will be marked as secure * even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS. * * @return true if the session tracking cookies created on behalf of the application represented by the * ServletContext from which this SessionCookieConfig was acquired will be marked as secure * even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS, and false if they * will be marked as secure only if the request that initiated the corresponding session was also secure * * @see jakarta.servlet.http.Cookie#getSecure() * @see ServletRequest#isSecure() */ public boolean isSecure(); /** * Sets the lifetime (in seconds) for the session tracking cookies created on behalf of the application represented by * the ServletContext from which this SessionCookieConfig was acquired. * * @param maxAge the lifetime (in seconds) of the session tracking cookies created on behalf of the application * represented by the ServletContext from which this SessionCookieConfig was acquired. * * @throws IllegalStateException if the ServletContext from which this SessionCookieConfig was * acquired has already been initialized * * @see jakarta.servlet.http.Cookie#setMaxAge */ public void setMaxAge(int maxAge); /** * Gets the lifetime (in seconds) of the session tracking cookies created on behalf of the application represented by * the ServletContext from which this SessionCookieConfig was acquired. * *
* By default, -1 is returned.
*
* @return the lifetime (in seconds) of the session tracking cookies created on behalf of the application represented by
* the ServletContext from which this SessionCookieConfig was acquired, or -1 (the default)
*
* @see jakarta.servlet.http.Cookie#getMaxAge
*/
public int getMaxAge();
/**
* Sets the value for the given session cookie attribute. When a value is set via this method, the value returned by the
* attribute specific getter (if any) must be consistent with the value set via this method.
*
* @param name Name of attribute to set, case insensitive
* @param value Value of attribute
*
* @throws IllegalStateException if the associated ServletContext has already been initialised
*
* @throws IllegalArgumentException If the attribute name is null or contains any characters not permitted for use in
* Cookie names.
*
* @throws NumberFormatException If the attribute is known to be numerical but the provided value cannot be parsed to a
* number.
*
* @since Servlet 6.0
*/
public void setAttribute(String name, String value);
/**
* Obtain the value for a given session cookie attribute. Values returned from this method must be consistent with the
* values set and returned by the attribute specific getters and setters in this class.
*
* @param name Name of attribute to return, case insensitive
*
* @return Value of specified attribute
*
* @since Servlet 6.0
*/
public String getAttribute(String name);
/**
* Obtain the Map (keys are case insensitive) of all attributes and values, including those set via the attribute
* specific setters, (excluding version) for this SessionCookieConfig.
*
* @return A read-only Map of attributes to values, excluding version.
*
* @since Servlet 6.0
*/
public Map