Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * Licensed to the Apache Software Foundation (ASF) under one or more3 * contributor license agreements. See the NOTICE file distributed with4 * this work for additional information regarding copyright ownership.5 * The ASF licenses this file to You under the Apache License, Version 2.06 * (the "License"); you may not use this file except in compliance with7 * the License. You may obtain a copy of the License at8 *9 * http://www.apache.org/licenses/LICENSE-2.010 *11 * Unless required by applicable law or agreed to in writing, software12 * 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 and15 * limitations under the License.16 */17 package javax.servlet.http;18 19 importjava.util.Enumeration;20 importjavax.servlet.ServletContext;21 22 /**23 *24 * Provides a way to identify a user across more than one page25 * 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 session28 * between an HTTP client and an HTTP server. The session persists29 * for a specified time period, across more than one connection or30 * 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 as37 * the session identifier, creation time, and last accessed time38 * <li>Bind objects to sessions, allowing user information to persist 39 * across multiple user connections40 * </ul>41 *42 * <p>When an application stores an object in or removes an object from a43 * session, the session checks whether the object implements44 * {@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 after48 * the session has been invalidated or expired.49 *50 * <p> When container migrates a session between VMs in a distributed container51 * setting, all session attributes implementing the {@link HttpSessionActivationListener}52 * interface are notified.53 * 54 * <p>A servlet should be able to handle cases in which55 * the client does not choose to join a session, such as when cookies are56 * intentionally turned off. Until the client joins the session,57 * <code>isNew</code> returns <code>true</code>. If the client chooses 58 * not to join59 * the session, <code>getSession</code> will return a different session60 * on each request, and <code>isNew</code> will always return61 * <code>true</code>.62 *63 * <p>Session information is scoped only to the current web application64 * (<code>ServletContext</code>), so information stored in one context65 * will not be directly visible in another.66 *67 * @author Various68 * @version $Version$69 *70 *71 * @see HttpSessionBindingListener72 * @see HttpSessionContext73 *74 */75 76 publicinterface HttpSession {77 78 79 80 81 /**82 *83 * Returns the time when this session was created, measured84 * in milliseconds since midnight January 1, 1970 GMT.85 *86 * @return a <code>long</code> specifying87 * when this session was created,88 * expressed in 89 * milliseconds since 1/1/1970 GMT90 *91 * @exception IllegalStateException if this method is called on an92 * invalidated session93 *94 */95 96 publiclong 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 identifier108 * assigned to this session109 *110 * @exception IllegalStateException if this method is called on an111 * invalidated session112 *113 */114 115 publicString getId();116 117 118 119 120 /**121 *122 * Returns the last time the client sent a request associated with123 * this session, as the number of milliseconds since midnight124 * 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 setting127 * a value associated with the session, do not affect the access128 * time.129 *130 * @return a <code>long</code>131 * representing the last time 132 * the client sent a request associated133 * with this session, expressed in 134 * milliseconds since 1/1/1970 GMT135 *136 * @exception IllegalStateException if this method is called on an137 * invalidated session138 *139 */140 141 publiclong getLastAccessedTime();142 143 144 /**145 * Returns the ServletContext to which this session belongs.146 * 147 * @return The ServletContext object for the web application148 * @since 2.3149 */150 151 publicServletContext 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 time158 * indicates the session should never timeout.159 *160 * @param interval An integer specifying the number161 * of seconds 162 *163 */164 165 publicvoid 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 container174 * will invalidate the session. The maximum time interval can be set175 * 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 of180 * seconds this session remains open181 * between client requests182 *183 * @see #setMaxInactiveInterval184 *185 *186 */187 188 publicint getMaxInactiveInterval();189 190 191 192 193 /**194 *195 * @deprecated As of Version 2.1, this method is196 * deprecated and has no replacement.197 * It will be removed in a future198 * version of the Java Servlet API.199 *200 */201 202 publicHttpSessionContext getSessionContext();203 204 205 206 207 /**208 *209 * Returns the object bound with the specified name in this session, or210 * <code>null</code> if no object is bound under the name.211 *212 * @param name a string specifying the name of the object213 *214 * @return the object with the specified name215 *216 * @exception IllegalStateException if this method is called on an217 * invalidated session218 *219 */220 221 publicObject getAttribute(String name);222 223 224 225 226 /**227 *228 * @deprecated As of Version 2.2, this method is229 * replaced by {@link #getAttribute}.230 *231 * @param name a string specifying the name of the object232 *233 * @return the object with the specified name234 *235 * @exception IllegalStateException if this method is called on an236 * invalidated session237 *238 */239 240 publicObject getValue(String name);241 242 243 244 245 /**246 *247 * Returns an <code>Enumeration</code> of <code>String</code> objects248 * 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 the252 * names of all the objects bound to253 * this session254 *255 * @exception IllegalStateException if this method is called on an256 * invalidated session257 *258 */259 260 publicEnumeration getAttributeNames();261 262 263 264 265 /**266 *267 * @deprecated As of Version 2.2, this method is268 * replaced by {@link #getAttributeNames}269 *270 * @return an array of <code>String</code>271 * objects specifying the272 * names of all the objects bound to273 * this session274 *275 * @exception IllegalStateException if this method is called on an276 * invalidated session277 *278 */279 280 publicString[] 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 object291 * 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 name298 * 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 null307 *308 * @param value the object to be bound309 *310 * @exception IllegalStateException if this method is called on an311 * invalidated session312 *313 */314 315 publicvoid setAttribute(String name, Object value);316 317 318 319 320 321 /**322 *323 * @deprecated As of Version 2.2, this method is324 * replaced by {@link #setAttribute}325 *326 * @param name the name to which the object is bound;327 * cannot be null328 *329 * @param value the object to be bound; cannot be null330 *331 * @exception IllegalStateException if this method is called on an332 * invalidated session333 *334 */335 336 publicvoid putValue(String name, Object value);337 338 339 340 341 342 /**343 *344 * Removes the object bound with the specified name from345 * this session. If the session does not have an object346 * bound with the specified name, this method does nothing.347 *348 * <p>After this method executes, and if the object349 * implements <code>HttpSessionBindingListener</code>,350 * the container calls 351 * <code>HttpSessionBindingListener.valueUnbound</code>. The container352 * then notifies any <code>HttpSessionAttributeListener</code>s in the web 353 * application.354 * 355 * 356 *357 * @param name the name of the object to358 * remove from this session359 *360 * @exception IllegalStateException if this method is called on an361 * invalidated session362 */363 364 publicvoid removeAttribute(String name);365 366 367 368 369 370 /**371 *372 * @deprecated As of Version 2.2, this method is373 * replaced by {@link #removeAttribute}374 *375 * @param name the name of the object to376 * remove from this session377 *378 * @exception IllegalStateException if this method is called on an379 * invalidated session380 */381 382 publicvoid removeValue(String name);383 384 385 386 387 /**388 *389 * Invalidates this session then unbinds any objects bound390 * to it. 391 *392 * @exception IllegalStateException if this method is called on an393 * already invalidated session394 *395 */396 397 publicvoid invalidate();398 399 400 401 402 /**403 *404 * Returns <code>true</code> if the client does not yet know about the405 * session or if the client chooses not to join the session. For 406 * example, if the server used only cookie-based sessions, and407 * the client had disabled the use of cookies, then a session would408 * 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 joined413 *414 * @exception IllegalStateException if this method is called on an415 * already invalidated session416 *417 */418 419 publicboolean isNew();420 421 422 423 }424 425