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.util.Date;
31
32 /**
33 * Cookie interface represents a token or short packet of state information
34 * (also referred to as "magic-cookie") that the HTTP agent and the target
35 * server can exchange to maintain a session. In its simples form an HTTP
36 * cookie is merely a name / value pair.
37 *
38 * @since 4.0
39 */
40 public interface Cookie {
41
42 String PATH_ATTR = "path";
43 String DOMAIN_ATTR = "domain";
44 String MAX_AGE_ATTR = "max-age";
45 String SECURE_ATTR = "secure";
46 String EXPIRES_ATTR = "expires";
47
48 /**
49 * @since 5.0
50 */
51 String getAttribute(String name);
52
53 /**
54 * @since 5.0
55 */
56 boolean containsAttribute(String name);
57
58 /**
59 * Returns the name.
60 *
61 * @return String name The name
62 */
63 String getName();
64
65 /**
66 * Returns the value.
67 *
68 * @return String value The current value.
69 */
70 String getValue();
71
72 /**
73 * Returns the expiration {@link Date} of the cookie, or {@code null}
74 * if none exists.
75 * <p><strong>Note:</strong> the object returned by this method is
76 * considered immutable. Changing it (e.g. using setTime()) could result
77 * in undefined behaviour. Do so at your peril. </p>
78 * @return Expiration {@link Date}, or {@code null}.
79 */
80 Date getExpiryDate();
81
82 /**
83 * Returns {@code false} if the cookie should be discarded at the end
84 * of the "session"; {@code true} otherwise.
85 *
86 * @return {@code false} if the cookie should be discarded at the end
87 * of the "session"; {@code true} otherwise
88 */
89 boolean isPersistent();
90
91 /**
92 * Returns domain attribute of the cookie. The value of the Domain
93 * attribute specifies the domain for which the cookie is valid.
94 *
95 * @return the value of the domain attribute.
96 */
97 String getDomain();
98
99 /**
100 * Returns the path attribute of the cookie. The value of the Path
101 * attribute specifies the subset of URLs on the origin server to which
102 * this cookie applies.
103 *
104 * @return The value of the path attribute.
105 */
106 String getPath();
107
108 /**
109 * Indicates whether this cookie requires a secure connection.
110 *
111 * @return {@code true} if this cookie should only be sent
112 * over secure connections, {@code false} otherwise.
113 */
114 boolean isSecure();
115
116 /**
117 * Returns true if this cookie has expired.
118 * @param date Current time
119 *
120 * @return {@code true} if the cookie has expired.
121 */
122 boolean isExpired(final Date date);
123
124 /**
125 * Returns creation time of the cookie.
126 */
127 Date getCreationDate();
128
129 }
130