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