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