001: /*
002: * Copyright 1999-2001,2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.catalina;
018:
019: import java.security.Principal;
020: import java.util.Iterator;
021:
022: import javax.servlet.http.HttpSession;
023:
024: /**
025: * A <b>Session</b> is the Catalina-internal facade for an
026: * <code>HttpSession</code> that is used to maintain state information
027: * between requests for a particular user of a web application.
028: *
029: * @author Craig R. McClanahan
030: * @version $Revision: 1.4 $ $Date: 2004/02/27 14:58:39 $
031: */
032:
033: public interface Session {
034:
035: // ----------------------------------------------------- Manifest Constants
036:
037: /**
038: * The SessionEvent event type when a session is created.
039: */
040: public static final String SESSION_CREATED_EVENT = "createSession";
041:
042: /**
043: * The SessionEvent event type when a session is destroyed.
044: */
045: public static final String SESSION_DESTROYED_EVENT = "destroySession";
046:
047: // ------------------------------------------------------------- Properties
048:
049: /**
050: * Return the authentication type used to authenticate our cached
051: * Principal, if any.
052: */
053: public String getAuthType();
054:
055: /**
056: * Set the authentication type used to authenticate our cached
057: * Principal, if any.
058: *
059: * @param authType The new cached authentication type
060: */
061: public void setAuthType(String authType);
062:
063: /**
064: * Return the creation time for this session.
065: */
066: public long getCreationTime();
067:
068: /**
069: * Set the creation time for this session. This method is called by the
070: * Manager when an existing Session instance is reused.
071: *
072: * @param time The new creation time
073: */
074: public void setCreationTime(long time);
075:
076: /**
077: * Return the session identifier for this session.
078: */
079: public String getId();
080:
081: /**
082: * Set the session identifier for this session.
083: *
084: * @param id The new session identifier
085: */
086: public void setId(String id);
087:
088: /**
089: * Return descriptive information about this Session implementation and
090: * the corresponding version number, in the format
091: * <code><description>/<version></code>.
092: */
093: public String getInfo();
094:
095: /**
096: * Return the last time the client sent a request associated with this
097: * session, as the number of milliseconds since midnight, January 1, 1970
098: * GMT. Actions that your application takes, such as getting or setting
099: * a value associated with the session, do not affect the access time.
100: */
101: public long getLastAccessedTime();
102:
103: /**
104: * Return the Manager within which this Session is valid.
105: */
106: public Manager getManager();
107:
108: /**
109: * Set the Manager within which this Session is valid.
110: *
111: * @param manager The new Manager
112: */
113: public void setManager(Manager manager);
114:
115: /**
116: * Return the maximum time interval, in seconds, between client requests
117: * before the servlet container will invalidate the session. A negative
118: * time indicates that the session should never time out.
119: */
120: public int getMaxInactiveInterval();
121:
122: /**
123: * Set the maximum time interval, in seconds, between client requests
124: * before the servlet container will invalidate the session. A negative
125: * time indicates that the session should never time out.
126: *
127: * @param interval The new maximum interval
128: */
129: public void setMaxInactiveInterval(int interval);
130:
131: /**
132: * Set the <code>isNew</code> flag for this session.
133: *
134: * @param isNew The new value for the <code>isNew</code> flag
135: */
136: public void setNew(boolean isNew);
137:
138: /**
139: * Return the authenticated Principal that is associated with this Session.
140: * This provides an <code>Authenticator</code> with a means to cache a
141: * previously authenticated Principal, and avoid potentially expensive
142: * <code>Realm.authenticate()</code> calls on every request. If there
143: * is no current associated Principal, return <code>null</code>.
144: */
145: public Principal getPrincipal();
146:
147: /**
148: * Set the authenticated Principal that is associated with this Session.
149: * This provides an <code>Authenticator</code> with a means to cache a
150: * previously authenticated Principal, and avoid potentially expensive
151: * <code>Realm.authenticate()</code> calls on every request.
152: *
153: * @param principal The new Principal, or <code>null</code> if none
154: */
155: public void setPrincipal(Principal principal);
156:
157: /**
158: * Return the <code>HttpSession</code> for which this object
159: * is the facade.
160: */
161: public HttpSession getSession();
162:
163: /**
164: * Set the <code>isValid</code> flag for this session.
165: *
166: * @param isValid The new value for the <code>isValid</code> flag
167: */
168: public void setValid(boolean isValid);
169:
170: /**
171: * Return the <code>isValid</code> flag for this session.
172: */
173: public boolean isValid();
174:
175: // --------------------------------------------------------- Public Methods
176:
177: /**
178: * Update the accessed time information for this session. This method
179: * should be called by the context when a request comes in for a particular
180: * session, even if the application does not reference it.
181: */
182: public void access();
183:
184: /**
185: * Add a session event listener to this component.
186: */
187: public void addSessionListener(SessionListener listener);
188:
189: /**
190: * End access to the session.
191: */
192: public void endAccess();
193:
194: /**
195: * Perform the internal processing required to invalidate this session,
196: * without triggering an exception if the session has already expired.
197: */
198: public void expire();
199:
200: /**
201: * Return the object bound with the specified name to the internal notes
202: * for this session, or <code>null</code> if no such binding exists.
203: *
204: * @param name Name of the note to be returned
205: */
206: public Object getNote(String name);
207:
208: /**
209: * Return an Iterator containing the String names of all notes bindings
210: * that exist for this session.
211: */
212: public Iterator getNoteNames();
213:
214: /**
215: * Release all object references, and initialize instance variables, in
216: * preparation for reuse of this object.
217: */
218: public void recycle();
219:
220: /**
221: * Remove any object bound to the specified name in the internal notes
222: * for this session.
223: *
224: * @param name Name of the note to be removed
225: */
226: public void removeNote(String name);
227:
228: /**
229: * Remove a session event listener from this component.
230: */
231: public void removeSessionListener(SessionListener listener);
232:
233: /**
234: * Bind an object to a specified name in the internal notes associated
235: * with this session, replacing any existing binding for this name.
236: *
237: * @param name Name to which the object should be bound
238: * @param value Object to be bound to the specified name
239: */
240: public void setNote(String name, Object value);
241:
242: }
|