home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Sambar Server.exe / _SETUP.1 / javaeng.jar / javax / servlet / http / Cookie.java < prev    next >
Encoding:
Java Source  |  2000-04-03  |  8.2 KB  |  323 lines
  1. /*
  2.  * Cookie.java -- Holds state information between requests and between session
  3.  *
  4.  * Copyright (c) 1998, 1999 by Free Software Foundation, Inc.
  5.  * Written by Paul Siegmann (pauls@euronet.nl)
  6.  *
  7.  * This program is free software; you can redistribute it and/or modify
  8.  * it under the terms of the GNU Library General Public License as published
  9.  * by the Free Software Foundation, version 2. (see COPYING.LIB)
  10.  *
  11.  * This program is distributed in the hope that it will be useful, but
  12.  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with this program; if not, write to the Free Software Foundation
  18.  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307 USA
  19.  */
  20. package javax.servlet.http;
  21.  
  22.  
  23. /**
  24.  * A cookie is basically a {String,String} name/value pair that the server tells
  25.  * the client to remember and to send back to him attached to every future
  26.  * request.<BR>
  27.  * Using cookies a server can maintain a state in between client requests.
  28.  * <P>
  29.  * A formal specification of Cookies can be found in RFC 2109
  30.  * ("HTTP State Management Mechanism")
  31.  *
  32. #ifdef SERVLET_2_0
  33.  * @version Servlet API 2.0 
  34. #endif
  35. #ifdef SERVLET_2_1
  36.  * @version Servlet API 2.1
  37. #endif
  38. #ifdef SERVLET_2_2
  39.  * @version Servlet API 2.2
  40. #endif
  41.  * @since Servlet API 2.0
  42.  * @author Paul Siegmann (pauls@euronet.nl)
  43.  */
  44. public class Cookie
  45.     implements Cloneable 
  46. {
  47.     private String myName;
  48.     private String myValue;
  49.     private String myComment = null;
  50.     private String myDomain = null;
  51.     private int myMaxAge = -1;
  52.     private String myPath = null;
  53.     private boolean mySecure = false;
  54.     private int myVersion = 0;
  55.  
  56.     private static String validChars = // Valid HTTP/1.1 token characters
  57. "!#$%&'*+-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ^_`abcdefghijklmnopqrstuvwxyz|~";
  58.  
  59.     /**
  60.      * Creates a cookie with a name and a value.
  61.      * The name must be a valid HTTP/1.1 token and not start with $.
  62.      *
  63.      * @since Servlet API 2.0
  64.      *
  65.      * @param name The name of the cookie
  66.      * @param value The value of the cookie
  67.      * @exception IllegalArgumentException if name is not a valid HTTP/1.1 token
  68.      *    or starts with $
  69.      */
  70.     public Cookie(String name, String value) throws IllegalArgumentException {
  71.         if(name.length() == 0) {
  72.             throw new IllegalArgumentException("Empty names are not allowed");
  73.         }
  74.         if(name.charAt(0) == '$') {
  75.             throw new IllegalArgumentException(
  76.                             "'$' not allowed as first char of Cookie name");
  77.         }
  78.         for(int i = 0; i < name.length(); i++) {
  79.             if (validChars.indexOf(name.charAt(i)) == -1) {
  80.                 throw new IllegalArgumentException("Character '" +
  81.                                         name.charAt(i) +
  82.                                         "' is not a valid HTTP/1.1 token");
  83.             }
  84.         }
  85.  
  86.         myName = name;
  87.         myValue = value;
  88.     }
  89.  
  90.     /**
  91.      * Gets the comment of the cookie
  92.      *
  93.      * @since Servlet API 2.0
  94.      *
  95.      * @return the comment or null if not defined
  96.      */
  97.     public String getComment() {
  98.         return myComment;
  99.     }
  100.  
  101.  
  102.     /**
  103.      * Gets this cookie's domain
  104.      *
  105.      * @since Servlet API 2.0
  106.      *
  107.      * @return The domain for which this cookie will be used or null if not
  108.      *    defined
  109.      */
  110.     public String getDomain() {
  111.         return myDomain;
  112.     }
  113.  
  114.  
  115.     /**
  116.      * Gets the time-to-live for this cookie, in seconds.<BR>
  117.      * If it is 0 then the client will delete the cookie.<BR>
  118.      * If it is -1 (which is the default) then the cookie will
  119.      * be a non-persistent cookie.<BR>
  120.      * This means that the cookie will live as long as the http
  121.      * client lives, and will not be saved to disk.
  122.      * 
  123.      * @since Servlet API 2.0
  124.      *
  125.      * @return the number of seconds to live or -1
  126.      */
  127.     public int getMaxAge() {
  128.         return myMaxAge;
  129.     }
  130.  
  131.  
  132.     /**
  133.      * Get the name
  134.      *
  135.      * @since Servlet API 2.0
  136.      *
  137.      * @return the Name
  138.      */
  139.     public String getName() {
  140.         return myName;
  141.     }
  142.  
  143.  
  144.     /**
  145.      * Gets the path for which requests this cookie will be attached.
  146.      * The domain/path pair determines with which requests the cookie
  147.      * will be sent to the server.<BR>
  148.      * Example:<BR>
  149.      * When a client receives a Cookie on requesting "/products/" then
  150.      * the path will be "/products/", and this Cookie will be attached
  151.      * to every request for "/products/" and any of its subdirectories.
  152.      *
  153.      * @since Servlet API 2.0
  154.      *
  155.      * @return the path or null if not defined
  156.      */
  157.     public String getPath() {
  158.         return myPath;
  159.     }
  160.  
  161.  
  162.     /**
  163.      * Whether only secure means (https) should be used when sending this
  164.      * cookie to a server.
  165.      *
  166.      * @since Servlet API 2.0
  167.      *
  168.      * @return whether this cookie should be secure or not
  169.      */
  170.     public boolean getSecure() {
  171.         return mySecure;
  172.     }
  173.  
  174.  
  175.     /**
  176.      * Gets the value
  177.      *
  178.      * @since Servlet API 2.0
  179.      *
  180.      * @return the Value
  181.      */
  182.     public String getValue() {
  183.         return myValue;
  184.     }
  185.  
  186.  
  187.     /**
  188.      * Gets the version of this cookie.
  189.      * The current type of cookies have version = 1, according to rfc2109.
  190.      * There have been slightly different (netscape only) types of cookies,
  191.      * but these days everyone uses version 1.
  192.      * Fresh cookies however get a default version of 0, to improve
  193.      * interoperability.
  194.      *
  195.      * @since Servlet API 2.0
  196.      *
  197.      * @return the version
  198.      */
  199.     public int getVersion() {
  200.         return myVersion;
  201.     }
  202.  
  203.  
  204.     /**
  205.      * Sets the comment of the cookie.
  206.      * Not supported by version 0 cookies.
  207.      *
  208.      * @since Servlet API 2.0
  209.      *
  210.      * @param comment the comment to be
  211.      */
  212.     public void setComment(String comment) {
  213.         myComment = comment;
  214.     }
  215.  
  216.  
  217.  
  218.     /**
  219.      * Sets the domain for which this Cookie will be used.
  220.      * If the domain is for instance set to .foo_bar.com then the client
  221.      * sends the cookie along with requests to all webservers whose domain
  222.      * ends with ".foo_bar.com" (www.foo_bar.com, blah.foo_bar.com, etc).
  223.      * If not set cookies are only returned to the domain from which the client
  224.      * received the cookie.
  225.      *
  226.      * @since Servlet API 2.0
  227.      *
  228.      * @param domain The cookie's domain
  229.      */
  230.     public void setDomain(String domain) {
  231.         myDomain = domain;
  232.     }
  233.  
  234.  
  235.     /**
  236.      * Sets the maximum lifetime of the cookie in seconds.<BR>
  237.      * If set to 0 then the cookie will be deleted by the client.<BR>
  238.      * If set to a negative value (such as -1 which is the default)
  239.      * then the cookie will
  240.      * be a non-persistent cookie.<BR>
  241.      * This means that the cookie will live as long as the http
  242.      * client lives, and will not be saved to disk.
  243.      *
  244.      * @since Servlet API 2.0
  245.      *
  246.      * @param maxAge The time-to-live for the cookie, in seconds
  247.      */
  248.     public void setMaxAge(int maxAge) {
  249.         myMaxAge = maxAge;
  250.     }
  251.  
  252.  
  253.     /**
  254.      * Set the path with which requests this cookie will be sent back to
  255.      * the server.
  256.      * The domain/path pair determines with which requests the cookie
  257.      * will be sent to the server.<BR>
  258.      * Defaults to path the client requested when it got this cookie.<BR>
  259.      * Example:<BR>
  260.      * When a client receives a Cookie on requesting "/products/" then
  261.      * the path will be "/products/", and this Cookie will be attached
  262.      * to every request for "/products/" and any of its subdirectories.
  263.      *
  264.      * @since Servlet API 2.0
  265.      *
  266.      * @param path the path
  267.      */
  268.     public void setPath(String path) {
  269.         myPath = path;
  270.     }
  271.  
  272.  
  273.     /**
  274.      * Whether only secure means (https) should be used when sending this
  275.      * cookie to a server.
  276.      *
  277.      * @since Servlet API 2.0
  278.      *
  279.      * @param secure whether this cookie should be secure or not.
  280.      */
  281.     public void setSecure(boolean secure) {
  282.         mySecure = secure;
  283.     }
  284.  
  285.  
  286.     /**
  287.      * Sets a new value.
  288.      *
  289.      * @since Servlet API 2.0
  290.      *
  291.      * @param value The new value
  292.      */
  293.     public void setValue(String value) {
  294.         myValue = value;
  295.     }
  296.  
  297.  
  298.     /**
  299.      * Sets the version.
  300.      * The current type of cookies have version = 1, according to rfc2109.
  301.      * There have been slightly different (netscape only) types of cookies,
  302.      * but these days everyone uses version 1.
  303.      *
  304.      * @since Servlet API 2.0
  305.      *
  306.      * @param version the version
  307.      */
  308.     public void setVersion(int version) {
  309.         myVersion = version;
  310.     }
  311.  
  312.     /**
  313.      * Clones the Cookie.
  314.      */
  315.     public Object clone() {
  316.         try {
  317.             return super.clone();
  318.         } catch (CloneNotSupportedException e) {
  319.             return null; // This should never happen
  320.         }
  321.     }
  322. }
  323.