View Javadoc

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  // This source code implements specifications defined by the Java
20  // Community Process. In order to remain compliant with the specification
21  // DO NOT add / change / or delete method signatures!
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