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-24 21:01:51 -0700 (Tue, 24 Oct 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