1 /*
2 * ====================================================================
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 * ====================================================================
20 *
21 * This software consists of voluntary contributions made by many
22 * individuals on behalf of the Apache Software Foundation. For more
23 * information on the Apache Software Foundation, please see
24 * <http://www.apache.org/>.
25 *
26 */
27
28 package org.apache.hc.client5.http.cookie;
29
30 import java.time.Instant;
31 import java.util.Date;
32
33 /**
34 * Cookie interface represents a token or short packet of state information
35 * (also referred to as "magic-cookie") that the HTTP agent and the target
36 * server can exchange to maintain a session. In its simples form an HTTP
37 * cookie is merely a name / value pair.
38 *
39 * @since 4.0
40 */
41 public interface Cookie {
42
43 String PATH_ATTR = "path";
44 String DOMAIN_ATTR = "domain";
45 String MAX_AGE_ATTR = "max-age";
46 String SECURE_ATTR = "secure";
47 String EXPIRES_ATTR = "expires";
48 String HTTP_ONLY_ATTR = "httpOnly";
49
50 /**
51 * @since 5.0
52 */
53 String getAttribute(String name);
54
55 /**
56 * @since 5.0
57 */
58 boolean containsAttribute(String name);
59
60 /**
61 * Returns the name.
62 *
63 * @return String name The name
64 */
65 String getName();
66
67 /**
68 * Returns the value.
69 *
70 * @return String value The current value.
71 */
72 String getValue();
73
74 /**
75 * Returns the expiration {@link Date} of the cookie, or {@code null}
76 * if none exists.
77 * <p><strong>Note:</strong> the object returned by this method is
78 * considered immutable. Changing it (e.g. using setTime()) could result
79 * in undefined behaviour. Do so at your peril. </p>
80 * @return Expiration {@link Date}, or {@code null}.
81 * @deprecated Use {{@link #getExpiryInstant()}}
82 */
83 @Deprecated
84 Date getExpiryDate();
85
86 /**
87 * Returns the expiration {@link Instant} of the cookie, or {@code null} if none exists.
88 * <p><strong>Note:</strong> the object returned by this method is
89 * considered immutable. Changing it (e.g. using setTime()) could result in undefined behaviour.
90 * Do so at your peril. </p>
91 *
92 * @return Expiration {@link Instant}, or {@code null}.
93 * @since 5.2
94 */
95 @SuppressWarnings("deprecated")
96 default Instant getExpiryInstant() {
97 final Date date = getExpiryDate();
98 return date != null ? Instant.ofEpochMilli(date.getTime()) : null;
99 }
100
101 /**
102 * Returns {@code false} if the cookie should be discarded at the end
103 * of the "session"; {@code true} otherwise.
104 *
105 * @return {@code false} if the cookie should be discarded at the end
106 * of the "session"; {@code true} otherwise
107 */
108 boolean isPersistent();
109
110 /**
111 * Returns domain attribute of the cookie. The value of the Domain
112 * attribute specifies the domain for which the cookie is valid.
113 *
114 * @return the value of the domain attribute.
115 */
116 String getDomain();
117
118 /**
119 * Returns the path attribute of the cookie. The value of the Path
120 * attribute specifies the subset of URLs on the origin server to which
121 * this cookie applies.
122 *
123 * @return The value of the path attribute.
124 */
125 String getPath();
126
127 /**
128 * Indicates whether this cookie requires a secure connection.
129 *
130 * @return {@code true} if this cookie should only be sent
131 * over secure connections, {@code false} otherwise.
132 */
133 boolean isSecure();
134
135 /**
136 * Returns true if this cookie has expired.
137 * @param date Current time
138 *
139 * @return {@code true} if the cookie has expired.
140 * @deprecated Use {{@link #isExpired(Instant)}}
141 */
142 @Deprecated
143 boolean isExpired(final Date date);
144
145 /**
146 * Returns true if this cookie has expired.
147 *
148 * @param date Current time
149 * @return {@code true} if the cookie has expired.
150 * @since 5.2
151 */
152 @SuppressWarnings("deprecation")
153 default boolean isExpired(final Instant date) {
154 return isExpired(date != null ? new Date(date.toEpochMilli()) : null);
155 }
156
157 /**
158 * Returns creation time of the cookie.
159 * @deprecated Use {@link #getCreationInstant()}
160 */
161 @Deprecated
162 Date getCreationDate();
163
164 /**
165 * Returns creation time of the cookie.
166 */
167 default Instant getCreationInstant() { return null; }
168
169 /**
170 * Checks whether this Cookie has been marked as {@code httpOnly}.
171 * <p>The default implementation returns {@code false}.
172 *
173 * @return true if this Cookie has been marked as {@code httpOnly},
174 * false otherwise
175 *
176 * @since 5.2
177 */
178 default boolean isHttpOnly(){
179 return false;
180 }
181
182 }
183