1 package org.apache.turbine.services.security;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23
24 import org.apache.commons.configuration2.Configuration;
25 import org.apache.fulcrum.security.acl.AccessControlList;
26 import org.apache.fulcrum.security.util.DataBackendException;
27 import org.apache.fulcrum.security.util.EntityExistsException;
28 import org.apache.fulcrum.security.util.PasswordMismatchException;
29 import org.apache.fulcrum.security.util.UnknownEntityException;
30 import org.apache.turbine.om.security.User;
31 import org.apache.turbine.services.InitializationException;
32
33 /**
34 * An UserManager performs {@link org.apache.turbine.om.security.User} objects
35 * related tasks on behalf of the
36 * {@link org.apache.turbine.services.security.DefaultSecurityService}.
37 *
38 * The responsibilities of this class include loading data of an user from the
39 * storage and putting them into the
40 * {@link org.apache.turbine.om.security.User} objects, saving those data
41 * to the permanent storage, and authenticating users.
42 *
43 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
44 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
45 * @version $Id$
46 */
47 public interface UserManager
48 {
49 /**
50 * Initializes the UserManager
51 *
52 * @param conf A Configuration object to init this Manager
53 *
54 * @throws InitializationException When something went wrong.
55 */
56 void init(Configuration conf)
57 throws InitializationException;
58
59 /**
60 * Check whether a specified user's account exists.
61 *
62 * The login name is used for looking up the account.
63 *
64 * @param user The user to be checked.
65 * @return true if the specified account exists
66 * @throws DataBackendException if there was an error accessing the data
67 * backend.
68 */
69 boolean accountExists(User user)
70 throws DataBackendException;
71
72 /**
73 * Check whether a specified user's account exists.
74 *
75 * The login name is used for looking up the account.
76 *
77 * @param userName The name of the user to be checked.
78 * @return true if the specified account exists
79 * @throws DataBackendException if there was an error accessing the data
80 * backend.
81 */
82 boolean accountExists(String userName)
83 throws DataBackendException;
84
85 /**
86 * Retrieve a user from persistent storage using username as the
87 * key.
88 *
89 * @param <U> user class
90 * @param username the name of the user.
91 * @return an User object.
92 * @throws UnknownEntityException if the user's record does not
93 * exist in the database.
94 * @throws DataBackendException if there is a problem accessing the
95 * storage.
96 */
97 <U extends User> U retrieve(String username)
98 throws UnknownEntityException, DataBackendException;
99
100 /**
101 * Retrieve a list of users that meet the specified criteria.
102 *
103 * As the keys for the criteria, you should use the constants that
104 * are defined in {@link User} interface, plus the names
105 * of the custom attributes you added to your user representation
106 * in the data storage. Use verbatim names of the attributes -
107 * without table name prefix in case of DB implementation.
108 *
109 * @param criteria The criteria of selection.
110 * @return a List of users meeting the criteria.
111 * @throws DataBackendException if there is a problem accessing the
112 * storage.
113 */
114 List<? extends User> retrieveList(Object criteria)
115 throws DataBackendException;
116
117 /**
118 * Retrieve a user from persistent storage using username as the
119 * key, and authenticate the user. The implementation may chose
120 * to authenticate to the server as the user whose data is being
121 * retrieved.
122 *
123 * @param <U> user class
124 * @param username the name of the user.
125 * @param password the user supplied password.
126 * @return an User object.
127 * @throws PasswordMismatchException if the supplied password was incorrect.
128 * @throws UnknownEntityException if the user's record does not
129 * exist in the database.
130 * @throws DataBackendException if there is a problem accessing the storage.
131 */
132 <U extends User> U retrieve(String username, String password)
133 throws PasswordMismatchException, UnknownEntityException,
134 DataBackendException;
135
136 /**
137 * Save an User object to persistent storage. User's record is
138 * required to exist in the storage.
139 *
140 * @param user an User object to store.
141 * @throws UnknownEntityException if the user's record does not
142 * exist in the database.
143 * @throws DataBackendException if there is a problem accessing the storage.
144 */
145 void store(User user)
146 throws UnknownEntityException, DataBackendException;
147
148 /**
149 * Saves User data when the session is unbound. The user account is required
150 * to exist in the storage.
151 *
152 * LastLogin, AccessCounter, persistent pull tools, and any data stored
153 * in the permData hashtable that is not mapped to a column will be saved.
154 *
155 * @param user the user in the session
156 *
157 * @throws UnknownEntityException if the user's account does not
158 * exist in the database.
159 * @throws DataBackendException if there is a problem accessing the
160 * storage.
161 */
162 void saveOnSessionUnbind(User user)
163 throws UnknownEntityException, DataBackendException;
164
165 /**
166 * Authenticate an User with the specified password. If authentication
167 * is successful the method returns nothing. If there are any problems,
168 * exception was thrown.
169 *
170 * @param user an User object to authenticate.
171 * @param password the user supplied password.
172 * @throws PasswordMismatchException if the supplied password was incorrect.
173 * @throws UnknownEntityException if the user's record does not
174 * exist in the database.
175 * @throws DataBackendException if there is a problem accessing the storage.
176 */
177 void authenticate(User user, String password)
178 throws PasswordMismatchException, UnknownEntityException,
179 DataBackendException;
180
181 /**
182 * Creates new user account with specified attributes.
183 *
184 * @param user the object describing account to be created.
185 * @param initialPassword password for the new user
186 * @throws UnknownEntityException if the user account cannot be created.
187 * @throws DataBackendException if there was an error accessing the data
188 * backend.
189 * @throws EntityExistsException if the user account already exists.
190 */
191 void createAccount(User user, String initialPassword)
192 throws UnknownEntityException, EntityExistsException, DataBackendException;
193
194 /**
195 * Removes an user account from the system.
196 *
197 * @param user the object describing the account to be removed.
198 * @throws DataBackendException if there was an error accessing the data
199 * backend.
200 * @throws UnknownEntityException if the user account is not present.
201 */
202 void removeAccount(User user)
203 throws UnknownEntityException, DataBackendException;
204
205 /**
206 * Change the password for an User.
207 *
208 * @param user an User to change password for.
209 * @param oldPassword the current password suplied by the user.
210 * @param newPassword the current password requested by the user.
211 * @throws PasswordMismatchException if the supplied password was incorrect.
212 * @throws UnknownEntityException if the user's record does not
213 * exist in the database.
214 * @throws DataBackendException if there is a problem accessing the storage.
215 */
216 void changePassword(User user, String oldPassword,
217 String newPassword)
218 throws PasswordMismatchException, UnknownEntityException,
219 DataBackendException;
220
221 /**
222 * Forcibly sets new password for an User.
223 *
224 * This is supposed by the administrator to change the forgotten or
225 * compromised passwords. Certain implementatations of this feature
226 * would require administrative level access to the authenticating
227 * server / program.
228 *
229 * @param user an User to change password for.
230 * @param password the new password.
231 * @throws UnknownEntityException if the user's record does not
232 * exist in the database.
233 * @throws DataBackendException if there is a problem accessing the storage.
234 */
235 void forcePassword(User user, String password)
236 throws UnknownEntityException, DataBackendException;
237
238 /**
239 * Constructs an User object to represent an anonymous user of the
240 * application.
241 *
242 * @param <U> user class
243 * @return An anonymous Turbine User.
244 * @throws UnknownEntityException
245 * if the anonymous User object couldn't be constructed.
246 */
247 <U extends User> U getAnonymousUser() throws UnknownEntityException;
248
249 /**
250 * Checks whether a passed user object matches the anonymous user pattern
251 * according to the configured user manager
252 *
253 * @param u a user object
254 *
255 * @return True if this is an anonymous user
256 *
257 */
258 boolean isAnonymousUser(User u);
259
260 /**
261 * Construct a blank User object.
262 *
263 * This method calls getUserClass, and then creates a new object using the
264 * default constructor.
265 *
266 * @param <U> user class
267 * @return an object implementing User interface.
268 * @throws DataBackendException
269 * if the object could not be instantiated.
270 */
271 <U extends User> U getUserInstance() throws DataBackendException;
272
273 /**
274 * Construct a blank User object.
275 *
276 * This method calls getUserClass, and then creates a new object using the
277 * default constructor.
278 *
279 * @param <U> user class
280 * @param userName
281 * The name of the user.
282 *
283 * @return an object implementing User interface.
284 * @throws DataBackendException
285 * if the object could not be instantiated.
286 */
287 <U extends User> U getUserInstance(String userName) throws DataBackendException;
288
289 /**
290 * Return a Class object representing the system's chosen implementation of
291 * of ACL interface for the given user
292 *
293 * @param <A> ACL class
294 * @param user the user
295 * @return systems's chosen implementation of ACL interface.
296 * @throws UnknownEntityException
297 * if the implementation of ACL interface could not be
298 * determined, or does not exist.
299 */
300 <A extends AccessControlList> A getACL(User user) throws UnknownEntityException;
301 }