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