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