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