2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 package javax.servlet.http;
19 import java.util.Enumeration;
21 import javax.servlet.ServletContext;
24 * Provides a way to identify a user across more than one page request or visit
25 * to a Web site and to store information about that user.
27 * The servlet container uses this interface to create a session between an HTTP
28 * client and an HTTP server. The session persists for a specified time period,
29 * across more than one connection or page request from the user. A session
30 * usually corresponds to one user, who may visit a site many times. The server
31 * can maintain a session in many ways such as using cookies or rewriting URLs.
33 * This interface allows servlets to
35 * <li>View and manipulate information about a session, such as the session
36 * identifier, creation time, and last accessed time
37 * <li>Bind objects to sessions, allowing user information to persist across
38 * multiple user connections
41 * When an application stores an object in or removes an object from a session,
42 * the session checks whether the object implements
43 * {@link HttpSessionBindingListener}. If it does, the servlet notifies the
44 * object that it has been bound to or unbound from the session. Notifications
45 * are sent after the binding methods complete. For session that are invalidated
46 * or expire, notifications are sent after the session has been invalidated or
49 * When container migrates a session between VMs in a distributed container
50 * setting, all session attributes implementing the
51 * {@link HttpSessionActivationListener} interface are notified.
53 * A servlet should be able to handle cases in which the client does not choose
54 * to join a session, such as when cookies are intentionally turned off. Until
55 * the client joins the session, <code>isNew</code> returns <code>true</code>.
56 * If the client chooses not to join the session, <code>getSession</code> will
57 * return a different session on each request, and <code>isNew</code> will
58 * always return <code>true</code>.
60 * Session information is scoped only to the current web application (
61 * <code>ServletContext</code>), so information stored in one context will not
62 * be directly visible in another.
64 * @see HttpSessionBindingListener
66 public interface HttpSession {
69 * Returns the time when this session was created, measured in milliseconds
70 * since midnight January 1, 1970 GMT.
72 * @return a <code>long</code> specifying when this session was created,
73 * expressed in milliseconds since 1/1/1970 GMT
74 * @exception IllegalStateException
75 * if this method is called on an invalidated session
77 public long getCreationTime();
80 * Returns a string containing the unique identifier assigned to this
81 * session. The identifier is assigned by the servlet container and is
82 * implementation dependent.
84 * @return a string specifying the identifier assigned to this session
85 * @exception IllegalStateException
86 * if this method is called on an invalidated session
88 public String getId();
91 * Returns the last time the client sent a request associated with this
92 * session, as the number of milliseconds since midnight January 1, 1970
93 * GMT, and marked by the time the container received the request.
95 * Actions that your application takes, such as getting or setting a value
96 * associated with the session, do not affect the access time.
98 * @return a <code>long</code> representing the last time the client sent a
99 * request associated with this session, expressed in milliseconds
101 * @exception IllegalStateException
102 * if this method is called on an invalidated session
104 public long getLastAccessedTime();
107 * Returns the ServletContext to which this session belongs.
109 * @return The ServletContext object for the web application
112 public ServletContext getServletContext();
115 * Specifies the time, in seconds, between client requests before the
116 * servlet container will invalidate this session. A zero or negative time
117 * indicates that the session should never timeout.
120 * An integer specifying the number of seconds
122 public void setMaxInactiveInterval(int interval);
125 * Returns the maximum time interval, in seconds, that the servlet container
126 * will keep this session open between client accesses. After this interval,
127 * the servlet container will invalidate the session. The maximum time
128 * interval can be set with the <code>setMaxInactiveInterval</code> method.
129 * A zero or negative time indicates that the session should never timeout.
131 * @return an integer specifying the number of seconds this session remains
132 * open between client requests
133 * @see #setMaxInactiveInterval
135 public int getMaxInactiveInterval();
138 * @deprecated As of Version 2.1, this method is deprecated and has no
139 * replacement. It will be removed in a future version of the
142 @SuppressWarnings("dep-ann")
143 // Spec API does not use @Deprecated
144 public HttpSessionContext getSessionContext();
147 * Returns the object bound with the specified name in this session, or
148 * <code>null</code> if no object is bound under the name.
151 * a string specifying the name of the object
152 * @return the object with the specified name
153 * @exception IllegalStateException
154 * if this method is called on an invalidated session
156 public Object getAttribute(String name);
160 * a string specifying the name of the object
161 * @return the object with the specified name
162 * @exception IllegalStateException
163 * if this method is called on an invalidated session
164 * @deprecated As of Version 2.2, this method is replaced by
165 * {@link #getAttribute}.
167 @SuppressWarnings("dep-ann")
168 // Spec API does not use @Deprecated
169 public Object getValue(String name);
172 * Returns an <code>Enumeration</code> of <code>String</code> objects
173 * containing the names of all the objects bound to this session.
175 * @return an <code>Enumeration</code> of <code>String</code> objects
176 * specifying the names of all the objects bound to this session
177 * @exception IllegalStateException
178 * if this method is called on an invalidated session
180 public Enumeration<String> getAttributeNames();
183 * @return an array of <code>String</code> objects specifying the names of
184 * all the objects bound to this session
185 * @exception IllegalStateException
186 * if this method is called on an invalidated session
187 * @deprecated As of Version 2.2, this method is replaced by
188 * {@link #getAttributeNames}
190 @SuppressWarnings("dep-ann")
191 // Spec API does not use @Deprecated
192 public String[] getValueNames();
195 * Binds an object to this session, using the name specified. If an object
196 * of the same name is already bound to the session, the object is replaced.
198 * After this method executes, and if the new object implements
199 * <code>HttpSessionBindingListener</code>, the container calls
200 * <code>HttpSessionBindingListener.valueBound</code>. The container then
201 * notifies any <code>HttpSessionAttributeListener</code>s in the web
204 * If an object was already bound to this session of this name that
205 * implements <code>HttpSessionBindingListener</code>, its
206 * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
208 * If the value passed in is null, this has the same effect as calling
209 * <code>removeAttribute()</code>.
212 * the name to which the object is bound; cannot be null
214 * the object to be bound
215 * @exception IllegalStateException
216 * if this method is called on an invalidated session
218 public void setAttribute(String name, Object value);
222 * the name to which the object is bound; cannot be null
224 * the object to be bound; cannot be null
225 * @exception IllegalStateException
226 * if this method is called on an invalidated session
227 * @deprecated As of Version 2.2, this method is replaced by
228 * {@link #setAttribute}
230 @SuppressWarnings("dep-ann")
231 // Spec API does not use @Deprecated
232 public void putValue(String name, Object value);
235 * Removes the object bound with the specified name from this session. If
236 * the session does not have an object bound with the specified name, this
237 * method does nothing.
239 * After this method executes, and if the object implements
240 * <code>HttpSessionBindingListener</code>, the container calls
241 * <code>HttpSessionBindingListener.valueUnbound</code>. The container then
242 * notifies any <code>HttpSessionAttributeListener</code>s in the web
246 * the name of the object to remove from this session
247 * @exception IllegalStateException
248 * if this method is called on an invalidated session
250 public void removeAttribute(String name);
254 * the name of the object to remove from this session
255 * @exception IllegalStateException
256 * if this method is called on an invalidated session
257 * @deprecated As of Version 2.2, this method is replaced by
258 * {@link #removeAttribute}
260 @SuppressWarnings("dep-ann")
261 // Spec API does not use @Deprecated
262 public void removeValue(String name);
265 * Invalidates this session then unbinds any objects bound to it.
267 * @exception IllegalStateException
268 * if this method is called on an already invalidated session
270 public void invalidate();
273 * Returns <code>true</code> if the client does not yet know about the
274 * session or if the client chooses not to join the session. For example, if
275 * the server used only cookie-based sessions, and the client had disabled
276 * the use of cookies, then a session would be new on each request.
278 * @return <code>true</code> if the server has created a session, but the
279 * client has not yet joined
280 * @exception IllegalStateException
281 * if this method is called on an already invalidated session
283 public boolean isNew();