View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.handler.codec.http;
17  
18  import java.util.Set;
19  
20  /**
21   * An interface defining an
22   * <a href="http://en.wikipedia.org/wiki/HTTP_cookie">HTTP cookie</a>.
23   */
24  public interface Cookie extends Comparable<Cookie> {
25  
26      /**
27       * Returns the name of this {@link Cookie}.
28       *
29       * @return The name of this {@link Cookie}
30       */
31      String name();
32  
33      /**
34       * Returns the value of this {@link Cookie}.
35       *
36       * @return The value of this {@link Cookie}
37       */
38      String value();
39  
40      /**
41       * Sets the value of this {@link Cookie}.
42       *
43       * @param value The value to set
44       */
45      void setValue(String value);
46  
47      /**
48       * Returns the raw value of this {@link Cookie},
49       * as it was set in original Set-Cookie header.
50       *
51       * @return The raw value of this {@link Cookie}
52       */
53      String rawValue();
54  
55      /**
56       * Sets the raw value of this {@link Cookie}.
57       *
58       * @param rawValue The raw value to set
59       */
60      void setRawValue(String rawValue);
61  
62      /**
63       * Returns the domain of this {@link Cookie}.
64       *
65       * @return The domain of this {@link Cookie}
66       */
67      String domain();
68  
69      /**
70       * Sets the domain of this {@link Cookie}.
71       *
72       * @param domain The domain to use
73       */
74      void setDomain(String domain);
75  
76      /**
77       * Returns the path of this {@link Cookie}.
78       *
79       * @return The {@link Cookie}'s path
80       */
81      String path();
82  
83      /**
84       * Sets the path of this {@link Cookie}.
85       *
86       * @param path The path to use for this {@link Cookie}
87       */
88      void setPath(String path);
89  
90      /**
91       * Returns the comment of this {@link Cookie}.
92       *
93       * @return The comment of this {@link Cookie}
94       */
95      String comment();
96  
97      /**
98       * Sets the comment of this {@link Cookie}.
99       *
100      * @param comment The comment to use
101      */
102     void setComment(String comment);
103 
104     /**
105      * Returns the maximum age of this {@link Cookie} in seconds or {@link Long#MIN_VALUE} if unspecified
106      *
107      * @return The maximum age of this {@link Cookie}
108      */
109     long maxAge();
110 
111     /**
112      * Sets the maximum age of this {@link Cookie} in seconds.
113      * If an age of {@code 0} is specified, this {@link Cookie} will be
114      * automatically removed by browser because it will expire immediately.
115      * If {@link Long#MIN_VALUE} is specified, this {@link Cookie} will be removed when the
116      * browser is closed.
117      *
118      * @param maxAge The maximum age of this {@link Cookie} in seconds
119      */
120     void setMaxAge(long maxAge);
121 
122     /**
123      * Returns the version of this {@link Cookie}.
124      *
125      * @return The version of this {@link Cookie}
126      */
127     int version();
128 
129     /**
130      * Sets the version of this {@link Cookie}.
131      *
132      * @param version The new version to use
133      */
134     void setVersion(int version);
135 
136     /**
137      * Checks to see if this {@link Cookie} is secure
138      *
139      * @return True if this {@link Cookie} is secure, otherwise false
140      */
141     boolean isSecure();
142 
143     /**
144      * Sets the security getStatus of this {@link Cookie}
145      *
146      * @param secure True if this {@link Cookie} is to be secure, otherwise false
147      */
148     void setSecure(boolean secure);
149 
150     /**
151      * Checks to see if this {@link Cookie} can only be accessed via HTTP.
152      * If this returns true, the {@link Cookie} cannot be accessed through
153      * client side script - But only if the browser supports it.
154      * For more information, please look <a href="http://www.owasp.org/index.php/HTTPOnly">here</a>
155      *
156      * @return True if this {@link Cookie} is HTTP-only or false if it isn't
157      */
158     boolean isHttpOnly();
159 
160     /**
161      * Determines if this {@link Cookie} is HTTP only.
162      * If set to true, this {@link Cookie} cannot be accessed by a client
163      * side script. However, this works only if the browser supports it.
164      * For for information, please look
165      * <a href="http://www.owasp.org/index.php/HTTPOnly">here</a>.
166      *
167      * @param httpOnly True if the {@link Cookie} is HTTP only, otherwise false.
168      */
169     void setHttpOnly(boolean httpOnly);
170 
171     /**
172      * Returns the comment URL of this {@link Cookie}.
173      *
174      * @return The comment URL of this {@link Cookie}
175      */
176     String commentUrl();
177 
178     /**
179      * Sets the comment URL of this {@link Cookie}.
180      *
181      * @param commentUrl The comment URL to use
182      */
183     void setCommentUrl(String commentUrl);
184 
185     /**
186      * Checks to see if this {@link Cookie} is to be discarded by the browser
187      * at the end of the current session.
188      *
189      * @return True if this {@link Cookie} is to be discarded, otherwise false
190      */
191     boolean isDiscard();
192 
193     /**
194      * Sets the discard flag of this {@link Cookie}.
195      * If set to true, this {@link Cookie} will be discarded by the browser
196      * at the end of the current session
197      *
198      * @param discard True if the {@link Cookie} is to be discarded
199      */
200     void setDiscard(boolean discard);
201 
202     /**
203      * Returns the ports that this {@link Cookie} can be accessed on.
204      *
205      * @return The {@link Set} of ports that this {@link Cookie} can use
206      */
207     Set<Integer> ports();
208 
209     /**
210      * Sets the ports that this {@link Cookie} can be accessed on.
211      *
212      * @param ports The ports that this {@link Cookie} can be accessed on
213      */
214     void setPorts(int... ports);
215 
216     /**
217      * Sets the ports that this {@link Cookie} can be accessed on.
218      *
219      * @param ports The {@link Iterable} collection of ports that this
220      *              {@link Cookie} can be accessed on.
221      */
222     void setPorts(Iterable<Integer> ports);
223 }