Cookie.java
1 /* 2 * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//httpclient/src/java/org/apache/commons/httpclient/Cookie.java,v 1.44 2004/06/05 16:49:20 olegk Exp $ 3 * $Revision: 531354 $ 4 * $Date: 2007-04-23 08:53:20 +0200 (Mon, 23 Apr 2007) $ 5 * 6 * ==================================================================== 7 * 8 * Licensed to the Apache Software Foundation (ASF) under one or more 9 * contributor license agreements. See the NOTICE file distributed with 10 * this work for additional information regarding copyright ownership. 11 * The ASF licenses this file to You under the Apache License, Version 2.0 12 * (the "License"); you may not use this file except in compliance with 13 * the License. You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * 17 * Unless required by applicable law or agreed to in writing, software 18 * distributed under the License is distributed on an "AS IS" BASIS, 19 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 * See the License for the specific language governing permissions and 21 * limitations under the License. 22 * ==================================================================== 23 * 24 * This software consists of voluntary contributions made by many 25 * individuals on behalf of the Apache Software Foundation. For more 26 * information on the Apache Software Foundation, please see 27 * <http://www.apache.org/>. 28 * 29 */ 30 31 package org.apache.commons.httpclient; 32 33 import java.io.Serializable; 34 import java.util.Comparator; 35 import java.util.Date; 36 37 import org.apache.commons.httpclient.cookie.CookiePolicy; 38 import org.apache.commons.httpclient.cookie.CookieSpec; 39 import org.apache.commons.httpclient.util.LangUtils; 40 import org.apache.commons.logging.Log; 41 import org.apache.commons.logging.LogFactory; 42 43 /** 44 * <p> 45 * HTTP "magic-cookie" represents a piece of state information 46 * that the HTTP agent and the target server can exchange to maintain 47 * a session. 48 * </p> 49 * 50 * @author B.C. Holmes 51 * @author <a href="mailto:jericho@thinkfree.com">Park, Sung-Gu</a> 52 * @author <a href="mailto:dsale@us.britannica.com">Doug Sale</a> 53 * @author Rod Waldhoff 54 * @author dIon Gillard 55 * @author Sean C. Sullivan 56 * @author <a href="mailto:JEvans@Cyveillance.com">John Evans</a> 57 * @author Marc A. Saegesser 58 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a> 59 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a> 60 * 61 * @version $Revision: 531354 $ $Date: 2007-04-23 08:53:20 +0200 (Mon, 23 Apr 2007) $ 62 */ 63 public class Cookie extends NameValuePair implements Serializable, Comparator { 64 65 // ----------------------------------------------------------- Constructors 66 67 /** 68 * Default constructor. Creates a blank cookie 69 */ 70 71 public Cookie() { 72 this(null, "noname", null, null, null, false); 73 } 74 75 /** 76 * Creates a cookie with the given name, value and domain attribute. 77 * 78 * @param name the cookie name 79 * @param value the cookie value 80 * @param domain the domain this cookie can be sent to 81 */ 82 public Cookie(String domain, String name, String value) { 83 this(domain, name, value, null, null, false); 84 } 85 86 /** 87 * Creates a cookie with the given name, value, domain attribute, 88 * path attribute, expiration attribute, and secure attribute 89 * 90 * @param name the cookie name 91 * @param value the cookie value 92 * @param domain the domain this cookie can be sent to 93 * @param path the path prefix for which this cookie can be sent 94 * @param expires the {@link Date} at which this cookie expires, 95 * or <tt>null</tt> if the cookie expires at the end 96 * of the session 97 * @param secure if true this cookie can only be sent over secure 98 * connections 99 * @throws IllegalArgumentException If cookie name is null or blank, 100 * cookie name contains a blank, or cookie name starts with character $ 101 * 102 */ 103 public Cookie(String domain, String name, String value, 104 String path, Date expires, boolean secure) { 105 106 super(name, value); 107 LOG.trace("enter Cookie(String, String, String, String, Date, boolean)"); 108 if (name == null) { 109 throw new IllegalArgumentException("Cookie name may not be null"); 110 } 111 if (name.trim().equals("")) { 112 throw new IllegalArgumentException("Cookie name may not be blank"); 113 } 114 this.setPath(path); 115 this.setDomain(domain); 116 this.setExpiryDate(expires); 117 this.setSecure(secure); 118 } 119 120 /** 121 * Creates a cookie with the given name, value, domain attribute, 122 * path attribute, maximum age attribute, and secure attribute 123 * 124 * @param name the cookie name 125 * @param value the cookie value 126 * @param domain the domain this cookie can be sent to 127 * @param path the path prefix for which this cookie can be sent 128 * @param maxAge the number of seconds for which this cookie is valid. 129 * maxAge is expected to be a non-negative number. 130 * <tt>-1</tt> signifies that the cookie should never expire. 131 * @param secure if <tt>true</tt> this cookie can only be sent over secure 132 * connections 133 */ 134 public Cookie(String domain, String name, String value, String path, 135 int maxAge, boolean secure) { 136 137 this(domain, name, value, path, null, secure); 138 if (maxAge < -1) { 139 throw new IllegalArgumentException("Invalid max age: " + Integer.toString(maxAge)); 140 } 141 if (maxAge >= 0) { 142 setExpiryDate(new Date(System.currentTimeMillis() + maxAge * 1000L)); 143 } 144 } 145 146 /** 147 * Returns the comment describing the purpose of this cookie, or 148 * <tt>null</tt> if no such comment has been defined. 149 * 150 * @return comment 151 * 152 * @see #setComment(String) 153 */ 154 public String getComment() { 155 return cookieComment; 156 } 157 158 /** 159 * If a user agent (web browser) presents this cookie to a user, the 160 * cookie's purpose will be described using this comment. 161 * 162 * @param comment 163 * 164 * @see #getComment() 165 */ 166 public void setComment(String comment) { 167 cookieComment = comment; 168 } 169 170 /** 171 * Returns the expiration {@link Date} of the cookie, or <tt>null</tt> 172 * if none exists. 173 * <p><strong>Note:</strong> the object returned by this method is 174 * considered immutable. Changing it (e.g. using setTime()) could result 175 * in undefined behaviour. Do so at your peril. </p> 176 * @return Expiration {@link Date}, or <tt>null</tt>. 177 * 178 * @see #setExpiryDate(java.util.Date) 179 * 180 */ 181 public Date getExpiryDate() { 182 return cookieExpiryDate; 183 } 184 185 /** 186 * Sets expiration date. 187 * <p><strong>Note:</strong> the object returned by this method is considered 188 * immutable. Changing it (e.g. using setTime()) could result in undefined 189 * behaviour. Do so at your peril.</p> 190 * 191 * @param expiryDate the {@link Date} after which this cookie is no longer valid. 192 * 193 * @see #getExpiryDate 194 * 195 */ 196 public void setExpiryDate (Date expiryDate) { 197 cookieExpiryDate = expiryDate; 198 } 199 200 201 /** 202 * Returns <tt>false</tt> if the cookie should be discarded at the end 203 * of the "session"; <tt>true</tt> otherwise. 204 * 205 * @return <tt>false</tt> if the cookie should be discarded at the end 206 * of the "session"; <tt>true</tt> otherwise 207 */ 208 public boolean isPersistent() { 209 return (null != cookieExpiryDate); 210 } 211 212 213 /** 214 * Returns domain attribute of the cookie. 215 * 216 * @return the value of the domain attribute 217 * 218 * @see #setDomain(java.lang.String) 219 */ 220 public String getDomain() { 221 return cookieDomain; 222 } 223 224 /** 225 * Sets the domain attribute. 226 * 227 * @param domain The value of the domain attribute 228 * 229 * @see #getDomain 230 */ 231 public void setDomain(String domain) { 232 if (domain != null) { 233 int ndx = domain.indexOf(":"); 234 if (ndx != -1) { 235 domain = domain.substring(0, ndx); 236 } 237 cookieDomain = domain.toLowerCase(); 238 } 239 } 240 241 242 /** 243 * Returns the path attribute of the cookie 244 * 245 * @return The value of the path attribute. 246 * 247 * @see #setPath(java.lang.String) 248 */ 249 public String getPath() { 250 return cookiePath; 251 } 252 253 /** 254 * Sets the path attribute. 255 * 256 * @param path The value of the path attribute 257 * 258 * @see #getPath 259 * 260 */ 261 public void setPath(String path) { 262 cookiePath = path; 263 } 264 265 /** 266 * @return <code>true</code> if this cookie should only be sent over secure connections. 267 * @see #setSecure(boolean) 268 */ 269 public boolean getSecure() { 270 return isSecure; 271 } 272 273 /** 274 * Sets the secure attribute of the cookie. 275 * <p> 276 * When <tt>true</tt> the cookie should only be sent 277 * using a secure protocol (https). This should only be set when 278 * the cookie's originating server used a secure protocol to set the 279 * cookie's value. 280 * 281 * @param secure The value of the secure attribute 282 * 283 * @see #getSecure() 284 */ 285 public void setSecure (boolean secure) { 286 isSecure = secure; 287 } 288 289 /** 290 * Returns the version of the cookie specification to which this 291 * cookie conforms. 292 * 293 * @return the version of the cookie. 294 * 295 * @see #setVersion(int) 296 * 297 */ 298 public int getVersion() { 299 return cookieVersion; 300 } 301 302 /** 303 * Sets the version of the cookie specification to which this 304 * cookie conforms. 305 * 306 * @param version the version of the cookie. 307 * 308 * @see #getVersion 309 */ 310 public void setVersion(int version) { 311 cookieVersion = version; 312 } 313 314 /** 315 * Returns true if this cookie has expired. 316 * 317 * @return <tt>true</tt> if the cookie has expired. 318 */ 319 public boolean isExpired() { 320 return (cookieExpiryDate != null 321 && cookieExpiryDate.getTime() <= System.currentTimeMillis()); 322 } 323 324 /** 325 * Returns true if this cookie has expired according to the time passed in. 326 * 327 * @param now The current time. 328 * 329 * @return <tt>true</tt> if the cookie expired. 330 */ 331 public boolean isExpired(Date now) { 332 return (cookieExpiryDate != null 333 && cookieExpiryDate.getTime() <= now.getTime()); 334 } 335 336 337 /** 338 * Indicates whether the cookie had a path specified in a 339 * path attribute of the <tt>Set-Cookie</tt> header. This value 340 * is important for generating the <tt>Cookie</tt> header because 341 * some cookie specifications require that the <tt>Cookie</tt> header 342 * should only include a path attribute if the cookie's path 343 * was specified in the <tt>Set-Cookie</tt> header. 344 * 345 * @param value <tt>true</tt> if the cookie's path was explicitly 346 * set, <tt>false</tt> otherwise. 347 * 348 * @see #isPathAttributeSpecified 349 */ 350 public void setPathAttributeSpecified(boolean value) { 351 hasPathAttribute = value; 352 } 353 354 /** 355 * Returns <tt>true</tt> if cookie's path was set via a path attribute 356 * in the <tt>Set-Cookie</tt> header. 357 * 358 * @return value <tt>true</tt> if the cookie's path was explicitly 359 * set, <tt>false</tt> otherwise. 360 * 361 * @see #setPathAttributeSpecified 362 */ 363 public boolean isPathAttributeSpecified() { 364 return hasPathAttribute; 365 } 366 367 /** 368 * Indicates whether the cookie had a domain specified in a 369 * domain attribute of the <tt>Set-Cookie</tt> header. This value 370 * is important for generating the <tt>Cookie</tt> header because 371 * some cookie specifications require that the <tt>Cookie</tt> header 372 * should only include a domain attribute if the cookie's domain 373 * was specified in the <tt>Set-Cookie</tt> header. 374 * 375 * @param value <tt>true</tt> if the cookie's domain was explicitly 376 * set, <tt>false</tt> otherwise. 377 * 378 * @see #isDomainAttributeSpecified 379 */ 380 public void setDomainAttributeSpecified(boolean value) { 381 hasDomainAttribute = value; 382 } 383 384 /** 385 * Returns <tt>true</tt> if cookie's domain was set via a domain 386 * attribute in the <tt>Set-Cookie</tt> header. 387 * 388 * @return value <tt>true</tt> if the cookie's domain was explicitly 389 * set, <tt>false</tt> otherwise. 390 * 391 * @see #setDomainAttributeSpecified 392 */ 393 public boolean isDomainAttributeSpecified() { 394 return hasDomainAttribute; 395 } 396 397 /** 398 * Returns a hash code in keeping with the 399 * {@link Object#hashCode} general hashCode contract. 400 * @return A hash code 401 */ 402 public int hashCode() { 403 int hash = LangUtils.HASH_SEED; 404 hash = LangUtils.hashCode(hash, this.getName()); 405 hash = LangUtils.hashCode(hash, this.cookieDomain); 406 hash = LangUtils.hashCode(hash, this.cookiePath); 407 return hash; 408 } 409 410 411 /** 412 * Two cookies are equal if the name, path and domain match. 413 * @param obj The object to compare against. 414 * @return true if the two objects are equal. 415 */ 416 public boolean equals(Object obj) { 417 if (obj == null) return false; 418 if (this == obj) return true; 419 if (obj instanceof Cookie) { 420 Cookie that = (Cookie) obj; 421 return LangUtils.equals(this.getName(), that.getName()) 422 && LangUtils.equals(this.cookieDomain, that.cookieDomain) 423 && LangUtils.equals(this.cookiePath, that.cookiePath); 424 } else { 425 return false; 426 } 427 } 428 429 430 /** 431 * Return a textual representation of the cookie. 432 * 433 * @return string. 434 */ 435 public String toExternalForm() { 436 CookieSpec spec = null; 437 if (getVersion() > 0) { 438 spec = CookiePolicy.getDefaultSpec(); 439 } else { 440 spec = CookiePolicy.getCookieSpec(CookiePolicy.NETSCAPE); 441 } 442 return spec.formatCookie(this); 443 } 444 445 /** 446 * <p>Compares two cookies to determine order for cookie header.</p> 447 * <p>Most specific should be first. </p> 448 * <p>This method is implemented so a cookie can be used as a comparator for 449 * a SortedSet of cookies. Specifically it's used above in the 450 * createCookieHeader method.</p> 451 * @param o1 The first object to be compared 452 * @param o2 The second object to be compared 453 * @return See {@link java.util.Comparator#compare(Object,Object)} 454 */ 455 public int compare(Object o1, Object o2) { 456 LOG.trace("enter Cookie.compare(Object, Object)"); 457 458 if (!(o1 instanceof Cookie)) { 459 throw new ClassCastException(o1.getClass().getName()); 460 } 461 if (!(o2 instanceof Cookie)) { 462 throw new ClassCastException(o2.getClass().getName()); 463 } 464 Cookie c1 = (Cookie) o1; 465 Cookie c2 = (Cookie) o2; 466 if (c1.getPath() == null && c2.getPath() == null) { 467 return 0; 468 } else if (c1.getPath() == null) { 469 // null is assumed to be "/" 470 if (c2.getPath().equals(CookieSpec.PATH_DELIM)) { 471 return 0; 472 } else { 473 return -1; 474 } 475 } else if (c2.getPath() == null) { 476 // null is assumed to be "/" 477 if (c1.getPath().equals(CookieSpec.PATH_DELIM)) { 478 return 0; 479 } else { 480 return 1; 481 } 482 } else { 483 return c1.getPath().compareTo(c2.getPath()); 484 } 485 } 486 487 /** 488 * Return a textual representation of the cookie. 489 * 490 * @return string. 491 * 492 * @see #toExternalForm 493 */ 494 public String toString() { 495 return toExternalForm(); 496 } 497 498 // ----------------------------------------------------- Instance Variables 499 500 /** Comment attribute. */ 501 private String cookieComment; 502 503 /** Domain attribute. */ 504 private String cookieDomain; 505 506 /** Expiration {@link Date}. */ 507 private Date cookieExpiryDate; 508 509 /** Path attribute. */ 510 private String cookiePath; 511 512 /** My secure flag. */ 513 private boolean isSecure; 514 515 /** 516 * Specifies if the set-cookie header included a Path attribute for this 517 * cookie 518 */ 519 private boolean hasPathAttribute = false; 520 521 /** 522 * Specifies if the set-cookie header included a Domain attribute for this 523 * cookie 524 */ 525 private boolean hasDomainAttribute = false; 526 527 /** The version of the cookie specification I was created from. */ 528 private int cookieVersion = 0; 529 530 // -------------------------------------------------------------- Constants 531 532 /** Log object for this class */ 533 private static final Log LOG = LogFactory.getLog(Cookie.class); 534 535 } 536