001: /*
002: * Copyright (c) 1998-2001 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: *
023: * Free Software Foundation, Inc.
024: * 59 Temple Place, Suite 330
025: * Boston, MA 02111-1307 USA
026: *
027: * @author Scott Ferguson
028: */
029:
030: package javax.servlet.http;
031:
032: import javax.servlet.ServletContext;
033: import java.util.Enumeration;
034:
035: /**
036: * Sessions are a convenient way to connect users to web pages. Because
037: * HTTP requests are intrinsically stateless, cookies and sessions are
038: * needed to implement more sophisticated interfaces like user preferences.
039: *
040: * <p>Because a web site might easily have thousands of simultaneous
041: * sessions, session attributes generally store small chunks of data
042: * rather than large objects.
043: *
044: * <p>The servlet engine controls the number of active sessions through
045: * two methods: a time limit on inactive sessions, and
046: * a cap on the number of active sessions. The cap on the number of
047: * sessions is controlled by an LRU mechanism, so active sessions will not
048: * be culled.
049: *
050: * Session configuration is per-application. It looks like:
051: * <code><pre>
052: * <session-config session-max='4096'
053: * session-timeout='30'/>
054: * </pre></code>
055: *
056: * <h4>Load balancing</h4>
057: *
058: * When using load balancing with Apache, sessions will always go to the
059: * same JVM. The session id encodes the JVM which first created the session.
060: */
061: public interface HttpSession {
062: /**
063: * Returns the id for the session. The session variable name is
064: * 'jsessionid'. <code>getId</code> returns the randomly generated
065: * value.
066: */
067: public String getId();
068:
069: /**
070: * Returns true if the session is new. If the servlet engine found the
071: * session from the client's request, <code>isNew</code> is false.
072: */
073: public boolean isNew();
074:
075: /**
076: * Returns the time when the session was created.
077: */
078: public long getCreationTime();
079:
080: /**
081: * Returns the time when the session was last accessed.
082: */
083: public long getLastAccessedTime();
084:
085: /**
086: * Sets the maximum inactive interval. Sessions have a limited lifetime.
087: * When the lifetime ends, the session will be invalidated.
088: *
089: * @param interval the new inactive interval in seconds.
090: */
091: public void setMaxInactiveInterval(int interval);
092:
093: /*
094: * @return the new inactive interval in seconds.
095: */
096: public int getMaxInactiveInterval();
097:
098: /**
099: * Returns a session value.
100: *
101: * @param name of the attribute.
102: * @return stored value
103: */
104: public Object getAttribute(String name);
105:
106: /**
107: * Returns an enumeration of all the attribute names.
108: */
109: public Enumeration getAttributeNames();
110:
111: /**
112: * Sets an attribute value. Because servlets are multithreaded,
113: * setting HttpSession attributes will generally need synchronization.
114: * Remember, users may open multiple browsers to the same page.
115: *
116: * <p>A typical initialization of an session attribute might look like:
117: * <code><pre>
118: * HttpSession session = request.getSession();
119: * String user;
120: * synchronized (session) {
121: * user = (String) session.getAttribute("user");
122: * if (user == null) {
123: * user = lookupUser(request);
124: * sesion.setAttribute("user", user);
125: * }
126: * }
127: * </pre></code>
128: *
129: * @param name of the attribute.
130: * @param value value to store
131: */
132: public void setAttribute(String name, Object value);
133:
134: /**
135: * Removes an attribute. If the attribute value implements
136: * HttpSessionBindingListener, it will receive a notice when
137: * it is removed. Because servlets are multithreaded,
138: * removing ServletContext attributes will generally need synchronization.
139: *
140: * @param name of the attribute.
141: */
142: public void removeAttribute(String name);
143:
144: /**
145: * Invalidates the current session. Calling most of the session methods
146: * after invalidation will throw an IllegalStateException.
147: *
148: * <p>All attribute values which implement HttpSessionBindingListener,
149: * will receive a notice when they're removed at invalidation.
150: */
151: public void invalidate();
152:
153: /**
154: * @deprecated
155: */
156: public HttpSessionContext getSessionContext();
157:
158: /**
159: * Returns the owning servlet context.
160: */
161: public ServletContext getServletContext();
162:
163: /**
164: * @deprecated
165: */
166: public Object getValue(String name);
167:
168: /**
169: * @deprecated
170: */
171: public String[] getValueNames();
172:
173: /**
174: * @deprecated
175: */
176: public void putValue(String name, Object value);
177:
178: /**
179: * @deprecated
180: */
181: public void removeValue(String name);
182:
183: /**
184: * logs the user out and invalidates the sessions.
185: */
186: // public void logout();
187: }
|