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