1
2
3 /*
4 * The contents of this file are subject to the terms
5 * of the Common Development and Distribution License
6 * (the "License"). You may not use this file except
7 * in compliance with the License.
8 *
9 * You can obtain a copy of the license at
10 * glassfish/bootstrap/legal/CDDLv1.0.txt or
11 * https://glassfish.dev.java.net/public/CDDLv1.0.html.
12 * See the License for the specific language governing
13 * permissions and limitations under the License.
14 *
15 * When distributing Covered Code, include this CDDL
16 * HEADER in each file and include the License file at
17 * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
18 * add the following below this CDDL HEADER, with the
19 * fields enclosed by brackets "[]" replaced with your
20 * own identifying information: Portions Copyright [yyyy]
21 * [name of copyright owner]
22 *
23 * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
24 *
25 * Portions Copyright Apache Software Foundation.
26 */
27
28 package javax.servlet.http;
29
30 import java.util.Enumeration;
31 import javax.servlet.ServletContext;
32
33 /**
34 *
35 * Provides a way to identify a user across more than one page
36 * request or visit to a Web site and to store information about that user.
37 *
38 * <p>The servlet container uses this interface to create a session
39 * between an HTTP client and an HTTP server. The session persists
40 * for a specified time period, across more than one connection or
41 * page request from the user. A session usually corresponds to one
42 * user, who may visit a site many times. The server can maintain a
43 * session in many ways such as using cookies or rewriting URLs.
44 *
45 * <p>This interface allows servlets to
46 * <ul>
47 * <li>View and manipulate information about a session, such as
48 * the session identifier, creation time, and last accessed time
49 * <li>Bind objects to sessions, allowing user information to persist
50 * across multiple user connections
51 * </ul>
52 *
53 * <p>When an application stores an object in or removes an object from a
54 * session, the session checks whether the object implements
55 * {@link HttpSessionBindingListener}. If it does,
56 * the servlet notifies the object that it has been bound to or unbound
57 * from the session. Notifications are sent after the binding methods complete.
58 * For session that are invalidated or expire, notifications are sent after
59 * the session has been invalidated or expired.
60 *
61 * <p> When container migrates a session between VMs in a distributed container
62 * setting, all session attributes implementing the {@link HttpSessionActivationListener}
63 * interface are notified.
64 *
65 * <p>A servlet should be able to handle cases in which
66 * the client does not choose to join a session, such as when cookies are
67 * intentionally turned off. Until the client joins the session,
68 * <code>isNew</code> returns <code>true</code>. If the client chooses
69 * not to join
70 * the session, <code>getSession</code> will return a different session
71 * on each request, and <code>isNew</code> will always return
72 * <code>true</code>.
73 *
74 * <p>Session information is scoped only to the current web application
75 * (<code>ServletContext</code>), so information stored in one context
76 * will not be directly visible in another.
77 *
78 * @author Various
79 *
80 * @see HttpSessionBindingListener
81 * @see HttpSessionContext
82 *
83 */
84
85 public interface HttpSession {
86
87
88
89
90 /**
91 *
92 * Returns the time when this session was created, measured
93 * in milliseconds since midnight January 1, 1970 GMT.
94 *
95 * @return a <code>long</code> specifying
96 * when this session was created,
97 * expressed in
98 * milliseconds since 1/1/1970 GMT
99 *
100 * @exception IllegalStateException if this method is called on an
101 * invalidated session
102 *
103 */
104
105 public long getCreationTime();
106
107
108
109
110 /**
111 *
112 * Returns a string containing the unique identifier assigned
113 * to this session. The identifier is assigned
114 * by the servlet container and is implementation dependent.
115 *
116 * @return a string specifying the identifier
117 * assigned to this session
118 */
119
120 public String getId();
121
122
123
124
125 /**
126 *
127 * Returns the last time the client sent a request associated with
128 * this session, as the number of milliseconds since midnight
129 * January 1, 1970 GMT, and marked by the time the container received the request.
130 *
131 * <p>Actions that your application takes, such as getting or setting
132 * a value associated with the session, do not affect the access
133 * time.
134 *
135 * @return a <code>long</code>
136 * representing the last time
137 * the client sent a request associated
138 * with this session, expressed in
139 * milliseconds since 1/1/1970 GMT
140 *
141 * @exception IllegalStateException if this method is called on an
142 * invalidated session
143 *
144 */
145
146 public long getLastAccessedTime();
147
148
149 /**
150 * Returns the ServletContext to which this session belongs.
151 *
152 * @return The ServletContext object for the web application
153 * @since 2.3
154 */
155
156 public ServletContext getServletContext();
157
158
159 /**
160 *
161 * Specifies the time, in seconds, between client requests before the
162 * servlet container will invalidate this session. A negative time
163 * indicates the session should never timeout.
164 *
165 * @param interval An integer specifying the number
166 * of seconds
167 *
168 */
169
170 public void setMaxInactiveInterval(int interval);
171
172
173
174
175 /**
176 * Returns the maximum time interval, in seconds, that
177 * the servlet container will keep this session open between
178 * client accesses. After this interval, the servlet container
179 * will invalidate the session. The maximum time interval can be set
180 * with the <code>setMaxInactiveInterval</code> method.
181 * A negative time indicates the session should never timeout.
182 *
183 *
184 * @return an integer specifying the number of
185 * seconds this session remains open
186 * between client requests
187 *
188 * @see #setMaxInactiveInterval
189 *
190 *
191 */
192
193 public int getMaxInactiveInterval();
194
195
196
197
198 /**
199 *
200 * @deprecated As of Version 2.1, this method is
201 * deprecated and has no replacement.
202 * It will be removed in a future
203 * version of the Java Servlet API.
204 *
205 */
206
207 public HttpSessionContext getSessionContext();
208
209
210
211
212 /**
213 *
214 * Returns the object bound with the specified name in this session, or
215 * <code>null</code> if no object is bound under the name.
216 *
217 * @param name a string specifying the name of the object
218 *
219 * @return the object with the specified name
220 *
221 * @exception IllegalStateException if this method is called on an
222 * invalidated session
223 *
224 */
225
226 public Object getAttribute(String name);
227
228
229
230
231 /**
232 *
233 * @deprecated As of Version 2.2, this method is
234 * replaced by {@link #getAttribute}.
235 *
236 * @param name a string specifying the name of the object
237 *
238 * @return the object with the specified name
239 *
240 * @exception IllegalStateException if this method is called on an
241 * invalidated session
242 *
243 */
244
245 public Object getValue(String name);
246
247
248
249
250 /**
251 *
252 * Returns an <code>Enumeration</code> of <code>String</code> objects
253 * containing the names of all the objects bound to this session.
254 *
255 * @return an <code>Enumeration</code> of
256 * <code>String</code> objects specifying the
257 * names of all the objects bound to
258 * this session
259 *
260 * @exception IllegalStateException if this method is called on an
261 * invalidated session
262 *
263 */
264
265 public Enumeration getAttributeNames();
266
267
268
269
270 /**
271 *
272 * @deprecated As of Version 2.2, this method is
273 * replaced by {@link #getAttributeNames}
274 *
275 * @return an array of <code>String</code>
276 * objects specifying the
277 * names of all the objects bound to
278 * this session
279 *
280 * @exception IllegalStateException if this method is called on an
281 * invalidated session
282 *
283 */
284
285 public String[] getValueNames();
286
287
288
289
290 /**
291 * Binds an object to this session, using the name specified.
292 * If an object of the same name is already bound to the session,
293 * the object is replaced.
294 *
295 * <p>After this method executes, and if the new object
296 * implements <code>HttpSessionBindingListener</code>,
297 * the container calls
298 * <code>HttpSessionBindingListener.valueBound</code>. The container then
299 * notifies any <code>HttpSessionAttributeListener</code>s in the web
300 * application.
301
302 * <p>If an object was already bound to this session of this name
303 * that implements <code>HttpSessionBindingListener</code>, its
304 * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
305 *
306 * <p>If the value passed in is null, this has the same effect as calling
307 * <code>removeAttribute()<code>.
308 *
309 *
310 * @param name the name to which the object is bound;
311 * cannot be null
312 *
313 * @param value the object to be bound
314 *
315 * @exception IllegalStateException if this method is called on an
316 * invalidated session
317 *
318 */
319
320 public void setAttribute(String name, Object value);
321
322
323
324
325
326 /**
327 *
328 * @deprecated As of Version 2.2, this method is
329 * replaced by {@link #setAttribute}
330 *
331 * @param name the name to which the object is bound;
332 * cannot be null
333 *
334 * @param value the object to be bound; cannot be null
335 *
336 * @exception IllegalStateException if this method is called on an
337 * invalidated session
338 *
339 */
340
341 public void putValue(String name, Object value);
342
343
344
345
346
347 /**
348 *
349 * Removes the object bound with the specified name from
350 * this session. If the session does not have an object
351 * bound with the specified name, this method does nothing.
352 *
353 * <p>After this method executes, and if the object
354 * implements <code>HttpSessionBindingListener</code>,
355 * the container calls
356 * <code>HttpSessionBindingListener.valueUnbound</code>. The container
357 * then notifies any <code>HttpSessionAttributeListener</code>s in the web
358 * application.
359 *
360 *
361 *
362 * @param name the name of the object to
363 * remove from this session
364 *
365 * @exception IllegalStateException if this method is called on an
366 * invalidated session
367 */
368
369 public void removeAttribute(String name);
370
371
372
373
374
375 /**
376 *
377 * @deprecated As of Version 2.2, this method is
378 * replaced by {@link #removeAttribute}
379 *
380 * @param name the name of the object to
381 * remove from this session
382 *
383 * @exception IllegalStateException if this method is called on an
384 * invalidated session
385 */
386
387 public void removeValue(String name);
388
389
390
391
392 /**
393 *
394 * Invalidates this session then unbinds any objects bound
395 * to it.
396 *
397 * @exception IllegalStateException if this method is called on an
398 * already invalidated session
399 *
400 */
401
402 public void invalidate();
403
404
405
406
407 /**
408 *
409 * Returns <code>true</code> if the client does not yet know about the
410 * session or if the client chooses not to join the session. For
411 * example, if the server used only cookie-based sessions, and
412 * the client had disabled the use of cookies, then a session would
413 * be new on each request.
414 *
415 * @return <code>true</code> if the
416 * server has created a session,
417 * but the client has not yet joined
418 *
419 * @exception IllegalStateException if this method is called on an
420 * already invalidated session
421 *
422 */
423
424 public boolean isNew();
425
426
427
428 }
429