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:
018: package org.apache.catalina;
019:
020: import java.security.Principal;
021: import java.util.Iterator;
022:
023: import javax.servlet.http.HttpSession;
024:
025: /**
026: * A <b>Session</b> is the Catalina-internal facade for an
027: * <code>HttpSession</code> that is used to maintain state information
028: * between requests for a particular user of a web application.
029: *
030: * @author Craig R. McClanahan
031: * @version $Revision: 467222 $ $Date: 2006-10-24 05:17:11 +0200 (mar., 24 oct. 2006) $
032: */
033:
034: public interface Session {
035:
036: // ----------------------------------------------------- Manifest Constants
037:
038: /**
039: * The SessionEvent event type when a session is created.
040: */
041: public static final String SESSION_CREATED_EVENT = "createSession";
042:
043: /**
044: * The SessionEvent event type when a session is destroyed.
045: */
046: public static final String SESSION_DESTROYED_EVENT = "destroySession";
047:
048: /**
049: * The SessionEvent event type when a session is activated.
050: */
051: public static final String SESSION_ACTIVATED_EVENT = "activateSession";
052:
053: /**
054: * The SessionEvent event type when a session is passivated.
055: */
056: public static final String SESSION_PASSIVATED_EVENT = "passivateSession";
057:
058: // ------------------------------------------------------------- Properties
059:
060: /**
061: * Return the authentication type used to authenticate our cached
062: * Principal, if any.
063: */
064: public String getAuthType();
065:
066: /**
067: * Set the authentication type used to authenticate our cached
068: * Principal, if any.
069: *
070: * @param authType The new cached authentication type
071: */
072: public void setAuthType(String authType);
073:
074: /**
075: * Return the creation time for this session.
076: */
077: public long getCreationTime();
078:
079: /**
080: * Set the creation time for this session. This method is called by the
081: * Manager when an existing Session instance is reused.
082: *
083: * @param time The new creation time
084: */
085: public void setCreationTime(long time);
086:
087: /**
088: * Return the session identifier for this session.
089: */
090: public String getId();
091:
092: /**
093: * Return the session identifier for this session.
094: */
095: public String getIdInternal();
096:
097: /**
098: * Set the session identifier for this session.
099: *
100: * @param id The new session identifier
101: */
102: public void setId(String id);
103:
104: /**
105: * Return descriptive information about this Session implementation and
106: * the corresponding version number, in the format
107: * <code><description>/<version></code>.
108: */
109: public String getInfo();
110:
111: /**
112: * Return the last time the client sent a request associated with this
113: * session, as the number of milliseconds since midnight, January 1, 1970
114: * GMT. Actions that your application takes, such as getting or setting
115: * a value associated with the session, do not affect the access time.
116: */
117: public long getLastAccessedTime();
118:
119: /**
120: * Return the last client access time without invalidation check
121: * @see #getLastAccessedTime().
122: */
123: public long getLastAccessedTimeInternal();
124:
125: /**
126: * Return the Manager within which this Session is valid.
127: */
128: public Manager getManager();
129:
130: /**
131: * Set the Manager within which this Session is valid.
132: *
133: * @param manager The new Manager
134: */
135: public void setManager(Manager manager);
136:
137: /**
138: * Return the maximum time interval, in seconds, between client requests
139: * before the servlet container will invalidate the session. A negative
140: * time indicates that the session should never time out.
141: */
142: public int getMaxInactiveInterval();
143:
144: /**
145: * Set the maximum time interval, in seconds, between client requests
146: * before the servlet container will invalidate the session. A negative
147: * time indicates that the session should never time out.
148: *
149: * @param interval The new maximum interval
150: */
151: public void setMaxInactiveInterval(int interval);
152:
153: /**
154: * Set the <code>isNew</code> flag for this session.
155: *
156: * @param isNew The new value for the <code>isNew</code> flag
157: */
158: public void setNew(boolean isNew);
159:
160: /**
161: * Return the authenticated Principal that is associated with this Session.
162: * This provides an <code>Authenticator</code> with a means to cache a
163: * previously authenticated Principal, and avoid potentially expensive
164: * <code>Realm.authenticate()</code> calls on every request. If there
165: * is no current associated Principal, return <code>null</code>.
166: */
167: public Principal getPrincipal();
168:
169: /**
170: * Set the authenticated Principal that is associated with this Session.
171: * This provides an <code>Authenticator</code> with a means to cache a
172: * previously authenticated Principal, and avoid potentially expensive
173: * <code>Realm.authenticate()</code> calls on every request.
174: *
175: * @param principal The new Principal, or <code>null</code> if none
176: */
177: public void setPrincipal(Principal principal);
178:
179: /**
180: * Return the <code>HttpSession</code> for which this object
181: * is the facade.
182: */
183: public HttpSession getSession();
184:
185: /**
186: * Set the <code>isValid</code> flag for this session.
187: *
188: * @param isValid The new value for the <code>isValid</code> flag
189: */
190: public void setValid(boolean isValid);
191:
192: /**
193: * Return the <code>isValid</code> flag for this session.
194: */
195: public boolean isValid();
196:
197: // --------------------------------------------------------- Public Methods
198:
199: /**
200: * Update the accessed time information for this session. This method
201: * should be called by the context when a request comes in for a particular
202: * session, even if the application does not reference it.
203: */
204: public void access();
205:
206: /**
207: * Add a session event listener to this component.
208: */
209: public void addSessionListener(SessionListener listener);
210:
211: /**
212: * End access to the session.
213: */
214: public void endAccess();
215:
216: /**
217: * Perform the internal processing required to invalidate this session,
218: * without triggering an exception if the session has already expired.
219: */
220: public void expire();
221:
222: /**
223: * Return the object bound with the specified name to the internal notes
224: * for this session, or <code>null</code> if no such binding exists.
225: *
226: * @param name Name of the note to be returned
227: */
228: public Object getNote(String name);
229:
230: /**
231: * Return an Iterator containing the String names of all notes bindings
232: * that exist for this session.
233: */
234: public Iterator getNoteNames();
235:
236: /**
237: * Release all object references, and initialize instance variables, in
238: * preparation for reuse of this object.
239: */
240: public void recycle();
241:
242: /**
243: * Remove any object bound to the specified name in the internal notes
244: * for this session.
245: *
246: * @param name Name of the note to be removed
247: */
248: public void removeNote(String name);
249:
250: /**
251: * Remove a session event listener from this component.
252: */
253: public void removeSessionListener(SessionListener listener);
254:
255: /**
256: * Bind an object to a specified name in the internal notes associated
257: * with this session, replacing any existing binding for this name.
258: *
259: * @param name Name to which the object should be bound
260: * @param value Object to be bound to the specified name
261: */
262: public void setNote(String name, Object value);
263:
264: }
|