/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.venice.ui.helpers;

import java.util.Set;

public interface CookieControl
{
  /**
   * Tests for the presence of a particular cookie.
   *
   * @param name Name of the cookie to test for existence.
   * @return <CODE>true</CODE> if a cookie by this name is present, <CODE>false</CODE> if not.
   */
  public abstract boolean isCookiePresent(String name);

  /**
   * Returns the value of a particular request cookie.
   *
   * @param name Name of the cookie to retrieve the value of.
   * @return The value of that cookie, or <CODE>null</CODE> if the cookie is not present.
   */
  public abstract String getCookie(String name);

  /**
   * Returns a set containing all the cookie names associated with this request.
   *
   * @return See above.
   */
  public abstract Set getCookieNames();

  /**
   * Adds a new persistent cookie to the application.  The cookie will be stored by the
   * browser's persistent storage facility.<P>
   * Cookies should be used <EM>sparingly</EM>, to avoid possible privacy concerns.
   *
   * @param name Name of the cookie to be set.
   * @param value Value of the cookie to be set.
   * @param max_age The maximum lifespan of the persistent cookie, in seconds.
   */
  public abstract void savePersistentCookie(String name, String value, int max_age);

  /**
   * Adds a new temporary cookie to the application.  The cookie will be stored in the
   * browser's memory only, and will disappear when the browser is closed.
   * Cookies should be used <EM>sparingly</EM>, to avoid possible privacy concerns.
   *
   * @param name Name of the cookie to be set.
   * @param value Value of the cookie to be set.
   */
  public abstract void saveTemporaryCookie(String name, String value);

  /**
   * Deletes a cookie (either persistent or temporary) from the application.  The cookie
   * will be erased from the browser.
   *
   * @param name Name of the cookie to remove.
   */
  public abstract void deleteCookie(String name);

} // end interface CookieControl
