001:
002: /*
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
004: *
005: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
006: *
007: * Portions Copyright Apache Software Foundation.
008: *
009: * The contents of this file are subject to the terms of either the GNU
010: * General Public License Version 2 only ("GPL") or the Common Development
011: * and Distribution License("CDDL") (collectively, the "License"). You
012: * may not use this file except in compliance with the License. You can obtain
013: * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
014: * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
015: * language governing permissions and limitations under the License.
016: *
017: * When distributing the software, include this License Header Notice in each
018: * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
019: * Sun designates this particular file as subject to the "Classpath" exception
020: * as provided by Sun in the GPL Version 2 section of the License file that
021: * accompanied this code. If applicable, add the following below the License
022: * Header, with the fields enclosed by brackets [] replaced by your own
023: * identifying information: "Portions Copyrighted [year]
024: * [name of copyright owner]"
025: *
026: * Contributor(s):
027: *
028: * If you wish your version of this file to be governed by only the CDDL or
029: * only the GPL Version 2, indicate your decision by adding "[Contributor]
030: * elects to include this software in this distribution under the [CDDL or GPL
031: * Version 2] license." If you don't indicate a single choice of license, a
032: * recipient has the option to distribute your version of this file under
033: * either the CDDL, the GPL Version 2 or to extend the choice of license to
034: * its licensees as provided above. However, if you add GPL Version 2 code
035: * and therefore, elected the GPL Version 2 license, then the option applies
036: * only if the new code is made subject to such option by the copyright
037: * holder.
038: */
039:
040: package javax.servlet.http;
041:
042: import java.util.Enumeration;
043: import javax.servlet.ServletContext;
044:
045: /**
046: *
047: * Provides a way to identify a user across more than one page
048: * request or visit to a Web site and to store information about that user.
049: *
050: * <p>The servlet container uses this interface to create a session
051: * between an HTTP client and an HTTP server. The session persists
052: * for a specified time period, across more than one connection or
053: * page request from the user. A session usually corresponds to one
054: * user, who may visit a site many times. The server can maintain a
055: * session in many ways such as using cookies or rewriting URLs.
056: *
057: * <p>This interface allows servlets to
058: * <ul>
059: * <li>View and manipulate information about a session, such as
060: * the session identifier, creation time, and last accessed time
061: * <li>Bind objects to sessions, allowing user information to persist
062: * across multiple user connections
063: * </ul>
064: *
065: * <p>When an application stores an object in or removes an object from a
066: * session, the session checks whether the object implements
067: * {@link HttpSessionBindingListener}. If it does,
068: * the servlet notifies the object that it has been bound to or unbound
069: * from the session. Notifications are sent after the binding methods complete.
070: * For session that are invalidated or expire, notifications are sent after
071: * the session has been invalidated or expired.
072: *
073: * <p> When container migrates a session between VMs in a distributed container
074: * setting, all session attributes implementing the {@link HttpSessionActivationListener}
075: * interface are notified.
076: *
077: * <p>A servlet should be able to handle cases in which
078: * the client does not choose to join a session, such as when cookies are
079: * intentionally turned off. Until the client joins the session,
080: * <code>isNew</code> returns <code>true</code>. If the client chooses
081: * not to join
082: * the session, <code>getSession</code> will return a different session
083: * on each request, and <code>isNew</code> will always return
084: * <code>true</code>.
085: *
086: * <p>Session information is scoped only to the current web application
087: * (<code>ServletContext</code>), so information stored in one context
088: * will not be directly visible in another.
089: *
090: * @author Various
091: *
092: * @see HttpSessionBindingListener
093: * @see HttpSessionContext
094: *
095: */
096:
097: public interface HttpSession {
098:
099: /**
100: *
101: * Returns the time when this session was created, measured
102: * in milliseconds since midnight January 1, 1970 GMT.
103: *
104: * @return a <code>long</code> specifying
105: * when this session was created,
106: * expressed in
107: * milliseconds since 1/1/1970 GMT
108: *
109: * @exception IllegalStateException if this method is called on an
110: * invalidated session
111: *
112: */
113:
114: public long getCreationTime();
115:
116: /**
117: *
118: * Returns a string containing the unique identifier assigned
119: * to this session. The identifier is assigned
120: * by the servlet container and is implementation dependent.
121: *
122: * @return a string specifying the identifier
123: * assigned to this session
124: */
125:
126: public String getId();
127:
128: /**
129: *
130: * Returns the last time the client sent a request associated with
131: * this session, as the number of milliseconds since midnight
132: * January 1, 1970 GMT, and marked by the time the container received the request.
133: *
134: * <p>Actions that your application takes, such as getting or setting
135: * a value associated with the session, do not affect the access
136: * time.
137: *
138: * @return a <code>long</code>
139: * representing the last time
140: * the client sent a request associated
141: * with this session, expressed in
142: * milliseconds since 1/1/1970 GMT
143: *
144: * @exception IllegalStateException if this method is called on an
145: * invalidated session
146: *
147: */
148:
149: public long getLastAccessedTime();
150:
151: /**
152: * Returns the ServletContext to which this session belongs.
153: *
154: * @return The ServletContext object for the web application
155: * @since 2.3
156: */
157:
158: public ServletContext getServletContext();
159:
160: /**
161: *
162: * Specifies the time, in seconds, between client requests before the
163: * servlet container will invalidate this session. A negative time
164: * indicates the session should never timeout.
165: *
166: * @param interval An integer specifying the number
167: * of seconds
168: *
169: */
170:
171: public void setMaxInactiveInterval(int interval);
172:
173: /**
174: * Returns the maximum time interval, in seconds, that
175: * the servlet container will keep this session open between
176: * client accesses. After this interval, the servlet container
177: * will invalidate the session. The maximum time interval can be set
178: * with the <code>setMaxInactiveInterval</code> method.
179: * A negative time indicates the session should never timeout.
180: *
181: *
182: * @return an integer specifying the number of
183: * seconds this session remains open
184: * between client requests
185: *
186: * @see #setMaxInactiveInterval
187: *
188: *
189: */
190:
191: public int getMaxInactiveInterval();
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: * Returns the object bound with the specified name in this session, or
207: * <code>null</code> if no object is bound under the name.
208: *
209: * @param name a string specifying the name of the object
210: *
211: * @return the object with the specified name
212: *
213: * @exception IllegalStateException if this method is called on an
214: * invalidated session
215: *
216: */
217:
218: public Object getAttribute(String name);
219:
220: /**
221: *
222: * @deprecated As of Version 2.2, this method is
223: * replaced by {@link #getAttribute}.
224: *
225: * @param name a string specifying the name of the object
226: *
227: * @return the object with the specified name
228: *
229: * @exception IllegalStateException if this method is called on an
230: * invalidated session
231: *
232: */
233:
234: public Object getValue(String name);
235:
236: /**
237: *
238: * Returns an <code>Enumeration</code> of <code>String</code> objects
239: * containing the names of all the objects bound to this session.
240: *
241: * @return an <code>Enumeration</code> of
242: * <code>String</code> objects specifying the
243: * names of all the objects bound to
244: * this session
245: *
246: * @exception IllegalStateException if this method is called on an
247: * invalidated session
248: *
249: */
250:
251: public Enumeration getAttributeNames();
252:
253: /**
254: *
255: * @deprecated As of Version 2.2, this method is
256: * replaced by {@link #getAttributeNames}
257: *
258: * @return an array of <code>String</code>
259: * objects specifying the
260: * names of all the objects bound to
261: * this session
262: *
263: * @exception IllegalStateException if this method is called on an
264: * invalidated session
265: *
266: */
267:
268: public String[] getValueNames();
269:
270: /**
271: * Binds an object to this session, using the name specified.
272: * If an object of the same name is already bound to the session,
273: * the object is replaced.
274: *
275: * <p>After this method executes, and if the new object
276: * implements <code>HttpSessionBindingListener</code>,
277: * the container calls
278: * <code>HttpSessionBindingListener.valueBound</code>. The container then
279: * notifies any <code>HttpSessionAttributeListener</code>s in the web
280: * application.
281:
282: * <p>If an object was already bound to this session of this name
283: * that implements <code>HttpSessionBindingListener</code>, its
284: * <code>HttpSessionBindingListener.valueUnbound</code> method is called.
285: *
286: * <p>If the value passed in is null, this has the same effect as calling
287: * <code>removeAttribute()<code>.
288: *
289: *
290: * @param name the name to which the object is bound;
291: * cannot be null
292: *
293: * @param value the object to be bound
294: *
295: * @exception IllegalStateException if this method is called on an
296: * invalidated session
297: *
298: */
299:
300: public void setAttribute(String name, Object value);
301:
302: /**
303: *
304: * @deprecated As of Version 2.2, this method is
305: * replaced by {@link #setAttribute}
306: *
307: * @param name the name to which the object is bound;
308: * cannot be null
309: *
310: * @param value the object to be bound; cannot be null
311: *
312: * @exception IllegalStateException if this method is called on an
313: * invalidated session
314: *
315: */
316:
317: public void putValue(String name, Object value);
318:
319: /**
320: *
321: * Removes the object bound with the specified name from
322: * this session. If the session does not have an object
323: * bound with the specified name, this method does nothing.
324: *
325: * <p>After this method executes, and if the object
326: * implements <code>HttpSessionBindingListener</code>,
327: * the container calls
328: * <code>HttpSessionBindingListener.valueUnbound</code>. The container
329: * then notifies any <code>HttpSessionAttributeListener</code>s in the web
330: * application.
331: *
332: *
333: *
334: * @param name the name of the object to
335: * remove from this session
336: *
337: * @exception IllegalStateException if this method is called on an
338: * invalidated session
339: */
340:
341: public void removeAttribute(String name);
342:
343: /**
344: *
345: * @deprecated As of Version 2.2, this method is
346: * replaced by {@link #removeAttribute}
347: *
348: * @param name the name of the object to
349: * remove from this session
350: *
351: * @exception IllegalStateException if this method is called on an
352: * invalidated session
353: */
354:
355: public void removeValue(String name);
356:
357: /**
358: *
359: * Invalidates this session then unbinds any objects bound
360: * to it.
361: *
362: * @exception IllegalStateException if this method is called on an
363: * already invalidated session
364: *
365: */
366:
367: public void invalidate();
368:
369: /**
370: *
371: * Returns <code>true</code> if the client does not yet know about the
372: * session or if the client chooses not to join the session. For
373: * example, if the server used only cookie-based sessions, and
374: * the client had disabled the use of cookies, then a session would
375: * be new on each request.
376: *
377: * @return <code>true</code> if the
378: * server has created a session,
379: * but the client has not yet joined
380: *
381: * @exception IllegalStateException if this method is called on an
382: * already invalidated session
383: *
384: */
385:
386: public boolean isNew();
387:
388: }
|