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