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 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet.http; 027 028 import java.util.Enumeration; 029 import javax.servlet.ServletContext; 030 031 /** 032 * Provides a way to identify a user across more than one page 033 * request or visit to a Web site and to store information about that user. 034 * 035 * <p>The servlet container uses this interface to create a session 036 * between an HTTP client and an HTTP server. The session persists 037 * for a specified time period, across more than one connection or 038 * page request from the user. A session usually corresponds to one 039 * user, who may visit a site many times. The server can maintain a 040 * session in many ways such as using cookies or rewriting URLs. 041 * 042 * <p>This interface allows servlets to 043 * <ul> 044 * <li>View and manipulate information about a session, such as 045 * the session identifier, creation time, and last accessed time 046 * <li>Bind objects to sessions, allowing user information to persist 047 * across multiple user connections 048 * </ul> 049 * 050 * <p>When an application stores an object in or removes an object from a 051 * session, the session checks whether the object implements 052 * {@link HttpSessionBindingListener}. If it does, 053 * the servlet notifies the object that it has been bound to or unbound 054 * from the session. Notifications are sent after the binding methods complete. 055 * For session that are invalidated or expire, notifications are sent after 056 * the session has been invalidatd or expired. 057 * 058 * <p> When container migrates a session between VMs in a distributed container 059 * setting, all session attributes implementing the {@link HttpSessionActivationListener} 060 * interface are notified. 061 * 062 * <p>A servlet should be able to handle cases in which 063 * the client does not choose to join a session, such as when cookies are 064 * intentionally turned off. Until the client joins the session, 065 * <code>isNew</code> returns <code>true</code>. If the client chooses 066 * not to join 067 * the session, <code>getSession</code> will return a different session 068 * on each request, and <code>isNew</code> will always return 069 * <code>true</code>. 070 * 071 * <p>Session information is scoped only to the current web application 072 * (<code>ServletContext</code>), so information stored in one context 073 * will not be directly visible in another. 074 * 075 * @see HttpSessionBindingListener 076 * @see HttpSessionContext 077 * 078 * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $ 079 */ 080 public interface HttpSession { 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 when this session was created, 086 * expressed in milliseconds since 1/1/1970 GMT 087 * 088 * @exception IllegalStateException if this method is called on an 089 * invalidated session 090 */ 091 public long getCreationTime(); 092 093 /** 094 * Returns a string containing the unique identifier assigned to this 095 * session. The identifier is assigned by the servlet container and is 096 * implementation dependent. 097 * 098 * @return a string specifying the identifier assigned to this session 099 * 100 * @exception IllegalStateException if this method is called on an 101 * invalidated session 102 */ 103 public String getId(); 104 105 /** 106 * Returns the last time the client sent a request associated with 107 * this session, as the number of milliseconds since midnight 108 * January 1, 1970 GMT, and marked by the time the container received the request. 109 * 110 * <p>Actions that your application takes, such as getting or setting 111 * a value associated with the session, do not affect the access 112 * time. 113 * 114 * @return a <code>long</code> representing the last time the client sent 115 * a request associated with this session, expressed in milliseconds since 116 * 1/1/1970 GMT 117 * 118 * @exception IllegalStateException if this method is called on an 119 * invalidated session 120 */ 121 public long getLastAccessedTime(); 122 123 /** 124 * Returns the ServletContext to which this session belongs. 125 * 126 * @return The ServletContext object for the web application 127 * @since Servlet 2.3 128 */ 129 public ServletContext getServletContext(); 130 131 /** 132 * Specifies the time, in seconds, between client requests before the 133 * servlet container will invalidate this session. A negative time 134 * indicates the session should never timeout. 135 * 136 * @param interval An integer specifying the number of seconds 137 */ 138 public void setMaxInactiveInterval(int interval); 139 140 /** 141 * Returns the maximum time interval, in seconds, that 142 * the servlet container will keep this session open between 143 * client accesses. After this interval, the servlet container 144 * will invalidate the session. The maximum time interval can be set 145 * with the <code>setMaxInactiveInterval</code> method. 146 * A negative time indicates the session should never timeout. 147 * 148 * @return an integer specifying the number of seconds this session 149 * remains open between client requests 150 * 151 * @see #setMaxInactiveInterval 152 */ 153 public int getMaxInactiveInterval(); 154 155 /** 156 * @deprecated As of Version 2.1, this method is deprecated and has no 157 * replacement. It will be removed in a future version of the Java Servlet 158 * API. 159 */ 160 public HttpSessionContext getSessionContext(); 161 162 /** 163 * Returns the object bound with the specified name in this session, or 164 * <code>null</code> if no object is bound under the name. 165 * 166 * @param name a string specifying the name of the object 167 * 168 * @return the object with the specified name 169 * 170 * @exception IllegalStateException if this method is called on an 171 * invalidated session 172 */ 173 public Object getAttribute(String name); 174 175 /** 176 * @deprecated As of Version 2.2, this method is replaced by 177 * {@link #getAttribute}. 178 * 179 * @param name a string specifying the name of the object 180 * 181 * @return the object with the specified name 182 * 183 * @exception IllegalStateException if this method is called on an 184 * invalidated session 185 */ 186 public Object getValue(String name); 187 188 /** 189 * Returns an <code>Enumeration</code> of <code>String</code> objects 190 * containing the names of all the objects bound to this session. 191 * 192 * @return an <code>Enumeration</code> of <code>String</code> objects 193 * specifying the names of all the objects bound to this session 194 * 195 * @exception IllegalStateException if this method is called on an 196 * invalidated session 197 */ 198 public Enumeration getAttributeNames(); 199 200 /** 201 * @deprecated As of Version 2.2, this method is replaced by 202 * {@link #getAttributeNames} 203 * 204 * @return an array of <code>String</code> objects specifying the names of 205 * all the objects bound to this session 206 * 207 * @exception IllegalStateException if this method is called on an 208 * invalidated session 209 */ 210 public String[] getValueNames(); 211 212 /** 213 * Binds an object to this session, using the name specified. If an object 214 * of the same name is already bound to the session, the object is 215 * replaced. 216 * 217 * <p>After this method executes, and if the new object implements 218 * <code>HttpSessionBindingListener</code>, the container calls 219 * <code>HttpSessionBindingListener.valueBound</code>. The container then 220 * notifies any <code>HttpSessionAttributeListener</code>s in the web 221 * application. 222 * 223 * <p>If an object was already bound to this session of this name 224 * that implements <code>HttpSessionBindingListener</code>, its 225 * <code>HttpSessionBindingListener.valueUnbound</code> method is called. 226 * 227 * <p>If the value passed in is null, this has the same effect as calling 228 * <code>removeAttribute()<code>. 229 * 230 * @param name the name to which the object is bound; cannot be null 231 * 232 * @param value the object to be bound 233 * 234 * @exception IllegalStateException if this method is called on an 235 * invalidated session 236 */ 237 public void setAttribute(String name, Object value); 238 239 /** 240 * @deprecated As of Version 2.2, this method is replaced by 241 * {@link #setAttribute} 242 * 243 * @param name the name to which the object is bound; cannot be null 244 * 245 * @param value the object to be bound; cannot be null 246 * 247 * @exception IllegalStateException if this method is called on an 248 * invalidated session 249 */ 250 public void putValue(String name, Object value); 251 252 /** 253 * Removes the object bound with the specified name from this session. 254 * If the session does not have an object bound with the specified name, 255 * this method does nothing. 256 * 257 * <p>After this method executes, and if the object implements 258 * <code>HttpSessionBindingListener</code>, the container calls 259 * <code>HttpSessionBindingListener.valueUnbound</code>. The container 260 * then notifies any <code>HttpSessionAttributeListener</code>s in the web 261 * application. 262 * 263 * @param name the name of the object to remove from this session 264 * 265 * @exception IllegalStateException if this method is called on an 266 * invalidated session 267 */ 268 public void removeAttribute(String name); 269 270 /** 271 * @deprecated As of Version 2.2, this method is replaced by 272 * {@link #removeAttribute} 273 * 274 * @param name the name of the object to remove from this session 275 * 276 * @exception IllegalStateException if this method is called on an 277 * invalidated session 278 */ 279 public void removeValue(String name); 280 281 /** 282 * Invalidates this session then unbinds any objects bound to it. 283 * 284 * @exception IllegalStateException if this method is called on an already 285 * invalidated session 286 */ 287 public void invalidate(); 288 289 /** 290 * Returns <code>true</code> if the client does not yet know about the 291 * session or if the client chooses not to join the session. For 292 * example, if the server used only cookie-based sessions, and 293 * the client had disabled the use of cookies, then a session would 294 * be new on each request. 295 * 296 * @return <code>true</code> if the server has created a session, but the 297 * client has not yet joined 298 * 299 * @exception IllegalStateException if this method is called on an already 300 * invalidated session 301 */ 302 public boolean isNew(); 303 } 304