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