/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2017-2017 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://oss.oracle.com/licenses/CDDL+GPL-1.1
* or LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.servlet;
/**
* Class that may be used to configure various properties of cookies
* used for session tracking purposes.
*
* <p>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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* <p>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 <tt>JSESSIONID</tt>,
* and therefore should only be done cautiously.
*
* @param name the cookie name to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> 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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* <p>By default, <tt>JSESSIONID</tt> will be used as the cookie name.
*
* @return the cookie name set via {@link #setName}, or
* <tt>null</tt> if {@link #setName} was never called
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @param domain the cookie domain to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @return the cookie domain set via {@link #setDomain}, or
* <tt>null</tt> if {@link #setDomain} was never called
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @param path the cookie path to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* <p>By default, the context path of the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired will
* be used.
*
* @return the cookie path set via {@link #setPath}, or <tt>null</tt>
* if {@link #setPath} was never called
*
* @see javax.servlet.http.Cookie#getPath()
*/
public
String getPath();
/**
* Sets the comment that will be assigned to any session tracking
* cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* <p>As a side effect of this call, the session tracking cookies
* will be marked with a <code>Version</code> attribute equal to
* <code>1</code>.
*
* @param comment the cookie comment to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.servlet.http.Cookie#setComment(String)
* @see javax.servlet.http.Cookie#getVersion
*/
public void
setComment(
String comment);
/**
* Gets the comment that will be assigned to any session tracking
* cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @return the cookie comment set via {@link #setComment}, or
* <tt>null</tt> if {@link #setComment} was never called
*
* @see javax.servlet.http.Cookie#getComment()
*/
public
String getComment();
/**
* Marks or unmarks the session tracking cookies created on behalf
* of the application represented by the <tt>ServletContext</tt> from
* which this <tt>SessionCookieConfig</tt> was acquired as
* <i>HttpOnly</i>.
*
* <p>A cookie is marked as <tt>HttpOnly</tt> by adding the
* <tt>HttpOnly</tt> attribute to it. <i>HttpOnly</i> 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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired shall be marked as <i>HttpOnly</i>, false otherwise
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.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 <tt>ServletContext</tt> from which
* this <tt>SessionCookieConfig</tt> was acquired will be marked as
* <i>HttpOnly</i>.
*
* @return true if the session tracking cookies created on behalf of
* the application represented by the <tt>ServletContext</tt> from
* which this <tt>SessionCookieConfig</tt> was acquired will be marked
* as <i>HttpOnly</i>, false otherwise
*
* @see javax.servlet.http.Cookie#isHttpOnly()
*/
public boolean
isHttpOnly();
/**
* Marks or unmarks the session tracking cookies created on behalf of
* the application represented by the <tt>ServletContext</tt> from which
* this <tt>SessionCookieConfig</tt> was acquired as <i>secure</i>.
*
* <p>One use case for marking a session tracking cookie as
* <tt>secure</tt>, 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 <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired shall be
* marked as <i>secure</i> even if the request that initiated the
* corresponding session is using plain HTTP instead of HTTPS, and false
* if they shall be marked as <i>secure</i> only if the request that
* initiated the corresponding session was also secure
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.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 <tt>ServletContext</tt> from which
* this <tt>SessionCookieConfig</tt> was acquired will be marked as
* <i>secure</i> 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 <tt>ServletContext</tt> from which
* this <tt>SessionCookieConfig</tt> was acquired will be marked as
* <i>secure</i> even if the request that initiated the corresponding
* session is using plain HTTP instead of HTTPS, and false if they will
* be marked as <i>secure</i> only if the request that initiated the
* corresponding session was also secure
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @param maxAge the lifetime (in seconds) of the session tracking
* cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* @throws IllegalStateException if the <tt>ServletContext</tt>
* from which this <tt>SessionCookieConfig</tt> was acquired has
* already been initialized
*
* @see javax.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
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired.
*
* <p>By default, <tt>-1</tt> is returned.
*
* @return the lifetime (in seconds) of the session tracking
* cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt>
* was acquired, or <tt>-1</tt> (the default)
*
* @see javax.servlet.http.Cookie#getMaxAge
*/
public int
getMaxAge();
}