1 /*
2 * $Header: /home/cvs/jakarta-commons/httpclient/src/java/org/apache/commons/httpclient/Cookie.java,v 1.38.2.2 2003/11/01 21:13:56 olegk Exp $
3 * $Revision: 1.38.2.2 $
4 * $Date: 2003/11/01 21:13:56 $
5 *
6 * ====================================================================
7 *
8 * The Apache Software License, Version 1.1
9 *
10 * Copyright (c) 1999-2003 The Apache Software Foundation. All rights
11 * reserved.
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 *
17 * 1. Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 *
20 * 2. Redistributions in binary form must reproduce the above copyright
21 * notice, this list of conditions and the following disclaimer in
22 * the documentation and/or other materials provided with the
23 * distribution.
24 *
25 * 3. The end-user documentation included with the redistribution, if
26 * any, must include the following acknowlegement:
27 * "This product includes software developed by the
28 * Apache Software Foundation (http://www.apache.org/)."
29 * Alternately, this acknowlegement may appear in the software itself,
30 * if and wherever such third-party acknowlegements normally appear.
31 *
32 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
33 * Foundation" must not be used to endorse or promote products derived
34 * from this software without prior written permission. For written
35 * permission, please contact apache@apache.org.
36 *
37 * 5. Products derived from this software may not be called "Apache"
38 * nor may "Apache" appear in their names without prior written
39 * permission of the Apache Group.
40 *
41 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
42 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
45 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
47 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
48 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
49 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
51 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
52 * SUCH DAMAGE.
53 * ====================================================================
54 *
55 * This software consists of voluntary contributions made by many
56 * individuals on behalf of the Apache Software Foundation. For more
57 * information on the Apache Software Foundation, please see
58 * <http://www.apache.org/>.
59 *
60 * [Additional notices, if required by prior licensing conditions]
61 *
62 */
63
64 package org.apache.commons.httpclient;
65
66 import java.io.Serializable;
67 import java.text.RuleBasedCollator;
68 import java.util.Comparator;
69 import java.util.Date;
70 import java.util.Locale;
71
72 import org.apache.commons.httpclient.cookie.CookiePolicy;
73 import org.apache.commons.httpclient.cookie.CookieSpec;
74 import org.apache.commons.logging.Log;
75 import org.apache.commons.logging.LogFactory;
76
77
78 /***
79 * <p>
80 * HTTP "magic-cookie" represents a piece of state information
81 * that the HTTP agent and the target server can exchange to maintain
82 * a session.
83 * </p>
84 *
85 * @author B.C. Holmes
86 * @author <a href="mailto:jericho@thinkfree.com">Park, Sung-Gu</a>
87 * @author <a href="mailto:dsale@us.britannica.com">Doug Sale</a>
88 * @author Rod Waldhoff
89 * @author dIon Gillard
90 * @author Sean C. Sullivan
91 * @author <a href="mailto:JEvans@Cyveillance.com">John Evans</a>
92 * @author Marc A. Saegesser
93 * @author <a href="mailto:oleg@ural.ru">Oleg Kalnichevski</a>
94 * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
95 *
96 * @version $Revision: 1.38.2.2 $ $Date: 2003/11/01 21:13:56 $
97 */
98
99 public class Cookie extends NameValuePair implements Serializable, Comparator {
100
101 // ----------------------------------------------------------- Constructors
102
103 /***
104 * Default constructor. Creates a blank cookie
105 */
106
107 public Cookie() {
108 this(null, "noname", null, null, null, false);
109 }
110
111 /***
112 * Creates a cookie with the given name, value and domain attribute.
113 *
114 * @param name the cookie name
115 * @param value the cookie value
116 * @param domain the domain this cookie can be sent to
117 */
118 public Cookie(String domain, String name, String value) {
119 this(domain, name, value, null, null, false);
120 }
121
122 /***
123 * Creates a cookie with the given name, value, domain attribute,
124 * path attribute, expiration attribute, and secure attribute
125 *
126 * @param name the cookie name
127 * @param value the cookie value
128 * @param domain the domain this cookie can be sent to
129 * @param path the path prefix for which this cookie can be sent
130 * @param expires the {@link Date} at which this cookie expires,
131 * or <tt>null</tt> if the cookie expires at the end
132 * of the session
133 * @param secure if true this cookie can only be sent over secure
134 * connections
135 * @throws IllegalArgumentException If cookie name is null or blank,
136 * cookie name contains a blank, or cookie name starts with character $
137 *
138 */
139 public Cookie(String domain, String name, String value,
140 String path, Date expires, boolean secure) {
141
142 super(name, value);
143 LOG.trace("enter Cookie(String, String, String, String, Date, boolean)");
144 if (name == null) {
145 throw new IllegalArgumentException("Cookie name may not be null");
146 }
147 if (name.equals("")) {
148 throw new IllegalArgumentException("Cookie name may not be blank");
149 }
150 if (name.indexOf(' ') != -1) {
151 throw new IllegalArgumentException("Cookie name may not contain blanks");
152 }
153 if (name.startsWith("$")) {
154 throw new IllegalArgumentException("Cookie name may not start with $");
155 }
156 this.setPath(path);
157 this.setDomain(domain);
158 this.setExpiryDate(expires);
159 this.setSecure(secure);
160 }
161
162 /***
163 * Creates a cookie with the given name, value, domain attribute,
164 * path attribute, maximum age attribute, and secure attribute
165 *
166 * @param name the cookie name
167 * @param value the cookie value
168 * @param domain the domain this cookie can be sent to
169 * @param path the path prefix for which this cookie can be sent
170 * @param maxAge the number of seconds for which this cookie is valid.
171 * maxAge is expected to be a non-negative number.
172 * <tt>-1</tt> signifies that the cookie should never expire.
173 * @param secure if <tt>true</tt> this cookie can only be sent over secure
174 * connections
175 */
176 public Cookie(String domain, String name, String value, String path,
177 int maxAge, boolean secure) {
178
179 this(domain, name, value, path, null, secure);
180 if (maxAge < -1) {
181 throw new IllegalArgumentException("Invalid max age: " + Integer.toString(maxAge));
182 }
183 if (maxAge >= 0) {
184 setExpiryDate(new Date(System.currentTimeMillis() + maxAge * 1000L));
185 }
186 }
187
188 /***
189 * Returns the comment describing the purpose of this cookie, or
190 * <tt>null</tt> if no such comment has been defined.
191 *
192 * @return comment
193 *
194 * @see #setComment(String)
195 */
196 public String getComment() {
197 return cookieComment;
198 }
199
200 /***
201 * If a user agent (web browser) presents this cookie to a user, the
202 * cookie's purpose will be described using this comment.
203 *
204 * @param comment
205 *
206 * @see #getComment()
207 */
208 public void setComment(String comment) {
209 cookieComment = comment;
210 }
211
212 /***
213 * Returns the expiration {@link Date} of the cookie, or <tt>null</tt>
214 * if none exists.
215 * <p><strong>Note:</strong> the object returned by this method is
216 * considered immutable. Changing it (e.g. using setTime()) could result
217 * in undefined behaviour. Do so at your peril. </p>
218 * @return Expiration {@link Date}, or <tt>null</tt>.
219 *
220 * @see #setExpiryDate(java.util.Date)
221 *
222 */
223 public Date getExpiryDate() {
224 return cookieExpiryDate;
225 }
226
227 /***
228 * Sets expiration date.
229 * <p><strong>Note:</strong> the object returned by this method is considered
230 * immutable. Changing it (e.g. using setTime()) could result in undefined
231 * behaviour. Do so at your peril.</p>
232 *
233 * @param expiryDate the {@link Date} after which this cookie is no longer valid.
234 *
235 * @see #getExpiryDate
236 *
237 */
238 public void setExpiryDate (Date expiryDate) {
239 cookieExpiryDate = expiryDate;
240 }
241
242
243 /***
244 * Returns <tt>false</tt> if the cookie should be discarded at the end
245 * of the "session"; <tt>true</tt> otherwise.
246 *
247 * @return <tt>false</tt> if the cookie should be discarded at the end
248 * of the "session"; <tt>true</tt> otherwise
249 */
250 public boolean isPersistent() {
251 return (null != cookieExpiryDate);
252 }
253
254
255 /***
256 * Returns domain attribute of the cookie.
257 *
258 * @return the value of the domain attribute
259 *
260 * @see #setDomain(java.lang.String)
261 */
262 public String getDomain() {
263 return cookieDomain;
264 }
265
266 /***
267 * Sets the domain attribute.
268 *
269 * @param domain The value of the domain attribute
270 *
271 * @see #getDomain
272 */
273 public void setDomain(String domain) {
274 if (domain != null) {
275 int ndx = domain.indexOf(":");
276 if (ndx != -1) {
277 domain = domain.substring(0, ndx);
278 }
279 cookieDomain = domain.toLowerCase();
280 }
281 }
282
283
284 /***
285 * Returns the path attribute of the cookie
286 *
287 * @return The value of the path attribute.
288 *
289 * @see #setPath(java.lang.String)
290 */
291 public String getPath() {
292 return cookiePath;
293 }
294
295 /***
296 * Sets the path attribute.
297 *
298 * @param path The value of the path attribute
299 *
300 * @see #getPath
301 *
302 */
303 public void setPath(String path) {
304 cookiePath = path;
305 }
306
307 /***
308 * @return <code>true</code> if this cookie should only be sent over secure connections.
309 * @see #setSecure(boolean)
310 */
311 public boolean getSecure() {
312 return isSecure;
313 }
314
315 /***
316 * Sets the secure attribute of the cookie.
317 * <p>
318 * When <tt>true</tt> the cookie should only be sent
319 * using a secure protocol (https). This should only be set when
320 * the cookie's originating server used a secure protocol to set the
321 * cookie's value.
322 *
323 * @param secure The value of the secure attribute
324 *
325 * @see #getSecure()
326 */
327 public void setSecure (boolean secure) {
328 isSecure = secure;
329 }
330
331 /***
332 * Returns the version of the cookie specification to which this
333 * cookie conforms.
334 *
335 * @return the version of the cookie.
336 *
337 * @see #setVersion(int)
338 *
339 */
340 public int getVersion() {
341 return cookieVersion;
342 }
343
344 /***
345 * Sets the version of the cookie specification to which this
346 * cookie conforms.
347 *
348 * @param version the version of the cookie.
349 *
350 * @see #getVersion
351 */
352 public void setVersion(int version) {
353 cookieVersion = version;
354 }
355
356 /***
357 * Returns true if this cookie has expired.
358 *
359 * @return <tt>true</tt> if the cookie has expired.
360 */
361 public boolean isExpired() {
362 return (cookieExpiryDate != null
363 && cookieExpiryDate.getTime() <= System.currentTimeMillis());
364 }
365
366 /***
367 * Returns true if this cookie has expired according to the time passed in.
368 *
369 * @param now The current time.
370 *
371 * @return <tt>true</tt> if the cookie expired.
372 */
373 public boolean isExpired(Date now) {
374 return (cookieExpiryDate != null
375 && cookieExpiryDate.getTime() <= now.getTime());
376 }
377
378
379 /***
380 * Indicates whether the cookie had a path specified in a
381 * path attribute of the <tt>Set-Cookie</tt> header. This value
382 * is important for generating the <tt>Cookie</tt> header because
383 * some cookie specifications require that the <tt>Cookie</tt> header
384 * should only include a path attribute if the cookie's path
385 * was specified in the <tt>Set-Cookie</tt> header.
386 *
387 * @param value <tt>true</tt> if the cookie's path was explicitly
388 * set, <tt>false</tt> otherwise.
389 *
390 * @see #isPathAttributeSpecified
391 */
392 public void setPathAttributeSpecified(boolean value) {
393 hasPathAttribute = value;
394 }
395
396 /***
397 * Returns <tt>true</tt> if cookie's path was set via a path attribute
398 * in the <tt>Set-Cookie</tt> header.
399 *
400 * @return value <tt>true</tt> if the cookie's path was explicitly
401 * set, <tt>false</tt> otherwise.
402 *
403 * @see #setPathAttributeSpecified
404 */
405 public boolean isPathAttributeSpecified() {
406 return hasPathAttribute;
407 }
408
409 /***
410 * Indicates whether the cookie had a domain specified in a
411 * domain attribute of the <tt>Set-Cookie</tt> header. This value
412 * is important for generating the <tt>Cookie</tt> header because
413 * some cookie specifications require that the <tt>Cookie</tt> header
414 * should only include a domain attribute if the cookie's domain
415 * was specified in the <tt>Set-Cookie</tt> header.
416 *
417 * @param value <tt>true</tt> if the cookie's domain was explicitly
418 * set, <tt>false</tt> otherwise.
419 *
420 * @see #isDomainAttributeSpecified
421 */
422 public void setDomainAttributeSpecified(boolean value) {
423 hasDomainAttribute = value;
424 }
425
426 /***
427 * Returns <tt>true</tt> if cookie's domain was set via a domain
428 * attribute in the <tt>Set-Cookie</tt> header.
429 *
430 * @return value <tt>true</tt> if the cookie's domain was explicitly
431 * set, <tt>false</tt> otherwise.
432 *
433 * @see #setDomainAttributeSpecified
434 */
435 public boolean isDomainAttributeSpecified() {
436 return hasDomainAttribute;
437 }
438
439 /***
440 * Returns a hash code in keeping with the
441 * {@link Object#hashCode} general hashCode contract.
442 * @return A hash code
443 */
444 public int hashCode() {
445 return super.hashCode()
446 ^ (null == cookiePath ? 0 : cookiePath.hashCode())
447 ^ (null == cookieDomain ? 0 : cookieDomain.hashCode());
448 }
449
450
451 /***
452 * Two cookies are equal if the name, path and domain match.
453 * @param obj The object to compare against.
454 * @return true if the two objects are equal.
455 */
456 public boolean equals(Object obj) {
457 LOG.trace("enter Cookie.equals(Object)");
458
459 if ((obj != null) && (obj instanceof Cookie)) {
460 Cookie that = (Cookie) obj;
461 return
462 (null == this.getName()
463 ? null == that.getName()
464 : this.getName().equals(that.getName()))
465 && (null == this.getPath()
466 ? null == that.getPath()
467 : this.getPath().equals(that.getPath()))
468 && (null == this.getDomain()
469 ? null == that.getDomain()
470 : this.getDomain().equals(that.getDomain()));
471 } else {
472 return false;
473 }
474 }
475
476
477 /***
478 * Returns a textual representation of the cookie.
479 *
480 * @return string .
481 */
482 public String toExternalForm() {
483 return CookiePolicy.getSpecByVersion(
484 getVersion()).formatCookie(this);
485 }
486
487 /***
488 * Return <tt>true</tt> if I should be submitted with a request with given
489 * attributes, <tt>false</tt> otherwise.
490 * @param domain the host to which the request is being submitted
491 * @param port the port to which the request is being submitted (currently
492 * ignored)
493 * @param path the path to which the request is being submitted
494 * @param secure <tt>true</tt> if the request is using the HTTPS protocol
495 * @param date the time at which the request is submitted
496 * @return true if the cookie matches
497 *
498 * @deprecated use {@link CookieSpec} interface
499 */
500 public boolean matches(
501 String domain, int port, String path, boolean secure, Date date) {
502
503 LOG.trace("enter Cookie.matches(Strinng, int, String, boolean, Date");
504 CookieSpec matcher = CookiePolicy.getDefaultSpec();
505 return matcher.match(domain, port, path, secure, this);
506 }
507
508 /***
509 * Return <tt>true</tt> if I should be submitted with a request with given
510 * attributes, <tt>false</tt> otherwise.
511 * @param domain the host to which the request is being submitted
512 * @param port the port to which the request is being submitted (currently
513 * ignored)
514 * @param path the path to which the request is being submitted
515 * @param secure True if this cookie has the secure flag set
516 * @return true if I should be submitted as above.
517 * @deprecated use {@link CookieSpec} interface
518 */
519 public boolean matches(
520 String domain, int port, String path, boolean secure) {
521 LOG.trace("enter Cookie.matches(String, int, String, boolean");
522 return matches(domain, port, path, secure, new Date());
523 }
524
525 /***
526 * Create a <tt>Cookie</tt> header containing
527 * all non-expired cookies in <i>cookies</i>,
528 * associated with the given <i>domain</i> and
529 * <i>path</i>, assuming the connection is not
530 * secure.
531 * <p>
532 * If no cookies match, returns null.
533 *
534 * @param domain The domain
535 * @param path The path
536 * @param cookies The cookies to use
537 * @return The new header.
538 * @deprecated use {@link CookieSpec} interface
539 */
540 public static Header createCookieHeader(String domain, String path,
541 Cookie[] cookies) {
542
543 LOG.trace("enter Cookie.createCookieHeader(String,String,Cookie[])");
544 return Cookie.createCookieHeader(domain, path, false, cookies);
545 }
546
547 /***
548 * Create a <tt>Cookie</tt> header containing
549 * all non-expired cookies in <i>cookies</i>,
550 * associated with the given <i>domain</i>, <i>path</i> and
551 * <i>https</i> setting.
552 * <p>
553 * If no cookies match, returns null.
554 *
555 * @param domain The domain
556 * @param path The path
557 * @param secure True if this cookie has the secure flag set
558 * @param cookies The cookies to use.
559 * @return The new header
560 * @exception IllegalArgumentException if domain or path is null
561 *
562 * @deprecated use {@link CookieSpec} interface
563 */
564 public static Header createCookieHeader(String domain, String path,
565 boolean secure, Cookie[] cookies)
566 throws IllegalArgumentException {
567
568 LOG.trace("enter Cookie.createCookieHeader("
569 + "String, String, boolean, Cookie[])");
570
571 // Make sure domain isn't null here. Path will be validated in
572 // subsequent call to createCookieHeader
573 if (domain == null) {
574 throw new IllegalArgumentException("null domain in "
575 + "createCookieHeader.");
576 }
577 // parse port from domain, if any
578 int port = secure ? 443 : 80;
579 int ndx = domain.indexOf(":");
580 if (ndx != -1) {
581 try {
582 port = Integer.parseInt(domain.substring(ndx + 1,
583 domain.length()));
584 } catch (NumberFormatException e) {
585 // ignore?, but at least LOG
586 LOG.warn("Cookie.createCookieHeader(): "
587 + "Invalid port number in domain " + domain);
588 }
589 }
590 return Cookie.createCookieHeader(domain, port, path, secure, cookies);
591 }
592
593 /***
594 * Create a <tt>Cookie</tt> header containing
595 * all non-expired cookies in <i>cookies</i>,
596 * associated with the given <i>domain</i>, <i>port</i>,
597 * <i>path</i> and <i>https</i> setting.
598 * <p>
599 * If no cookies match, returns null.
600 *
601 * @param domain The domain
602 * @param port The port
603 * @param path The path
604 * @param secure True if this cookie has the secure flag set
605 * @param cookies The cookies to use.
606 * @return The new header
607 * @throws IllegalArgumentException if domain or path is null
608 *
609 * @deprecated use {@link CookieSpec} interface
610 */
611 public static Header createCookieHeader(String domain, int port,
612 String path, boolean secure, Cookie[] cookies)
613 throws IllegalArgumentException {
614 LOG.trace("enter Cookie.createCookieHeader(String, int, String, boolean, Cookie[])");
615 return Cookie.createCookieHeader(domain, port, path, secure, new Date(), cookies);
616 }
617
618 /***
619 * Create a <tt>Cookie</tt> header containing all cookies in <i>cookies</i>,
620 * associated with the given <i>domain</i>, <i>port</i>, <i>path</i> and
621 * <i>https</i> setting, and which are not expired according to the given
622 * <i>date</i>.
623 * <p>
624 * If no cookies match, returns null.
625 *
626 * @param domain The domain
627 * @param port The port
628 * @param path The path
629 * @param secure True if this cookie has the secure flag set
630 * @param now The date to check for expiry
631 * @param cookies The cookies to use.
632 * @return The new header
633 * @throws IllegalArgumentException if domain or path is null
634 *
635 * @deprecated use {@link CookieSpec} interface
636 */
637
638 public static Header createCookieHeader(
639 String domain, int port, String path, boolean secure,
640 Date now, Cookie[] cookies)
641 throws IllegalArgumentException {
642
643 LOG.trace("enter Cookie.createCookieHeader(String, int, String, boolean, Date, Cookie[])");
644 CookieSpec matcher = CookiePolicy.getDefaultSpec();
645 cookies = matcher.match(domain, port, path, secure, cookies);
646 if ((cookies != null) && (cookies.length > 0)) {
647 return matcher.formatCookieHeader(cookies);
648 } else {
649 return null;
650 }
651 }
652
653 /***
654 * <p>Compares two cookies to determine order for cookie header.</p>
655 * <p>Most specific should be first. </p>
656 * <p>This method is implemented so a cookie can be used as a comparator for
657 * a SortedSet of cookies. Specifically it's used above in the
658 * createCookieHeader method.</p>
659 * @param o1 The first object to be compared
660 * @param o2 The second object to be compared
661 * @return See {@link java.util.Comparator#compare(Object,Object)}
662 */
663 public int compare(Object o1, Object o2) {
664 LOG.trace("enter Cookie.compare(Object, Object)");
665
666 if (!(o1 instanceof Cookie)) {
667 throw new ClassCastException(o1.getClass().getName());
668 }
669 if (!(o2 instanceof Cookie)) {
670 throw new ClassCastException(o2.getClass().getName());
671 }
672 Cookie c1 = (Cookie) o1;
673 Cookie c2 = (Cookie) o2;
674 if (c1.getPath() == null && c2.getPath() == null) {
675 return 0;
676 } else if (c1.getPath() == null) {
677 // null is assumed to be "/"
678 if (c2.getPath().equals(CookieSpec.PATH_DELIM)) {
679 return 0;
680 } else {
681 return -1;
682 }
683 } else if (c2.getPath() == null) {
684 // null is assumed to be "/"
685 if (c1.getPath().equals(CookieSpec.PATH_DELIM)) {
686 return 0;
687 } else {
688 return 1;
689 }
690 } else {
691 return STRING_COLLATOR.compare(c1.getPath(), c2.getPath());
692 }
693 }
694
695 /***
696 * Return a textual representation of the cookie.
697 * @see #toExternalForm
698 */
699 public String toString() {
700 return toExternalForm();
701 }
702
703 /***
704 * Parses the Set-Cookie {@link Header} into an array of
705 * <tt>Cookie</tt>s, assuming that the cookies were recieved
706 * on an insecure channel.
707 *
708 * @param domain the domain from which the {@link Header} was received
709 * @param port the port from which the {@link Header} was received
710 * (currently ignored)
711 * @param path the path from which the {@link Header} was received
712 * @param setCookie the <tt>Set-Cookie</tt> {@link Header} received from the
713 * server
714 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie {@link
715 * Header}
716 * @throws HttpException if an exception occurs during parsing
717 * @throws IllegalArgumentException if domain or path are null
718 *
719 * @deprecated use {@link CookieSpec} interface
720 */
721 public static Cookie[] parse(
722 String domain, int port, String path, Header setCookie)
723 throws HttpException, IllegalArgumentException {
724
725 LOG.trace("enter Cookie.parse(String, int, String, Header)");
726 return Cookie.parse(domain, port, path, false, setCookie);
727 }
728
729 /***
730 * Parses the Set-Cookie {@link Header} into an array of
731 * <tt>Cookie</tt>s, assuming that the cookies were recieved
732 * on an insecure channel.
733 *
734 * @param domain the domain from which the {@link Header} was received
735 * @param path the path from which the {@link Header} was received
736 * @param setCookie the <tt>Set-Cookie</tt> {@link Header} received from the
737 * server
738 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie {@link
739 * Header}
740 * @throws HttpException if an exception occurs during parsing
741 * @throws IllegalArgumentException if domain or path are null
742 *
743 * @deprecated use {@link CookieSpec} interface
744 */
745 public static Cookie[] parse(String domain, String path, Header setCookie)
746 throws HttpException, IllegalArgumentException {
747 LOG.trace("enter Cookie.parse(String, String, Header)");
748 return Cookie.parse (domain, 80, path, false, setCookie);
749 }
750
751 /***
752 * Parses the Set-Cookie {@link Header} into an array of
753 * <tt>Cookie</tt>s.
754 *
755 * @param domain the domain from which the {@link Header} was received
756 * @param path the path from which the {@link Header} was received
757 * @param secure <tt>true</tt> when the header was recieved over a secure
758 * channel
759 * @param setCookie the <tt>Set-Cookie</tt> {@link Header} received from the
760 * server
761 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie {@link
762 * Header}
763 * @throws HttpException if an exception occurs during parsing
764 * @throws IllegalArgumentException if domain or path are null
765 *
766 * @deprecated use {@link CookieSpec} interface
767 */
768 public static Cookie[] parse(String domain, String path,
769 boolean secure, Header setCookie)
770 throws HttpException, IllegalArgumentException {
771
772 LOG.trace ("enter Cookie.parse(String, String, boolean, Header)");
773 return Cookie.parse (
774 domain, (secure ? 443 : 80), path, secure, setCookie);
775 }
776
777 /***
778 * Parses the Set-Cookie {@link Header} into an array of
779 * <tt>Cookie</tt>s.
780 *
781 * <P>The syntax for the Set-Cookie response header is:
782 *
783 * <PRE>
784 * set-cookie = "Set-Cookie:" cookies
785 * cookies = 1#cookie
786 * cookie = NAME "=" VALUE * (";" cookie-av)
787 * NAME = attr
788 * VALUE = value
789 * cookie-av = "Comment" "=" value
790 * | "Domain" "=" value
791 * | "Max-Age" "=" value
792 * | "Path" "=" value
793 * | "Secure"
794 * | "Version" "=" 1*DIGIT
795 * </PRE>
796 *
797 * @param domain the domain from which the {@link Header} was received
798 * @param port The port from which the {@link Header} was received.
799 * @param path the path from which the {@link Header} was received
800 * @param secure <tt>true</tt> when the {@link Header} was received over
801 * HTTPS
802 * @param setCookie the <tt>Set-Cookie</tt> {@link Header} received from
803 * the server
804 * @return an array of <tt>Cookie</tt>s parsed from the Set-Cookie {@link
805 * Header}
806 * @throws HttpException if an exception occurs during parsing
807 *
808 * @deprecated use {@link CookieSpec} interface
809 */
810 public static Cookie[] parse(String domain, int port, String path,
811 boolean secure, Header setCookie)
812 throws HttpException {
813
814 LOG.trace("enter Cookie.parse(String, int, String, boolean, Header)");
815
816 CookieSpec parser = CookiePolicy.getDefaultSpec();
817 Cookie[] cookies = parser.parse(domain, port, path, secure, setCookie);
818
819 for (int i = 0; i < cookies.length; i++) {
820 final Cookie cookie = cookies[i];
821 final CookieSpec validator
822 = CookiePolicy.getSpecByVersion(cookie.getVersion());
823 validator.validate(domain, port, path, secure, cookie);
824 }
825 return cookies;
826 }
827
828 // ----------------------------------------------------- Instance Variables
829
830 /*** Comment attribute. */
831 private String cookieComment;
832
833 /*** Domain attribute. */
834 private String cookieDomain;
835
836 /*** Expiration {@link Date}. */
837 private Date cookieExpiryDate;
838
839 /*** Path attribute. */
840 private String cookiePath;
841
842 /*** My secure flag. */
843 private boolean isSecure;
844
845 /***
846 * Specifies if the set-cookie header included a Path attribute for this
847 * cookie
848 */
849 private boolean hasPathAttribute = false;
850
851 /***
852 * Specifies if the set-cookie header included a Domain attribute for this
853 * cookie
854 */
855 private boolean hasDomainAttribute = false;
856
857 /*** The version of the cookie specification I was created from. */
858 private int cookieVersion = 0;
859
860 // -------------------------------------------------------------- Constants
861
862 /***
863 * Collator for Cookie comparisons. Could be replaced with references to
864 * specific Locales.
865 */
866 private static final RuleBasedCollator STRING_COLLATOR =
867 (RuleBasedCollator) RuleBasedCollator.getInstance(
868 new Locale("en", "US", ""));
869
870 /*** Log object for this class */
871 private static final Log LOG = LogFactory.getLog(Cookie.class);
872
873 }
874
This page was automatically generated by Maven