Cookie


1   /* 
2    * ========================================================================
3    * 
4    * Copyright 2001-2004 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    * 
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   * 
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   * 
18   * ========================================================================
19   */
20  package org.apache.cactus;
21  
22  import java.io.Serializable  ;
23  
24  import java.util.Date  ;
25  
26  import org.apache.cactus.internal.util.CookieUtil;
27  
28  /**
29   * Client cookie. Used for manipulating client cookies either in
30   * <code>beginXXX()</code> (to send cookies) or in
31   * <code>endXXX()</code> methods (to assert returned cookies).
32   *
33   * @version $Id: Cookie.java,v 1.1 2004/05/22 11:34:45 vmassol Exp $
34   */
35  public class Cookie implements Serializable  
36  {
37      /**
38       * The cookie name
39       */
40      private String   name;
41  
42      /**
43       * The cookie value
44       */
45      private String   value;
46  
47      /**
48       * The cookie description.
49       * @see #setComment(String)
50       */
51      private String   comment;
52  
53      /**
54       * The cookie domain.
55       * @see #setDomain(String)
56       */
57      private String   domain;
58  
59      /**
60       * The cookie expiry date.
61       * @see #setExpiryDate(Date)
62       */
63      private Date   expiryDate;
64  
65      /**
66       * The cookie path.
67       * @see #setPath(String)
68       */
69      private String   path;
70  
71      /**
72       * True if the cookie should only be sent over secure connections.
73       * @see #setSecure(boolean)
74       */
75      private boolean isSecure = false;
76  
77      /**
78       * Create a cookie.
79       *
80       * @param theDomain the cookie domain
81       * @param theName the cookie name
82       * @param theValue the cookie value
83       */
84      public Cookie(String   theDomain, String   theName, String   theValue)
85      {
86          if (theDomain == null)
87          {
88              throw new NullPointerException  ("missing cookie domain");
89          }
90  
91          if (theName == null)
92          {
93              throw new NullPointerException  ("missing cookie name");
94          }
95  
96          if (theValue == null)
97          {
98              throw new NullPointerException  ("missing cookie value");
99          }
100 
101         setDomain(theDomain);
102         setName(theName);
103         setValue(theValue);
104     }
105 
106     /**
107      * Sets the cookie name
108      *
109      * @param theName the cookie name
110      */
111     public void setName(String   theName)
112     {
113         this.name = theName;
114     }
115 
116     /**
117      * @return the cookie name
118      */
119     public String   getName()
120     {
121         return this.name;
122     }
123 
124     /**
125      * Sets the cookie value
126      *
127      * @param theValue the cookie value
128      */
129     public void setValue(String   theValue)
130     {
131         this.value = theValue;
132     }
133 
134     /**
135      * @return the cookie value
136      */
137     public String   getValue()
138     {
139         return this.value;
140     }
141 
142     /**
143      * Returns the comment describing the purpose of this cookie, or
144      * null if no such comment has been defined.
145      *
146      * @return the cookie comment
147      */
148     public String   getComment()
149     {
150         return this.comment;
151     }
152 
153     /**
154      * If a user agent (web browser) presents this cookie to a user, the
155      * cookie's purpose will be described using this comment.
156      *
157      * @param theComment the cookie's text comment
158      */
159     public void setComment(String   theComment)
160     {
161         this.comment = theComment;
162     }
163 
164     /**
165      * Return the expiry date.
166      *
167      * @return the expiry date of this cookie, or null if none set.
168      */
169     public Date   getExpiryDate()
170     {
171         return this.expiryDate;
172     }
173 
174     /**
175      * Set the cookie expires date.
176      *
177      * <p>Netscape's original proposal defined an Expires header that took
178      * a date value in a fixed-length variant format in place of Max-Age:
179      *
180      * Wdy, DD-Mon-YY HH:MM:SS GMT
181      *
182      * Note that the Expires date format contains embedded spaces, and that
183      * "old" cookies did not have quotes around values.  Clients that
184      * implement to this specification should be aware of "old" cookies and
185      * Expires.
186      *
187      * @param theExpiryDate the expires date.
188      */
189     public void setExpiryDate(Date   theExpiryDate)
190     {
191         this.expiryDate = theExpiryDate;
192     }
193 
194     /**
195      * @return true if the cookie should be discarded at the end of the
196      *         session; false otherwise
197      */
198     public boolean isToBeDiscarded()
199     {
200         return (this.getExpiryDate() != null);
201     }
202 
203     /**
204      * Returns the domain of this cookie.
205      *
206      * @return the cookie domain
207      */
208     public String   getDomain()
209     {
210         return this.domain;
211     }
212 
213     /**
214      * Sets the cookie domain. This cookie should be presented only to hosts
215      * satisfying this domain name pattern.  Read RFC 2109 for specific
216      * details of the syntax.
217      *
218      * Briefly, a domain name name begins with a dot (".foo.com") and means
219      * that hosts in that DNS zone ("www.foo.com", but not "a.b.foo.com")
220      * should see the cookie.  By default, cookies are only returned to
221      * the host which saved them.
222      *
223      * @param theDomain the cookie domain
224      */
225     public void setDomain(String   theDomain)
226     {
227         int ndx = theDomain.indexOf(":");
228 
229         if (ndx != -1)
230         {
231             theDomain = theDomain.substring(0, ndx);
232         }
233 
234         this.domain = theDomain.toLowerCase();
235     }
236 
237     /**
238      * Return the path this cookie is associated with.
239      *
240      * @return the cookie path
241      */
242     public String   getPath()
243     {
244         return this.path;
245     }
246 
247     /**
248      * Sets the cookie path. This cookie should be presented only with
249      * requests beginning with this URL. Read RFC 2109 for a specification
250      * of the default behaviour. Basically, URLs in the same "directory" as
251      * the one which set the cookie, and in subdirectories, can all see the
252      * cookie unless a different path is set.
253      *
254      * @param thePath the cookie path
255      */
256     public void setPath(String   thePath)
257     {
258         this.path = thePath;
259     }
260 
261     /**
262      * @return true if the cookie should only be sent over secure connections.
263      */
264     public boolean isSecure()
265     {
266         return this.isSecure;
267     }
268 
269     /**
270      * Indicates to the user agent that the cookie should only be sent
271      * using a secure protocol (https).  This should only be set when
272      * the cookie's originating server used a secure protocol to set the
273      * cookie's value.
274      *
275      * @param isSecure true if the cookie should be sent over secure
276      *                 connections only
277      */
278     public void setSecure(boolean isSecure)
279     {
280         this.isSecure = isSecure;
281     }
282 
283     /**
284      * @return true if this cookie has expired
285      */
286     public boolean isExpired()
287     {
288         return (this.getExpiryDate() != null
289             && this.getExpiryDate().getTime() <= System.currentTimeMillis());
290     }
291 
292     /**
293      * Hash up name, value and domain into new hash.
294      *
295      * @return the hashcode of this class
296      */
297     public int hashCode()
298     {
299         return (this.getName().hashCode() + this.getValue().hashCode()
300             + this.getDomain().hashCode());
301     }
302 
303     /**
304      * Two cookies match if the name, path and domain match.
305      *
306      * @param theObject the cookie object to match
307      * @return true of the object passed as paramater is equal to this coookie
308      *         instance
309      */
310     public boolean equals(Object   theObject)
311     {
312         if ((theObject != null) && (theObject instanceof Cookie))
313         {
314             Cookie other = (Cookie) theObject;
315 
316             return (this.getName().equals(other.getName())
317                 && this.getPath().equals(other.getPath())
318                 && this.getDomain().equals(other.getDomain()));
319         }
320 
321         return false;
322     }
323 
324     /**
325      * @return a string representation of the cookie
326      */
327     public String   toString()
328     {
329         StringBuffer   buffer = new StringBuffer  ();
330 
331         buffer.append("name = [" + getName() + "], ");
332         buffer.append("value = [" + getValue() + "], ");
333         buffer.append("domain = [" + getDomain() + "], ");
334         buffer.append("path = [" + getPath() + "], ");
335         buffer.append("isSecure = [" + isSecure() + "], ");
336         buffer.append("comment = [" + getComment() + "], ");
337         buffer.append("expiryDate = [" + getExpiryDate() + "]");
338 
339         return buffer.toString();
340     }
341 
342     /**
343      * @see CookieUtil#getCookieDomain(WebRequest, String)
344      * @deprecated use {@link CookieUtil#getCookieDomain(WebRequest, String)} 
345      */
346     public static String   getCookieDomain(WebRequest theRequest, 
347         String   theRealHost)
348     {
349         return CookieUtil.getCookieDomain(theRequest, theRealHost);
350     }
351 
352     /**
353      * @see CookieUtil#getCookiePort(WebRequest, int)
354      * @deprecated use {@link CookieUtil#getCookiePort(WebRequest, int)} 
355      */
356     public static int getCookiePort(WebRequest theRequest, int theRealPort)
357     {
358         return CookieUtil.getCookiePort(theRequest, theRealPort);
359     }
360 
361     /**
362      * @see CookieUtil#getCookiePath(WebRequest, String)
363      * @deprecated use {@link CookieUtil#getCookiePath(WebRequest, String)} 
364      */
365     public static String   getCookiePath(WebRequest theRequest, 
366         String   theRealPath)
367     {
368         return CookieUtil.getCookiePath(theRequest, theRealPath);
369     }
370 }
371
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags