-
Notifications
You must be signed in to change notification settings - Fork 78
/
SessionCookieConfig.java
277 lines (257 loc) · 12.7 KB
/
SessionCookieConfig.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
/*
* Copyright (c) 2017, 2020 Oracle and/or its affiliates and others.
* All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.servlet;
import java.util.Map;
/**
* Class that may be used to configure various properties of cookies used for session tracking purposes.
*
* <p>
* An instance of this class is acquired by a call to {@link ServletContext#getSessionCookieConfig}.
*
* @since Servlet 3.0
*/
public interface SessionCookieConfig {
/**
* Sets the name that will be assigned to any session tracking cookies created on behalf of the application represented
* by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* <p>
* NOTE: Changing the name of session tracking cookies may break other tiers (for example, a load balancing frontend)
* that assume the cookie name to be equal to the default <tt>JSESSIONID</tt>, and therefore should only be done
* cautiously.
*
* @param name the cookie name to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*/
public void setName(String name);
/**
* Gets the name that will be assigned to any session tracking cookies created on behalf of the application represented
* by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* <p>
* By default, <tt>JSESSIONID</tt> will be used as the cookie name.
*
* @return the cookie name set via {@link #setName}, or <tt>null</tt> if {@link #setName} was never called
*
* @see jakarta.servlet.http.Cookie#getName()
*/
public String getName();
/**
* Sets the domain name that will be assigned to any session tracking cookies created on behalf of the application
* represented by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @param domain the cookie domain to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setDomain(String)
*/
public void setDomain(String domain);
/**
* Gets the domain name that will be assigned to any session tracking cookies created on behalf of the application
* represented by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @return the cookie domain set via {@link #setDomain}, or <tt>null</tt> if {@link #setDomain} was never called
*
* @see jakarta.servlet.http.Cookie#getDomain()
*/
public String getDomain();
/**
* Sets the path that will be assigned to any session tracking cookies created on behalf of the application represented
* by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @param path the cookie path to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setPath(String)
*/
public void setPath(String path);
/**
* Gets the path that will be assigned to any session tracking cookies created on behalf of the application represented
* by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* <p>
* By default, the context path of the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired
* will be used.
*
* @return the cookie path set via {@link #setPath}, or <tt>null</tt> if {@link #setPath} was never called
*
* @see jakarta.servlet.http.Cookie#getPath()
*/
public String getPath();
/**
* Sets the comment that will be assigned to any session tracking cookies created on behalf of the application
* represented by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* <p>
* As a side effect of this call, the session tracking cookies will be marked with a <code>Version</code> attribute
* equal to <code>1</code>.
*
* @param comment the cookie comment to use
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setComment(String)
* @see jakarta.servlet.http.Cookie#getVersion
*/
public void setComment(String comment);
/**
* Gets the comment that will be assigned to any session tracking cookies created on behalf of the application
* represented by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @return the cookie comment set via {@link #setComment}, or <tt>null</tt> if {@link #setComment} was never called
*
* @see jakarta.servlet.http.Cookie#getComment()
*/
public String getComment();
/**
* Marks or unmarks the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired as <i>HttpOnly</i>.
*
* <p>
* A cookie is marked as <tt>HttpOnly</tt> by adding the <tt>HttpOnly</tt> attribute to it. <i>HttpOnly</i> cookies are
* not supposed to be exposed to client-side scripting code, and may therefore help mitigate certain kinds of cross-site
* scripting attacks.
*
* @param httpOnly true if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired shall be marked as <i>HttpOnly</i>,
* false otherwise
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setHttpOnly(boolean)
*/
public void setHttpOnly(boolean httpOnly);
/**
* Checks if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired will be marked as <i>HttpOnly</i>.
*
* @return true if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired will be marked as <i>HttpOnly</i>,
* false otherwise
*
* @see jakarta.servlet.http.Cookie#isHttpOnly()
*/
public boolean isHttpOnly();
/**
* Marks or unmarks the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired as <i>secure</i>.
*
* <p>
* One use case for marking a session tracking cookie as <tt>secure</tt>, even though the request that initiated the
* session came over HTTP, is to support a topology where the web container is front-ended by an SSL offloading load
* balancer. In this case, the traffic between the client and the load balancer will be over HTTPS, whereas the traffic
* between the load balancer and the web container will be over HTTP.
*
* @param secure true if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired shall be marked as <i>secure</i>
* even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS, and false if they
* shall be marked as <i>secure</i> only if the request that initiated the corresponding session was also secure
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setSecure(boolean)
* @see ServletRequest#isSecure()
*/
public void setSecure(boolean secure);
/**
* Checks if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired will be marked as <i>secure</i>
* even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS.
*
* @return true if the session tracking cookies created on behalf of the application represented by the
* <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired will be marked as <i>secure</i>
* even if the request that initiated the corresponding session is using plain HTTP instead of HTTPS, and false if they
* will be marked as <i>secure</i> only if the request that initiated the corresponding session was also secure
*
* @see jakarta.servlet.http.Cookie#getSecure()
* @see ServletRequest#isSecure()
*/
public boolean isSecure();
/**
* Sets the lifetime (in seconds) for the session tracking cookies created on behalf of the application represented by
* the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @param maxAge the lifetime (in seconds) of the session tracking cookies created on behalf of the application
* represented by the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* @throws IllegalStateException if the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was
* acquired has already been initialized
*
* @see jakarta.servlet.http.Cookie#setMaxAge
*/
public void setMaxAge(int maxAge);
/**
* Gets the lifetime (in seconds) of the session tracking cookies created on behalf of the application represented by
* the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired.
*
* <p>
* By default, <tt>-1</tt> is returned.
*
* @return the lifetime (in seconds) of the session tracking cookies created on behalf of the application represented by
* the <tt>ServletContext</tt> from which this <tt>SessionCookieConfig</tt> was acquired, or <tt>-1</tt> (the default)
*
* @see jakarta.servlet.http.Cookie#getMaxAge
*/
public int getMaxAge();
/**
* Sets the value for the given session cookie attribute. When a value is set via this method, the value returned by the
* attribute specific getter (if any) must be consistent with the value set via this method.
*
* @param name Name of attribute to set, case insensitive
* @param value Value of attribute
*
* @throws IllegalStateException if the associated ServletContext has already been initialised
*
* @throws IllegalArgumentException If the attribute name is null or contains any characters not permitted for use in
* Cookie names.
*
* @throws NumberFormatException If the attribute is known to be numerical but the provided value cannot be parsed to a
* number.
*
* @since Servlet 6.0
*/
public void setAttribute(String name, String value);
/**
* Obtain the value for a given session cookie attribute. Values returned from this method must be consistent with the
* values set and returned by the attribute specific getters and setters in this class.
*
* @param name Name of attribute to return, case insensitive
*
* @return Value of specified attribute
*
* @since Servlet 6.0
*/
public String getAttribute(String name);
/**
* Obtain the Map (keys are case insensitive) of all attributes and values, including those set via the attribute
* specific setters, (excluding version) for this <tt>SessionCookieConfig</tt>.
*
* @return A read-only Map of attributes to values, excluding version.
*
* @since Servlet 6.0
*/
public Map<String, String> getAttributes();
}