001 /*
002 * Copyright 2004 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package javax.servlet.http;
017
018 import java.util.Enumeration;
019 import javax.servlet.ServletContext;
020
021 /**
022 *
023 * Provides a way to identify a user across more than one page
024 * request or visit to a Web site and to store information about that user.
025 *
026 * <p>The servlet container uses this interface to create a session
027 * between an HTTP client and an HTTP server. The session persists
028 * for a specified time period, across more than one connection or
029 * page request from the user. A session usually corresponds to one
030 * user, who may visit a site many times. The server can maintain a
031 * session in many ways such as using cookies or rewriting URLs.
032 *
033 * <p>This interface allows servlets to
034 * <ul>
035 * <li>View and manipulate information about a session, such as
036 * the session identifier, creation time, and last accessed time
037 * <li>Bind objects to sessions, allowing user information to persist
038 * across multiple user connections
039 * </ul>
040 *
041 * <p>When an application stores an object in or removes an object from a
042 * session, the session checks whether the object implements
043 * {@link HttpSessionBindingListener}. If it does,
044 * the servlet notifies the object that it has been bound to or unbound
045 * from the session. Notifications are sent after the binding methods complete.
046 * For session that are invalidated or expire, notifications are sent after
047 * the session has been invalidated or expired.
048 *
049 * <p> When container migrates a session between VMs in a distributed container
050 * setting, all session attributes implementing the {@link HttpSessionActivationListener}
051 * interface are notified.
052 *
053 * <p>A servlet should be able to handle cases in which
054 * the client does not choose to join a session, such as when cookies are
055 * intentionally turned off. Until the client joins the session,
056 * <code>isNew</code> returns <code>true</code>. If the client chooses
057 * not to join
058 * the session, <code>getSession</code> will return a different session
059 * on each request, and <code>isNew</code> will always return
060 * <code>true</code>.
061 *
062 * <p>Session information is scoped only to the current web application
063 * (<code>ServletContext</code>), so information stored in one context
064 * will not be directly visible in another.
065 *
066 * @author Various
067 * @version $Version$
068 *
069 *
070 * @see HttpSessionBindingListener
071 * @see HttpSessionContext
072 *
073 */
074
075 public interface HttpSession {
076
077
078
079
080 /**
081 *
082 * Returns the time when this session was created, measured
083 * in milliseconds since midnight January 1, 1970 GMT.
084 *
085 * @return a <code>long</code> specifying
086 * when this session was created,
087 * expressed in
088 * milliseconds since 1/1/1970 GMT
089 *
090 * @exception IllegalStateException if this method is called on an
091 * invalidated session
092 *
093 */
094
095 public long getCreationTime();
096
097
098
099
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