001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: SessionManager.java,v 1.4 2007-10-19 10:05:39 sinisa Exp $
022: *
023: * formatted with JxBeauty (c) johann.langhofer@nextra.at
024: */
025:
026: package com.lutris.appserver.server.session;
027:
028: import java.util.Date;
029: import java.util.Enumeration;
030:
031: import com.lutris.appserver.server.httpPresentation.HttpPresentationComms;
032: import com.lutris.appserver.server.user.User;
033:
034: /**
035: * The session management object interface. This class implementing this
036: * interface manage the session state for currently active users of one or more
037: * applications. It allocates sessions and maintains the mapping between session
038: * keys and Session objects.
039: *
040: * @version $Revision: 1.4 $
041: * @author Shawn McMurdo
042: * @author Mark Diekhans
043: */
044: public interface SessionManager {
045: /**
046: * Indicates that url encoding of session ids is never preformed.
047: *
048: * @see #getEncodeUrlState
049: */
050: public static final String ENCODE_URL_NEVER = "Never";
051:
052: /**
053: * Indicates that url encoding of session ids is always preformed.
054: *
055: * @see #getEncodeUrlState
056: */
057: public static final String ENCODE_URL_ALWAYS = "Always";
058:
059: /**
060: * Indicates that url encoding of session ids is preformed only when cookies
061: * are disabled on the client browser. This is automatically detected.
062: *
063: * @see #getEncodeUrlState
064: */
065: public static final String ENCODE_URL_AUTO = "Auto";
066:
067: /**
068: * Create a new <CODE>Session</CODE> object and an associated unique
069: * random key. No <CODE>User</CODE> object is initially associated with
070: * the session (<CODE>getUser()</CODE> returns <CODE>null</CODE>).
071: *
072: * @return session The new <code>Session</code> object.
073: * @exception SessionException
074: * if the session cannot be created.
075: * @see Session
076: */
077: public Session createSession() throws SessionException;
078:
079: /**
080: * Create a new <CODE>Session</CODE> object and an associated unique
081: * random key. No <CODE>User</CODE> object is initially associated with
082: * the session (<CODE>getUser()</CODE> returns <CODE>null</CODE>).
083: *
084: * @param ipPortToken
085: * The base64 encoded IP and Port number to include in session
086: * key
087: * @return session The new <code>Session</code> object.
088: * @exception SessionException
089: * if the session cannot be created.
090: * @see Session
091: */
092: public Session createSession(String ipPortToken)
093: throws SessionException;
094:
095: /**
096: * Create a new <CODE>Session</CODE> object and an associated unique
097: * random key. No <CODE>User</CODE> object is initially associated with
098: * the session (<CODE>getUser()</CODE> returns <CODE>null</CODE>).
099: *
100: * @param comms
101: * The presentations manager comms object with all
102: * request/response information in it.
103: * @return session The new <code>Session</code> object.
104: * @exception SessionException
105: * if the session cannot be created.
106: * @see Session
107: */
108:
109: public Session createSession(HttpPresentationComms comms)
110: throws SessionException;
111:
112: /**
113: * Removes a session from the session manager.
114: *
115: * @param session
116: * The session object to delete.
117: * @exception SessionException
118: * if the session cannot be deleted.
119: */
120: public void deleteSession(Session session) throws SessionException;
121:
122: /**
123: * Removes a session from the manager.
124: *
125: * @param sessionKey
126: * the session key.
127: * @exception SessionException
128: * if the session cannot be deleted.
129: */
130: public void deleteSession(String sessionKey)
131: throws SessionException;
132:
133: /**
134: * Returns whether the <code>Session</code> object associated with the
135: * specified session key exists.
136: *
137: * @param sessionKey
138: * The String used to reference a <code>Session</code> object.
139: * @return If the key is associated with an active session, then return
140: * true, otherwise return false.
141: * @exception SessionException
142: * if the existence of the session cannot be determined.
143: */
144: public boolean sessionExists(String sessionKey)
145: throws SessionException;
146:
147: /**
148: * Returns the <code>Session</code> object associated with the specified
149: * session key. The session is put in the 'active' state. If no
150: * <code>Session</code> object is associated with the key then this method
151: * returns <code>null</code>.
152: *
153: * @param sessionKey
154: * The String used to reference a <code>Session</code> object.
155: * @return If the key is associated with an active session, then the
156: * corresponding <code>Session</code> object is returned.
157: * Otherwise <code>null</code> is returned.
158: * @see Session
159: * @exception SessionException
160: * if the session cannot be retrieved.
161: */
162: public Session getSession(String sessionKey)
163: throws SessionException;
164:
165: /**
166: * Returns the <code>Session</code> object associated with the specified
167: * session key. The session is put in the 'active' state. If no
168: * <code>Session</code> object is associated with the key then this method
169: * returns <code>null</code>.
170: *
171: * @param thread
172: * the thread that should be associated with the session. Only
173: * this thread can subsequently put the session into the passive
174: * state.
175: * @param sessionKey
176: * The String used to reference a <code>Session</code> object.
177: * @return If the key is associated with an active session, then the
178: * corresponding <code>Session</code> object is returned.
179: * Otherwise <code>null</code> is returned.
180: * @see Session
181: * @exception SessionException
182: * if the session cannot be retrieved.
183: */
184: public Session getSession(Thread thread, String sessionKey)
185: throws SessionException;
186:
187: /**
188: * Returns the <code>Session</code> object associated with the specified
189: * session key. The session is put in the 'active' state. If no
190: * <code>Session</code> object is associated with the key then this method
191: * returns <code>null</code>.
192: *
193: * @param thread
194: * the thread that should be associated with the session. Only
195: * this thread can subsequently put the session into the passive
196: * state.
197: * @param comms
198: * The presentations manager comms object with all
199: * request/response information in it.
200: * @param sessionKey
201: * The String used to reference a <code>Session</code> object.
202: * @return If the key is associated with an active session, then the
203: * corresponding <code>Session</code> object is returned.
204: * Otherwise <code>null</code> is returned.
205: * @see Session
206: * @exception SessionException
207: * if the session cannot be retrieved.
208: */
209:
210: public Session getSession(Thread thread, String sessionKey,
211: HttpPresentationComms comms) throws SessionException;
212:
213: /**
214: * Lookup active sessions keys for a user. A given user may have multiple
215: * sessions associated with it.
216: *
217: * @param user
218: * The user to search for.
219: * @return An enumeration of the active sessions keys for the user.
220: * @exception SessionException
221: * if the sessions cannot be retrieved.
222: */
223: public Enumeration getSessionKeys(User user)
224: throws SessionException;
225:
226: /**
227: * Puts a session into the 'passive' state. A 'passive' session may be made
228: * persistent.
229: *
230: * @param thread
231: * the thread currently associate with the the session.
232: * @param sessionKey
233: * the session key for the session that will be made persistent.
234: * @exception SessionException
235: * if the session cannot be put into the passive state..
236: */
237: public void passivateSession(Thread thread, String sessionKey)
238: throws SessionException;
239:
240: /**
241: * Gets the number of currently active sessions.
242: *
243: * @return The number of currently active sessions.
244: * @exception SessionException
245: * if the active session count cannot be determined.
246: */
247: public int activeSessionCount() throws SessionException;
248:
249: /**
250: * Gets the maximum number of concurent sessions that existed at any time
251: * since this object was created, or <CODE>resetMaxSessionCount()</CODE>
252: * was called. This is a historical highwater mark. If you do not implement
253: * this feature, return -1.
254: *
255: * @return The highwater mark for number of sessions, or -1.
256: */
257: public int maxSessionCount();
258:
259: /**
260: * Gets the time when the maximum refered to by <CODE>maxSessionCount()</CODE>
261: * occured.
262: *
263: * @return The Date of when the maximum number of sessions occured.
264: */
265: public Date maxSessionCountDate();
266:
267: /**
268: * Reset the maximum session count. See <CODE>maxSessionCount()</CODE>.
269: * The highwater mark should be reset to the current number of sessions.
270: *
271: * @exception SessionException
272: * if the max session count cannot be reset.
273: */
274: public void resetMaxSessionCount() throws SessionException;
275:
276: /**
277: * Get an enumeration of all session keys.
278: *
279: * @return An enumeration of the session keys.
280: * @exception SessionException
281: * if the session keys cannot be retrieved.
282: */
283: public Enumeration getSessionKeys() throws SessionException;
284:
285: /**
286: * Shutdown this session manager as required. The session manager should not
287: * be used after this method has been called
288: */
289: public void shutdown();
290:
291: /**
292: * Returns the url encoding state. Either <code>Never</code>
293: * <code>Always</code> <code>Auto</code>
294: */
295: public String getEncodeUrlState();
296:
297: /**
298: * Return value determins whether to use empty path (/) as session cookie
299: * path attribute value!
300: *
301: * @return Whether to use empty path for session cookies
302: */
303: public boolean getEmptySessionPath();
304:
305: /**
306: * Returns the url encoding rule for the first application page
307: * (true/false).
308: *
309: */
310: public boolean getEncodeFirstUrl();
311:
312: }
|