HttpSession


1   /*
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
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  package javax.servlet.http;
18  
19  import java.util.Enumeration  ;
20  import javax.servlet.ServletContext  ;
21  
22  /**
23   *
24   * Provides a way to identify a user across more than one page
25   * request or visit to a Web site and to store information about that user.
26   *
27   * <p>The servlet container uses this interface to create a session
28   * between an HTTP client and an HTTP server. The session persists
29   * for a specified time period, across more than one connection or
30   * page request from the user. A session usually corresponds to one 
31   * user, who may visit a site many times. The server can maintain a 
32   * session in many ways such as using cookies or rewriting URLs.
33   *
34   * <p>This interface allows servlets to 
35   * <ul>
36   * <li>View and manipulate information about a session, such as
37   *     the session identifier, creation time, and last accessed time
38   * <li>Bind objects to sessions, allowing user information to persist 
39   *     across multiple user connections
40   * </ul>
41   *
42   * <p>When an application stores an object in or removes an object from a
43   * session, the session checks whether the object implements
44   * {@link HttpSessionBindingListener}. If it does, 
45   * the servlet notifies the object that it has been bound to or unbound 
46   * from the session. Notifications are sent after the binding methods complete. 
47   * For session that are invalidated or expire, notifications are sent after
48   * the session has been invalidated or expired.
49   *
50   * <p> When container migrates a session between VMs in a distributed container
51   * setting, all session attributes implementing the {@link HttpSessionActivationListener}
52   * interface are notified.
53   * 
54   * <p>A servlet should be able to handle cases in which
55   * the client does not choose to join a session, such as when cookies are
56   * intentionally turned off. Until the client joins the session,
57   * <code>isNew</code> returns <code>true</code>.  If the client chooses 
58   * not to join
59   * the session, <code>getSession</code> will return a different session
60   * on each request, and <code>isNew</code> will always return
61   * <code>true</code>.
62   *
63   * <p>Session information is scoped only to the current web application
64   * (<code>ServletContext</code>), so information stored in one context
65   * will not be directly visible in another.
66   *
67   * @author  Various
68   * @version $Version$
69   *
70   *
71   * @see     HttpSessionBindingListener
72   * @see     HttpSessionContext
73   *
74   */
75  
76  public interface HttpSession {
77  
78  
79  
80  
81      /**
82       *
83       * Returns the time when this session was created, measured
84       * in milliseconds since midnight January 1, 1970 GMT.
85       *
86       * @return              a <code>long</code> specifying
87       *                  when this session was created,
88       *                  expressed in 
89       *                  milliseconds since 1/1/1970 GMT
90       *
91       * @exception IllegalStateException if this method is called on an
92       *                  invalidated session
93       *
94       */
95  
96      public long getCreationTime();
97      
98      
99      
100     
101     /**
102      *
103      * Returns a string containing the unique identifier assigned 
104      * to this session. The identifier is assigned 
105      * by the servlet container and is implementation dependent.
106      * 
107      * @return              a string specifying the identifier
108      *                  assigned to this session
109      *
110      * @exception IllegalStateException if this method is called on an
111      *                  invalidated session
112      *
113      */
114 
115     public String   getId();
116     
117     
118     
119 
120     /**
121      *
122      * Returns the last time the client sent a request associated with
123      * this session, as the number of milliseconds since midnight
124      * January 1, 1970 GMT, and marked by the time the container received the request. 
125      *
126      * <p>Actions that your application takes, such as getting or setting
127      * a value associated with the session, do not affect the access
128      * time.
129      *
130      * @return              a <code>long</code>
131      *                  representing the last time 
132      *                  the client sent a request associated
133      *                  with this session, expressed in 
134      *                  milliseconds since 1/1/1970 GMT
135      *
136      * @exception IllegalStateException if this method is called on an
137      *                  invalidated session
138      *
139      */
140 
141     public long getLastAccessedTime();
142     
143     
144     /**
145     * Returns the ServletContext to which this session belongs.
146     *    
147     * @return The ServletContext object for the web application
148     * @since 2.3
149     */
150 
151     public ServletContext   getServletContext();
152 
153 
154     /**
155      *
156      * Specifies the time, in seconds, between client requests before the 
157      * servlet container will invalidate this session.  A negative time
158      * indicates the session should never timeout.
159      *
160      * @param interval      An integer specifying the number
161      *              of seconds 
162      *
163      */
164     
165     public void setMaxInactiveInterval(int interval);
166 
167 
168 
169 
170    /**
171     * Returns the maximum time interval, in seconds, that 
172     * the servlet container will keep this session open between 
173     * client accesses. After this interval, the servlet container
174     * will invalidate the session.  The maximum time interval can be set
175     * with the <code>setMaxInactiveInterval</code> method.
176     * A negative time indicates the session should never timeout.
177     *  
178     *
179     * @return       an integer specifying the number of
180     *           seconds this session remains open
181     *           between client requests
182     *
183     * @see      #setMaxInactiveInterval
184     *
185     *
186     */
187 
188     public int getMaxInactiveInterval();
189     
190     
191 
192 
193    /**
194     *
195     * @deprecated   As of Version 2.1, this method is
196     *           deprecated and has no replacement.
197     *           It will be removed in a future
198     *           version of the Java Servlet API.
199     *
200     */
201 
202     public HttpSessionContext   getSessionContext();
203     
204     
205     
206     
207     /**
208      *
209      * Returns the object bound with the specified name in this session, or
210      * <code>null</code> if no object is bound under the name.
211      *
212      * @param name      a string specifying the name of the object
213      *
214      * @return          the object with the specified name
215      *
216      * @exception IllegalStateException if this method is called on an
217      *                  invalidated session
218      *
219      */
220   
221     public Object   getAttribute(String   name);
222     
223     
224     
225     
226     /**
227      *
228      * @deprecated  As of Version 2.2, this method is
229      *          replaced by {@link #getAttribute}.
230      *
231      * @param name      a string specifying the name of the object
232      *
233      * @return          the object with the specified name
234      *
235      * @exception IllegalStateException if this method is called on an
236      *                  invalidated session
237      *
238      */
239   
240     public Object   getValue(String   name);
241     
242     
243     
244 
245     /**
246      *
247      * Returns an <code>Enumeration</code> of <code>String</code> objects
248      * containing the names of all the objects bound to this session. 
249      *
250      * @return          an <code>Enumeration</code> of 
251      *              <code>String</code> objects specifying the
252      *              names of all the objects bound to
253      *              this session
254      *
255      * @exception IllegalStateException if this method is called on an
256      *                  invalidated session
257      *
258      */
259     
260     public Enumeration   getAttributeNames();
261     
262     
263     
264 
265     /**
266      *
267      * @deprecated  As of Version 2.2, this method is
268      *          replaced by {@link #getAttributeNames}
269      *
270      * @return              an array of <code>String</code>
271      *                  objects specifying the
272      *                  names of all the objects bound to
273      *                  this session
274      *
275      * @exception IllegalStateException if this method is called on an
276      *                  invalidated session
277      *
278      */
279     
280     public String  [] getValueNames();
281     
282     
283     
284 
285     /**
286      * Binds an object to this session, using the name specified.
287      * If an object of the same name is already bound to the session,
288      * the object is replaced.
289      *
290      * <p>After this method executes, and if the new object
291      * implements <code>HttpSessionBindingListener</code>,
292      * the container calls 
293      * <code>HttpSessionBindingListener.valueBound</code>. The container then   
294      * notifies any <code>HttpSessionAttributeListener</code>s in the web 
295      * application.
296      
297      * <p>If an object was already bound to this session of this name
298      * that implements <code>HttpSessionBindingListener</code>, its 
299      * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
300      *
301      * <p>If the value passed in is null, this has the same effect as calling 
302      * <code>removeAttribute()<code>.
303      *
304      *
305      * @param name          the name to which the object is bound;
306      *                  cannot be null
307      *
308      * @param value         the object to be bound
309      *
310      * @exception IllegalStateException if this method is called on an
311      *                  invalidated session
312      *
313      */
314  
315     public void setAttribute(String   name, Object   value);
316     
317 
318 
319 
320     
321     /**
322      *
323      * @deprecated  As of Version 2.2, this method is
324      *          replaced by {@link #setAttribute}
325      *
326      * @param name          the name to which the object is bound;
327      *                  cannot be null
328      *
329      * @param value         the object to be bound; cannot be null
330      *
331      * @exception IllegalStateException if this method is called on an
332      *                  invalidated session
333      *
334      */
335  
336     public void putValue(String   name, Object   value);
337 
338 
339 
340 
341 
342     /**
343      *
344      * Removes the object bound with the specified name from
345      * this session. If the session does not have an object
346      * bound with the specified name, this method does nothing.
347      *
348      * <p>After this method executes, and if the object
349      * implements <code>HttpSessionBindingListener</code>,
350      * the container calls 
351      * <code>HttpSessionBindingListener.valueUnbound</code>. The container
352      * then notifies any <code>HttpSessionAttributeListener</code>s in the web 
353      * application.
354      * 
355      * 
356      *
357      * @param name              the name of the object to
358      *                      remove from this session
359      *
360      * @exception IllegalStateException if this method is called on an
361      *                  invalidated session
362      */
363 
364     public void removeAttribute(String   name);
365 
366 
367 
368 
369 
370     /**
371      *
372      * @deprecated  As of Version 2.2, this method is
373      *          replaced by {@link #removeAttribute}
374      *
375      * @param name              the name of the object to
376      *                      remove from this session
377      *
378      * @exception IllegalStateException if this method is called on an
379      *                  invalidated session
380      */
381 
382     public void removeValue(String   name);
383 
384 
385 
386 
387     /**
388      *
389      * Invalidates this session then unbinds any objects bound
390      * to it. 
391      *
392      * @exception IllegalStateException if this method is called on an
393      *                  already invalidated session
394      *
395      */
396 
397     public void invalidate();
398     
399     
400     
401     
402     /**
403      *
404      * Returns <code>true</code> if the client does not yet know about the
405      * session or if the client chooses not to join the session.  For 
406      * example, if the server used only cookie-based sessions, and
407      * the client had disabled the use of cookies, then a session would
408      * be new on each request.
409      *
410      * @return              <code>true</code> if the 
411      *                  server has created a session, 
412      *                  but the client has not yet joined
413      *
414      * @exception IllegalStateException if this method is called on an
415      *                  already invalidated session
416      *
417      */
418 
419     public boolean isNew();
420 
421 
422 
423 }
424 
425
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags