1 package org.apache.turbine.services.security;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.util.List;
23
24 import org.apache.commons.configuration.Configuration;
25
26 import org.apache.torque.util.Criteria;
27
28 import org.apache.turbine.om.security.User;
29 import org.apache.turbine.services.InitializationException;
30 import org.apache.turbine.util.security.DataBackendException;
31 import org.apache.turbine.util.security.EntityExistsException;
32 import org.apache.turbine.util.security.PasswordMismatchException;
33 import org.apache.turbine.util.security.UnknownEntityException;
34
35 /***
36 * An UserManager performs {@link org.apache.turbine.om.security.User} objects
37 * related tasks on behalf of the
38 * {@link org.apache.turbine.services.security.BaseSecurityService}.
39 *
40 * The responsibilities of this class include loading data of an user from the
41 * storage and putting them into the
42 * {@link org.apache.turbine.om.security.User} objects, saving those data
43 * to the permanent storage, and authenticating users.
44 *
45 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
46 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
47 * @version $Id: UserManager.java 534527 2007-05-02 16:10:59Z tv $
48 */
49 public interface UserManager
50 {
51 /***
52 * Initializes the UserManager
53 *
54 * @param conf A Configuration object to init this Manager
55 *
56 * @throws InitializationException When something went wrong.
57 */
58 void init(Configuration conf)
59 throws InitializationException;
60
61 /***
62 * Check whether a specified user's account exists.
63 *
64 * The login name is used for looking up the account.
65 *
66 * @param user The user to be checked.
67 * @return true if the specified account exists
68 * @throws DataBackendException if there was an error accessing the data
69 * backend.
70 */
71 boolean accountExists(User user)
72 throws DataBackendException;
73
74 /***
75 * Check whether a specified user's account exists.
76 *
77 * The login name is used for looking up the account.
78 *
79 * @param userName The name of the user to be checked.
80 * @return true if the specified account exists
81 * @throws DataBackendException if there was an error accessing the data
82 * backend.
83 */
84 boolean accountExists(String userName)
85 throws DataBackendException;
86
87 /***
88 * Retrieve a user from persistent storage using username as the
89 * key.
90 *
91 * @param username the name of the user.
92 * @return an User object.
93 * @throws UnknownEntityException if the user's record does not
94 * exist in the database.
95 * @throws DataBackendException if there is a problem accessing the
96 * storage.
97 */
98 User retrieve(String username)
99 throws UnknownEntityException, DataBackendException;
100
101 /***
102 * Retrieve a user from persistent storage using the primary key
103 *
104 * @param key The primary key object
105 * @return an User object.
106 * @throws UnknownEntityException if the user's record does not
107 * exist in the database.
108 * @throws DataBackendException if there is a problem accessing the
109 * storage.
110 */
111 User retrieveById(Object key)
112 throws UnknownEntityException, DataBackendException;
113
114 /***
115 * Retrieve a set of users that meet the specified criteria.
116 *
117 * As the keys for the criteria, you should use the constants that
118 * are defined in {@link User} interface, plus the names
119 * of the custom attributes you added to your user representation
120 * in the data storage. Use verbatim names of the attributes -
121 * without table name prefix in case of DB implementation.
122 *
123 * @param criteria The criteria of selection.
124 * @return a List of users meeting the criteria.
125 * @throws DataBackendException if there is a problem accessing the
126 * storage.
127 * @deprecated Use retrieveList(Criteria crit)
128 */
129 User[] retrieve(Criteria criteria) throws DataBackendException;
130
131 /***
132 * Retrieve a list of users that meet the specified criteria.
133 *
134 * As the keys for the criteria, you should use the constants that
135 * are defined in {@link User} interface, plus the names
136 * of the custom attributes you added to your user representation
137 * in the data storage. Use verbatim names of the attributes -
138 * without table name prefix in case of DB implementation.
139 *
140 * @param criteria The criteria of selection.
141 * @return a List of users meeting the criteria.
142 * @throws DataBackendException if there is a problem accessing the
143 * storage.
144 */
145 List retrieveList(Criteria criteria)
146 throws DataBackendException;
147
148 /***
149 * Retrieve a user from persistent storage using username as the
150 * key, and authenticate the user. The implementation may chose
151 * to authenticate to the server as the user whose data is being
152 * retrieved.
153 *
154 * @param username the name of the user.
155 * @param password the user supplied password.
156 * @return an User object.
157 * @throws PasswordMismatchException if the supplied password was incorrect.
158 * @throws UnknownEntityException if the user's record does not
159 * exist in the database.
160 * @throws DataBackendException if there is a problem accessing the storage.
161 */
162 User retrieve(String username, String password)
163 throws PasswordMismatchException, UnknownEntityException,
164 DataBackendException;
165
166 /***
167 * Save an User object to persistent storage. User's record is
168 * required to exist in the storage.
169 *
170 * @param user an User object to store.
171 * @throws UnknownEntityException if the user's record does not
172 * exist in the database.
173 * @throws DataBackendException if there is a problem accessing the storage.
174 */
175 void store(User user)
176 throws UnknownEntityException, DataBackendException;
177
178 /***
179 * Saves User data when the session is unbound. The user account is required
180 * to exist in the storage.
181 *
182 * LastLogin, AccessCounter, persistent pull tools, and any data stored
183 * in the permData hashtable that is not mapped to a column will be saved.
184 *
185 * @exception UnknownEntityException if the user's account does not
186 * exist in the database.
187 * @exception DataBackendException if there is a problem accessing the
188 * storage.
189 */
190 void saveOnSessionUnbind(User user)
191 throws UnknownEntityException, DataBackendException;
192
193 /***
194 * Authenticate an User with the specified password. If authentication
195 * is successful the method returns nothing. If there are any problems,
196 * exception was thrown.
197 *
198 * @param user an User object to authenticate.
199 * @param password the user supplied password.
200 * @throws PasswordMismatchException if the supplied password was incorrect.
201 * @throws UnknownEntityException if the user's record does not
202 * exist in the database.
203 * @throws DataBackendException if there is a problem accessing the storage.
204 */
205 void authenticate(User user, String password)
206 throws PasswordMismatchException, UnknownEntityException,
207 DataBackendException;
208
209 /***
210 * Creates new user account with specified attributes.
211 *
212 * @param user the object describing account to be created.
213 * @param initialPassword password for the new user
214 * @throws DataBackendException if there was an error accessing the data
215 * backend.
216 * @throws EntityExistsException if the user account already exists.
217 */
218 void createAccount(User user, String initialPassword)
219 throws EntityExistsException, DataBackendException;
220
221 /***
222 * Removes an user account from the system.
223 *
224 * @param user the object describing the account to be removed.
225 * @throws DataBackendException if there was an error accessing the data
226 * backend.
227 * @throws UnknownEntityException if the user account is not present.
228 */
229 void removeAccount(User user)
230 throws UnknownEntityException, DataBackendException;
231
232 /***
233 * Change the password for an User.
234 *
235 * @param user an User to change password for.
236 * @param oldPassword the current password suplied by the user.
237 * @param newPassword the current password requested by the user.
238 * @throws PasswordMismatchException if the supplied password was incorrect.
239 * @throws UnknownEntityException if the user's record does not
240 * exist in the database.
241 * @throws DataBackendException if there is a problem accessing the storage.
242 */
243 void changePassword(User user, String oldPassword,
244 String newPassword)
245 throws PasswordMismatchException, UnknownEntityException,
246 DataBackendException;
247
248 /***
249 * Forcibly sets new password for an User.
250 *
251 * This is supposed by the administrator to change the forgotten or
252 * compromised passwords. Certain implementatations of this feature
253 * would require administrative level access to the authenticating
254 * server / program.
255 *
256 * @param user an User to change password for.
257 * @param password the new password.
258 * @throws UnknownEntityException if the user's record does not
259 * exist in the database.
260 * @throws DataBackendException if there is a problem accessing the storage.
261 */
262 void forcePassword(User user, String password)
263 throws UnknownEntityException, DataBackendException;
264 }