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