001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com>
003: * Distributed under the terms of either:
004: * - the common development and distribution license (CDDL), v1.0; or
005: * - the GNU Lesser General Public License, v2.1 or later
006: * $Id: SessionManager.java 3643 2007-01-12 15:29:45Z gbevin $
007: */
008: package com.uwyn.rife.authentication;
009:
010: import com.uwyn.rife.authentication.exceptions.SessionManagerException;
011:
012: /**
013: * This interface defines the methods that classes with
014: * {@code SessionManager} functionalities have to implement.
015: * <p>A {@code SessionManager} is reponsible for handling all tasks
016: * related to the lifetime of a session in which a user is successfully
017: * authenticated.
018: * <p>This kind of session doesn't provide any state persistance across
019: * requests and doesn't store any additional business data on the server-side.
020: * It merely provides a unique authentication id which can be used to identify
021: * a successfully authenticated user.
022: * <p>For safety's sake, sessions time out after a certain period of
023: * inactivity and their validity is bound only to a unique user id and a host
024: * ip. No assumptions are being made about the actual meaning or structure of
025: * a 'user'. A unique numeric identifier is all that's required.
026: *
027: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
028: * @version $Revision: 3643 $
029: * @see com.uwyn.rife.authentication.SessionValidator
030: * @since 1.0
031: */
032: public interface SessionManager {
033: /**
034: * Obtains the maximum time that a user can stay inactive before an active
035: * session becomes invalid.
036: *
037: * @return The maximum time of inactivity in milliseconds.
038: * @since 1.0
039: */
040: public long getSessionDuration();
041:
042: /**
043: * Sets the maximum time that a user can stay inactive before an active
044: * session becomes invalid.
045: *
046: * @param milliseconds The maximum time of inactivity in milliseconds.
047: * @since 1.0
048: */
049: public void setSessionDuration(long milliseconds);
050:
051: /**
052: * Obtains the restriction policy of the authentication ID with regards to the
053: * user's host IP.
054: * <p>The default is {@code false}, or no restriction.
055: *
056: * @return {@code true} if the authentication is restricted to one host IP; or
057: * <p>{@code false} if the authentication ID can be used with any host IP
058: * @since 1.0
059: */
060: public boolean getRestrictHostIp();
061:
062: /**
063: * Sets the restriction policy of the authentication ID with regards to the
064: * user's host IP.
065: * <p>The default is {@code false}, or no restriction.
066: *
067: * @param flag {@code true} to activate the host IP restriction; or
068: * <p>{@code false} otherwise
069: * @since 1.0
070: */
071: public void setRestrictHostIp(boolean flag);
072:
073: /**
074: * Starts a new session.
075: *
076: * @param userId The id that uniquely identifies the user that is allowed
077: * to use this session.
078: * @param hostIp The ip address of the host from which the user accesses
079: * the application.
080: * @param remembered Indicates whether the session is started through
081: * remember me or from scratch.
082: * @return A {@code String} that uniquely identifies the
083: * authentication session that was just started.
084: * @exception SessionManagerException An undefined number of exceptional
085: * cases or error situations can occur when a session is started. They are
086: * all indicated by throwing an instance of
087: * {@code SessionManagerException}. It's up to the implementations of
088: * this interface to give more specific meanings to these exceptions.
089: * @since 1.0
090: */
091: public String startSession(long userId, String hostIp,
092: boolean remembered) throws SessionManagerException;
093:
094: /**
095: * Verifies if a session is valid and still active.
096: *
097: * @param authId The unique id of the authentication session that needs to
098: * be verified.
099: * @param hostIp The ip address of the host from which the user accesses
100: * the application.
101: * @return {@code true} if a valid active session was found; or
102: * <p>{@code false} if this was not possible.
103: * @exception SessionManagerException An undefined number of exceptional
104: * cases or error situations can occur when a session is verified. They
105: * are all indicated by throwing an instance of
106: * {@code SessionManagerException}. It's up to the implementations of
107: * this interface to give more specific meanings to these exceptions.
108: * @since 1.0
109: */
110: public boolean isSessionValid(String authId, String hostIp)
111: throws SessionManagerException;
112:
113: /**
114: * Continues an already active session. This means that the inactivity
115: * time-out is reset to the maximal value. This is typically called each
116: * time a user accesses an application.
117: *
118: * @param authId The unique id of the authentication session that needs to
119: * be continued.
120: * @return {@code true} if the session was successfully continued; or
121: * <p>{@code false} if this was not possible (ie. the session
122: * couldn't be found).
123: * @exception SessionManagerException An undefined number of exceptional
124: * cases or error situations can occur when a session is continued. They
125: * are all indicated by throwing an instance of
126: * {@code SessionManagerException}. It's up to the implementations of
127: * this interface to give more specific meanings to these exceptions.
128: * @since 1.0
129: */
130: public boolean continueSession(String authId)
131: throws SessionManagerException;
132:
133: /**
134: * Removes all traces of an authentication session. This makes the session
135: * instantly inactive and invalid.
136: *
137: * @param authId The unique id of the authentication session that needs to
138: * be erased.
139: * @return {@code true} if the session was successfully erased; or
140: * <p>{@code false} if this was not possible (ie. the session
141: * couldn't be found).
142: * @exception SessionManagerException An undefined number of exceptional
143: * cases or error situations can occur when a session is erased. They are
144: * all indicated by throwing an instance of
145: * {@code SessionManagerException}. It's up to the implementations of
146: * this interface to give more specific meanings to these exceptions.
147: * @since 1.0
148: */
149: public boolean eraseSession(String authId)
150: throws SessionManagerException;
151:
152: /**
153: * Checks if a session was previously automatically created from remembered
154: * data.
155: *
156: * @param authId The unique id of the authentication session that needs to
157: * be erased.
158: * @return {@code true} if the session was created automatically from
159: * remembered data; or
160: * <p>{@code false} if it was created from full credentials or if the
161: * session couldn't be found.
162: *
163: * @exception SessionManagerException An undefined number of exceptional
164: * cases or error situations can occur when a session is erased. They are
165: * all indicated by throwing an instance of
166: * {@code SessionManagerException}. It's up to the implementations of
167: * this interface to give more specific meanings to these exceptions.
168: * @since 1.0
169: */
170: public boolean wasRemembered(String authId)
171: throws SessionManagerException;
172:
173: /**
174: * Removes all traces of all authentication sessions for a particular
175: * user. This makes all sessions of this user instantly inactive and
176: * invalid.
177: *
178: * @param userId The id that uniquely identifies the user whose sessions
179: * are to be erased.
180: * @return {@code true} if the sessions were successfully erased; or
181: * <p>{@code false} if this was not possible (ie. no sessions
182: * couldn't be found).
183: * @exception SessionManagerException An undefined number of exceptional
184: * cases or error situations can occur when a session is erased. They are
185: * all indicated by throwing an instance of
186: * {@code SessionManagerException}. It's up to the implementations of
187: * this interface to give more specific meanings to these exceptions.
188: * @since 1.0
189: */
190: public boolean eraseUserSessions(long userId)
191: throws SessionManagerException;
192:
193: /**
194: * Removes all available sessions. This makes all sessions instantly
195: * invalid and inactive for all users.
196: *
197: * @exception SessionManagerException An undefined number of exceptional
198: * cases or error situations can occur when a session is erased. They are
199: * all indicated by throwing an instance of
200: * {@code SessionManagerException}. It's up to the implementations of
201: * this interface to give more specific meanings to these exceptions.
202: * @since 1.0
203: */
204: public void eraseAllSessions() throws SessionManagerException;
205:
206: /**
207: * Retrieves the id of a user that has access to a particular session.
208: *
209: * @param authId The unique id of the authentication session for which the
210: * user needs to be looked up.
211: * @return A long {@code >= 0} that corresponds to the user id
212: * that has access to the session; or
213: * <p>{@code -1} if the session couldn't be found.
214: * @exception SessionManagerException An undefined number of exceptional
215: * cases or error situations can occur when user id of a session is
216: * retrieved. They are all indicated by throwing an instance of
217: * {@code SessionManagerException}. It's up to the implementations of
218: * this interface to give more specific meanings to these exceptions.
219: * @since 1.0
220: */
221: public long getSessionUserId(String authId)
222: throws SessionManagerException;
223:
224: /**
225: * Removes all sessions that are inactive. This means that all sessions
226: * where the inactivity time has been exceeded, will be removed.
227: *
228: * @exception SessionManagerException An undefined number of exceptional
229: * cases or error situations can occur when a session is purged. They are
230: * all indicated by throwing an instance of
231: * {@code SessionManagerException}. It's up to the implementations of
232: * this interface to give more specific meanings to these exceptions.
233: * @since 1.0
234: */
235: public void purgeSessions() throws SessionManagerException;
236:
237: /**
238: * Counts the number of active sessions.
239: *
240: * @return The number of active sessions.
241: * @exception SessionManagerException An undefined number of exceptional
242: * cases or error situations can occur when a session is counted. They are
243: * all indicated by throwing an instance of
244: * {@code SessionManagerException}. It's up to the implementations of
245: * this interface to give more specific meanings to these exceptions.
246: * @since 1.0
247: */
248: public long countSessions() throws SessionManagerException;
249:
250: /**
251: * Lists the active sessions.
252: *
253: * @param processor The row processor that will be used to list the active
254: * sessions.
255: * @return {@code true} if active sessions were found; or
256: * <p>{@code false} if no session was active.
257: * @exception SessionManagerException An undefined number of exceptional
258: * cases or error situations can occur when session are listed. They are
259: * all indicated by throwing an instance of
260: * {@code SessionManagerException}. It's up to the implementations of
261: * this interface to give more specific meanings to these exceptions.
262: * @since 1.0
263: */
264: public boolean listSessions(ListSessions processor)
265: throws SessionManagerException;
266: }
|