1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19
20
21
22
23
24 package javax.servlet.http;
25
26 import java.util.Enumeration;
27 import javax.servlet.ServletContext;
28
29 /**
30 * Provides a way to identify a user across more than one page
31 * request or visit to a Web site and to store information about that user.
32 *
33 * <p>The servlet container uses this interface to create a session
34 * between an HTTP client and an HTTP server. The session persists
35 * for a specified time period, across more than one connection or
36 * page request from the user. A session usually corresponds to one
37 * user, who may visit a site many times. The server can maintain a
38 * session in many ways such as using cookies or rewriting URLs.
39 *
40 * <p>This interface allows servlets to
41 * <ul>
42 * <li>View and manipulate information about a session, such as
43 * the session identifier, creation time, and last accessed time
44 * <li>Bind objects to sessions, allowing user information to persist
45 * across multiple user connections
46 * </ul>
47 *
48 * <p>When an application stores an object in or removes an object from a
49 * session, the session checks whether the object implements
50 * {@link HttpSessionBindingListener}. If it does,
51 * the servlet notifies the object that it has been bound to or unbound
52 * from the session. Notifications are sent after the binding methods complete.
53 * For session that are invalidated or expire, notifications are sent after
54 * the session has been invalidatd or expired.
55 *
56 * <p> When container migrates a session between VMs in a distributed container
57 * setting, all session attributes implementing the {@link HttpSessionActivationListener}
58 * interface are notified.
59 *
60 * <p>A servlet should be able to handle cases in which
61 * the client does not choose to join a session, such as when cookies are
62 * intentionally turned off. Until the client joins the session,
63 * <code>isNew</code> returns <code>true</code>. If the client chooses
64 * not to join
65 * the session, <code>getSession</code> will return a different session
66 * on each request, and <code>isNew</code> will always return
67 * <code>true</code>.
68 *
69 * <p>Session information is scoped only to the current web application
70 * (<code>ServletContext</code>), so information stored in one context
71 * will not be directly visible in another.
72 *
73 * @see HttpSessionBindingListener
74 * @see HttpSessionContext
75 *
76 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
77 */
78 public interface HttpSession {
79 /**
80 * Returns the time when this session was created, measured
81 * in milliseconds since midnight January 1, 1970 GMT.
82 *
83 * @return a <code>long</code> specifying when this session was created,
84 * expressed in milliseconds since 1/1/1970 GMT
85 *
86 * @exception IllegalStateException if this method is called on an
87 * invalidated session
88 */
89 public long getCreationTime();
90
91 /**
92 * Returns a string containing the unique identifier assigned to this
93 * session. The identifier is assigned by the servlet container and is
94 * implementation dependent.
95 *
96 * @return a string specifying the identifier assigned to this session
97 *
98 * @exception IllegalStateException if this method is called on an
99 * 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