View Javadoc

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