001: /*
002: * $Header: /home/cvs/jakarta-tomcat-4.0/catalina/src/share/org/apache/catalina/Session.java,v 1.5 2001/07/31 02:00:02 craigmcc Exp $
003: * $Revision: 1.5 $
004: * $Date: 2001/07/31 02:00:02 $
005: *
006: * ====================================================================
007: *
008: * The Apache Software License, Version 1.1
009: *
010: * Copyright (c) 1999-2001 The Apache Software Foundation. All rights
011: * reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions
015: * are met:
016: *
017: * 1. Redistributions of source code must retain the above copyright
018: * notice, this list of conditions and the following disclaimer.
019: *
020: * 2. Redistributions in binary form must reproduce the above copyright
021: * notice, this list of conditions and the following disclaimer in
022: * the documentation and/or other materials provided with the
023: * distribution.
024: *
025: * 3. The end-user documentation included with the redistribution, if
026: * any, must include the following acknowlegement:
027: * "This product includes software developed by the
028: * Apache Software Foundation (http://www.apache.org/)."
029: * Alternately, this acknowlegement may appear in the software itself,
030: * if and wherever such third-party acknowlegements normally appear.
031: *
032: * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
033: * Foundation" must not be used to endorse or promote products derived
034: * from this software without prior written permission. For written
035: * permission, please contact apache@apache.org.
036: *
037: * 5. Products derived from this software may not be called "Apache"
038: * nor may "Apache" appear in their names without prior written
039: * permission of the Apache Group.
040: *
041: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
042: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
043: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
044: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
045: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
046: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
047: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
048: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
049: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
050: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
051: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
052: * SUCH DAMAGE.
053: * ====================================================================
054: *
055: * This software consists of voluntary contributions made by many
056: * individuals on behalf of the Apache Software Foundation. For more
057: * information on the Apache Software Foundation, please see
058: * <http://www.apache.org/>.
059: *
060: * [Additional notices, if required by prior licensing conditions]
061: *
062: */
063:
064: package org.apache.catalina;
065:
066: import java.io.IOException;
067: import java.security.Principal;
068: import java.util.Iterator;
069: import javax.servlet.ServletException;
070: import javax.servlet.http.HttpSession;
071:
072: /**
073: * A <b>Session</b> is the Catalina-internal facade for an
074: * <code>HttpSession</code> that is used to maintain state information
075: * between requests for a particular user of a web application.
076: *
077: * @author Craig R. McClanahan
078: * @version $Revision: 1.5 $ $Date: 2001/07/31 02:00:02 $
079: */
080:
081: public interface Session {
082:
083: // ----------------------------------------------------- Manifest Constants
084:
085: /**
086: * The SessionEvent event type when a session is created.
087: */
088: public static final String SESSION_CREATED_EVENT = "createSession";
089:
090: /**
091: * The SessionEvent event type when a session is destroyed.
092: */
093: public static final String SESSION_DESTROYED_EVENT = "destroySession";
094:
095: // ------------------------------------------------------------- Properties
096:
097: /**
098: * Return the authentication type used to authenticate our cached
099: * Principal, if any.
100: */
101: public String getAuthType();
102:
103: /**
104: * Set the authentication type used to authenticate our cached
105: * Principal, if any.
106: *
107: * @param authType The new cached authentication type
108: */
109: public void setAuthType(String authType);
110:
111: /**
112: * Return the creation time for this session.
113: */
114: public long getCreationTime();
115:
116: /**
117: * Set the creation time for this session. This method is called by the
118: * Manager when an existing Session instance is reused.
119: *
120: * @param time The new creation time
121: */
122: public void setCreationTime(long time);
123:
124: /**
125: * Return the session identifier for this session.
126: */
127: public String getId();
128:
129: /**
130: * Set the session identifier for this session.
131: *
132: * @param id The new session identifier
133: */
134: public void setId(String id);
135:
136: /**
137: * Return descriptive information about this Session implementation and
138: * the corresponding version number, in the format
139: * <code><description>/<version></code>.
140: */
141: public String getInfo();
142:
143: /**
144: * Return the last time the client sent a request associated with this
145: * session, as the number of milliseconds since midnight, January 1, 1970
146: * GMT. Actions that your application takes, such as getting or setting
147: * a value associated with the session, do not affect the access time.
148: */
149: public long getLastAccessedTime();
150:
151: /**
152: * Return the Manager within which this Session is valid.
153: */
154: public Manager getManager();
155:
156: /**
157: * Set the Manager within which this Session is valid.
158: *
159: * @param manager The new Manager
160: */
161: public void setManager(Manager manager);
162:
163: /**
164: * Return the maximum time interval, in seconds, between client requests
165: * before the servlet container will invalidate the session. A negative
166: * time indicates that the session should never time out.
167: */
168: public int getMaxInactiveInterval();
169:
170: /**
171: * Set the maximum time interval, in seconds, between client requests
172: * before the servlet container will invalidate the session. A negative
173: * time indicates that the session should never time out.
174: *
175: * @param interval The new maximum interval
176: */
177: public void setMaxInactiveInterval(int interval);
178:
179: /**
180: * Set the <code>isNew</code> flag for this session.
181: *
182: * @param isNew The new value for the <code>isNew</code> flag
183: */
184: public void setNew(boolean isNew);
185:
186: /**
187: * Return the authenticated Principal that is associated with this Session.
188: * This provides an <code>Authenticator</code> with a means to cache a
189: * previously authenticated Principal, and avoid potentially expensive
190: * <code>Realm.authenticate()</code> calls on every request. If there
191: * is no current associated Principal, return <code>null</code>.
192: */
193: public Principal getPrincipal();
194:
195: /**
196: * Set the authenticated Principal that is associated with this Session.
197: * This provides an <code>Authenticator</code> with a means to cache a
198: * previously authenticated Principal, and avoid potentially expensive
199: * <code>Realm.authenticate()</code> calls on every request.
200: *
201: * @param principal The new Principal, or <code>null</code> if none
202: */
203: public void setPrincipal(Principal principal);
204:
205: /**
206: * Return the <code>HttpSession</code> for which this object
207: * is the facade.
208: */
209: public HttpSession getSession();
210:
211: /**
212: * Set the <code>isValid</code> flag for this session.
213: *
214: * @param isValid The new value for the <code>isValid</code> flag
215: */
216: public void setValid(boolean isValid);
217:
218: /**
219: * Return the <code>isValid</code> flag for this session.
220: */
221: public boolean isValid();
222:
223: // --------------------------------------------------------- Public Methods
224:
225: /**
226: * Update the accessed time information for this session. This method
227: * should be called by the context when a request comes in for a particular
228: * session, even if the application does not reference it.
229: */
230: public void access();
231:
232: /**
233: * Add a session event listener to this component.
234: */
235: public void addSessionListener(SessionListener listener);
236:
237: /**
238: * Perform the internal processing required to invalidate this session,
239: * without triggering an exception if the session has already expired.
240: */
241: public void expire();
242:
243: /**
244: * Return the object bound with the specified name to the internal notes
245: * for this session, or <code>null</code> if no such binding exists.
246: *
247: * @param name Name of the note to be returned
248: */
249: public Object getNote(String name);
250:
251: /**
252: * Return an Iterator containing the String names of all notes bindings
253: * that exist for this session.
254: */
255: public Iterator getNoteNames();
256:
257: /**
258: * Release all object references, and initialize instance variables, in
259: * preparation for reuse of this object.
260: */
261: public void recycle();
262:
263: /**
264: * Remove any object bound to the specified name in the internal notes
265: * for this session.
266: *
267: * @param name Name of the note to be removed
268: */
269: public void removeNote(String name);
270:
271: /**
272: * Remove a session event listener from this component.
273: */
274: public void removeSessionListener(SessionListener listener);
275:
276: /**
277: * Bind an object to a specified name in the internal notes associated
278: * with this session, replacing any existing binding for this name.
279: *
280: * @param name Name to which the object should be bound
281: * @param value Object to be bound to the specified name
282: */
283: public void setNote(String name, Object value);
284:
285: }
|