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