View Javadoc

1   /*
2    * $Header: /cvsroot/httpc-cookie2/httpc-cookie2/httpcookie2SVN-patch.082805-2100.diff,v 1.1 2005/08/29 05:01:58 sjain700 Exp $
3    * $Revision:400312 $
4    * $Date:2006-05-06 14:49:41 +0200 (Sat, 06 May 2006) $
5    *
6    * ====================================================================
7    *
8    *  Copyright 1999-2004 The Apache Software Foundation
9    *
10   *  Licensed under the Apache License, Version 2.0 (the "License");
11   *  you may not use this file except in compliance with the License.
12   *  You may obtain a copy of the License at
13   *
14   *      http://www.apache.org/licenses/LICENSE-2.0
15   *
16   *  Unless required by applicable law or agreed to in writing, software
17   *  distributed under the License is distributed on an "AS IS" BASIS,
18   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   *  See the License for the specific language governing permissions and
20   *  limitations under the License.
21   * ====================================================================
22   *
23   * This software consists of voluntary contributions made by many
24   * individuals on behalf of the Apache Software Foundation.  For more
25   * information on the Apache Software Foundation, please see
26   * <http://www.apache.org/>.
27   *
28   */
29  
30  package org.apache.commons.httpclient.cookie;
31  
32  import java.util.Date;
33  
34  import org.apache.commons.httpclient.Cookie;
35  
36  /***
37   * <p>
38   * Cookie class for {@link org.apache.commons.httpclient.cookie.RFC2965Spec}
39   * cookie specification. It extends {@link Cookie} class and adds newer cookie
40   * attributes and functions required for this specification.
41   * </p>
42   *
43   * @author Samit Jain (jain.samit@gmail.com)
44   * 
45   * @since 3.1
46   */
47  public class Cookie2 extends Cookie {
48  
49      // string constants for cookie attributes
50      public static final String DOMAIN = "domain";
51      public static final String PATH = "path";
52      public static final String PORT = "port";
53      public static final String VERSION = "version";
54      public static final String SECURE = "secure";
55      public static final String MAXAGE = "max-age";
56      public static final String COMMENT = "comment";
57      public static final String COMMENTURL = "commenturl";
58      public static final String DISCARD = "discard";
59  
60      /***
61       * Default constructor. Creates a blank cookie
62       */
63      public Cookie2() {
64          super(null, "noname", null, null, null, false);
65      }
66  
67      /***
68       * Creates a cookie with the given name, value and domain attribute.
69       *
70       * @param name    the cookie name
71       * @param value   the cookie value
72       * @param domain  the domain this cookie can be sent to
73       */
74      public Cookie2(String domain, String name, String value) {
75          super(domain, name, value);
76      }
77  
78      /***
79       * Creates a cookie with the given name, value, domain attribute,
80       * path attribute, expiration attribute, and secure attribute
81       *
82       * @param name    the cookie name
83       * @param value   the cookie value
84       * @param domain  the domain this cookie can be sent to
85       * @param path    the path prefix for which this cookie can be sent
86       * @param expires the {@link Date} at which this cookie expires,
87       *                or <tt>null</tt> if the cookie expires at the end
88       *                of the session
89       * @param secure if true this cookie can only be sent over secure
90       * connections
91       * @throws IllegalArgumentException If cookie name is null or blank,
92       *   cookie name contains a blank, or cookie name starts with character $
93       *
94       */
95      public Cookie2(String domain, String name, String value,
96                     String path, Date expires, boolean secure) {
97          super(domain, name, value, path, expires, secure);
98      }
99  
100     /***
101      * Creates a cookie with the given name, value, domain attribute,
102      * path attribute, expiration attribute, secure attribute, and ports
103      * attribute.
104      *
105      * @param name    the cookie name
106      * @param value   the cookie value
107      * @param domain  the domain this cookie can be sent to
108      * @param path    the path prefix for which this cookie can be sent
109      * @param expires the {@link Date} at which this cookie expires,
110      *                or <tt>null</tt> if the cookie expires at the end
111      *                of the session
112      * @param secure if true this cookie can only be sent over secure
113      * connections
114      * @param ports   the ports for which this cookie can be sent
115      * @throws IllegalArgumentException If cookie name is null or blank,
116      *   cookie name contains a blank, or cookie name starts with character $
117      *
118      */
119     public Cookie2(String domain, String name, String value,
120                    String path, Date expires, boolean secure, int[] ports) {
121         super(domain, name, value, path, expires, secure);
122         setPorts(ports);
123     }
124 
125    /***
126      * If a user agent (web browser) presents this cookie to a user, the
127      * cookie's purpose will be described by the information at this URL.
128      *
129      * @see #setCommentURL(String)
130      */
131     public String getCommentURL() {
132         return cookieCommentURL;
133     }
134 
135    /***
136      * If a user agent (web browser) presents this cookie to a user, the
137      * cookie's purpose will be described by the information at this URL.
138      *
139      * @param commentURL
140      *
141      * @see #getCommentURL()
142      */
143     public void setCommentURL(String commentURL) {
144         this.cookieCommentURL = commentURL;
145     }
146 
147     /***
148      * Get the Port attribute. It restricts the ports to which a cookie
149      * may be returned in a Cookie request header.
150      *
151      * @see #setPorts(int[])
152      */
153     public int[] getPorts() {
154         return cookiePorts;
155     }
156 
157    /***
158      * Set the Port attribute. It restricts the ports to which a cookie
159      * may be returned in a Cookie request header.
160      *
161      * @param ports
162      *
163      * @see #getPorts()
164      */
165     public void setPorts(int[] ports) {
166         this.cookiePorts = ports;
167     }
168 
169     /***
170      * Set the Discard attribute.
171      *
172      * Note: <tt>Discard</tt> attribute overrides <tt>Max-age</tt>.
173      *
174      * @see #isPersistent()
175      */
176     public void setDiscard(boolean toDiscard) {
177         discard = toDiscard;
178     }
179 
180     /***
181      * Returns <tt>false</tt> if the cookie should be discarded at the end
182      * of the "session"; <tt>true</tt> otherwise.
183      *
184      * @return <tt>false</tt> if the cookie should be discarded at the end
185      *         of the "session"; <tt>true</tt> otherwise
186      */
187     public boolean isPersistent() {
188         return (null != getExpiryDate()) && !discard;
189     }
190 
191     /***
192      * Indicates whether the cookie had a port attribute specified in the
193      * <tt>Set-Cookie2</tt> response header. 
194      *
195      * @param value <tt>true</tt> if port attribute is specified in response
196      * header.
197      *
198      * @see #isPortAttributeSpecified
199      */
200     public void setPortAttributeSpecified(boolean value) {
201         hasPortAttribute = value;
202     }
203 
204     /***
205      * @return <tt>true</tt> if cookie port attribute was specified in the
206      * <tt>Set-Cookie2</tt> header.
207      *
208      * @see #setPortAttributeSpecified
209      */
210     public boolean isPortAttributeSpecified() {
211         return hasPortAttribute;
212     }
213 
214     /***
215      * Indicates whether the Port attribute in <tt>Set-Cookie2</tt> header
216      * contains no value (is of the form Port="").
217      * <p>
218      * This value is required for generating
219      * the <tt>Cookie</tt> request header because the specification requires that if
220      * <tt>Set-Cookie2</tt> header contains a blank value for port attribute,
221      * the <tt>Cookie</tt> header should also contain a port attribute with no value.
222      *
223      * @param value <tt>true</tt> if port attribute is specified as blank in response
224      * header.
225      *
226      * @see #isPortAttributeBlank
227      */
228     public void setPortAttributeBlank(boolean value) {
229         isPortAttributeBlank = value;
230     }
231 
232     /***
233      * @return <tt>true</tt> if the port attribute in <tt>Set-Cookie2</tt> header
234      * had no value (was of the form Port="").
235      *
236      * @see #setPortAttributeBlank
237      */
238     public boolean isPortAttributeBlank() {
239         return isPortAttributeBlank;
240     }
241 
242     /***
243      * Indicates whether the cookie had a version attribute specified in the
244      * <tt>Set-Cookie2</tt> response header. 
245      *
246      * @param value <tt>true</tt> if version attribute is specified in response
247      * header.
248      * @see #isVersionAttributeSpecified()
249      */
250     public void setVersionAttributeSpecified(boolean value) {
251         hasVersionAttribute = value;
252     }
253 
254     /***
255      * @return <tt>true</tt> if cookie version attribute was specified in the
256      * <tt>Set-Cookie2</tt> header.
257      *
258      * @see #setVersionAttributeSpecified
259      */
260     public boolean isVersionAttributeSpecified() {
261         return hasVersionAttribute;
262     }
263 
264     /***
265      * Return a textual representation of the cookie.
266      *
267      * @return string.
268      */
269     public String toExternalForm() {
270         CookieSpec spec =
271                 CookiePolicy.getCookieSpec(CookiePolicy.RFC_2965);
272         return spec.formatCookie(this);
273     }
274 
275     /***
276      * Comment URL attribute
277      */
278     private String cookieCommentURL;
279 
280     /***
281      * Port attribute.
282      */
283     private int[] cookiePorts;
284 
285     /***
286      * Discard attribute.
287      */
288     private boolean discard = false;
289 
290     /***
291      * Indicates if the set-cookie2 header included a Port attribute for this
292      * cookie
293      */
294     private boolean hasPortAttribute = false;
295 
296     /***
297      * Indicates if the set-cookie2 header's Port attribute did not have
298      * any value.
299      */
300     private boolean isPortAttributeBlank = false;
301 
302     /***
303      * Indicates if the set-cookie2 header included a Version attribute
304      */
305     private boolean hasVersionAttribute = false;
306 
307 
308 }
309