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.configuration.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: UserManager.java 1706239 2015-10-01 13:18:35Z tv $
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 username the name of the user.
90 * @return an User object.
91 * @throws UnknownEntityException if the user's record does not
92 * exist in the database.
93 * @throws DataBackendException if there is a problem accessing the
94 * storage.
95 */
96 <U extends User> U retrieve(String username)
97 throws UnknownEntityException, DataBackendException;
98
99 /**
100 * Retrieve a list of users that meet the specified criteria.
101 *
102 * As the keys for the criteria, you should use the constants that
103 * are defined in {@link User} interface, plus the names
104 * of the custom attributes you added to your user representation
105 * in the data storage. Use verbatim names of the attributes -
106 * without table name prefix in case of DB implementation.
107 *
108 * @param criteria The criteria of selection.
109 * @return a List of users meeting the criteria.
110 * @throws DataBackendException if there is a problem accessing the
111 * storage.
112 */
113 List<? extends User> retrieveList(Object criteria)
114 throws DataBackendException;
115
116 /**
117 * Retrieve a user from persistent storage using username as the
118 * key, and authenticate the user. The implementation may chose
119 * to authenticate to the server as the user whose data is being
120 * retrieved.
121 *
122 * @param username the name of the user.
123 * @param password the user supplied password.
124 * @return an User object.
125 * @throws PasswordMismatchException if the supplied password was incorrect.
126 * @throws UnknownEntityException if the user's record does not
127 * exist in the database.
128 * @throws DataBackendException if there is a problem accessing the storage.
129 */
130 <U extends User> U retrieve(String username, String password)
131 throws PasswordMismatchException, UnknownEntityException,
132 DataBackendException;
133
134 /**
135 * Save an User object to persistent storage. User's record is
136 * required to exist in the storage.
137 *
138 * @param user an User object to store.
139 * @throws UnknownEntityException if the user's record does not
140 * exist in the database.
141 * @throws DataBackendException if there is a problem accessing the storage.
142 */
143 void store(User user)
144 throws UnknownEntityException, DataBackendException;
145
146 /**
147 * Saves User data when the session is unbound. The user account is required
148 * to exist in the storage.
149 *
150 * LastLogin, AccessCounter, persistent pull tools, and any data stored
151 * in the permData hashtable that is not mapped to a column will be saved.
152 *
153 * @param user the user in the session
154 *
155 * @exception UnknownEntityException if the user's account does not
156 * exist in the database.
157 * @exception DataBackendException if there is a problem accessing the
158 * storage.
159 */
160 void saveOnSessionUnbind(User user)
161 throws UnknownEntityException, DataBackendException;
162
163 /**
164 * Authenticate an User with the specified password. If authentication
165 * is successful the method returns nothing. If there are any problems,
166 * exception was thrown.
167 *
168 * @param user an User object to authenticate.
169 * @param password the user supplied password.
170 * @throws PasswordMismatchException if the supplied password was incorrect.
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 authenticate(User user, String password)
176 throws PasswordMismatchException, UnknownEntityException,
177 DataBackendException;
178
179 /**
180 * Creates new user account with specified attributes.
181 *
182 * @param user the object describing account to be created.
183 * @param initialPassword password for the new user
184 * @throws DataBackendException if there was an error accessing the data
185 * backend.
186 * @throws EntityExistsException if the user account already exists.
187 */
188 void createAccount(User user, String initialPassword)
189 throws EntityExistsException, DataBackendException;
190
191 /**
192 * Removes an user account from the system.
193 *
194 * @param user the object describing the account to be removed.
195 * @throws DataBackendException if there was an error accessing the data
196 * backend.
197 * @throws UnknownEntityException if the user account is not present.
198 */
199 void removeAccount(User user)
200 throws UnknownEntityException, DataBackendException;
201
202 /**
203 * Change the password for an User.
204 *
205 * @param user an User to change password for.
206 * @param oldPassword the current password suplied by the user.
207 * @param newPassword the current password requested by the user.
208 * @throws PasswordMismatchException if the supplied password was incorrect.
209 * @throws UnknownEntityException if the user's record does not
210 * exist in the database.
211 * @throws DataBackendException if there is a problem accessing the storage.
212 */
213 void changePassword(User user, String oldPassword,
214 String newPassword)
215 throws PasswordMismatchException, UnknownEntityException,
216 DataBackendException;
217
218 /**
219 * Forcibly sets new password for an User.
220 *
221 * This is supposed by the administrator to change the forgotten or
222 * compromised passwords. Certain implementatations of this feature
223 * would require administrative level access to the authenticating
224 * server / program.
225 *
226 * @param user an User to change password for.
227 * @param password the new password.
228 * @throws UnknownEntityException if the user's record does not
229 * exist in the database.
230 * @throws DataBackendException if there is a problem accessing the storage.
231 */
232 void forcePassword(User user, String password)
233 throws UnknownEntityException, DataBackendException;
234
235 /**
236 * Constructs an User object to represent an anonymous user of the
237 * application.
238 *
239 * @return An anonymous Turbine User.
240 * @throws UnknownEntityException
241 * if the anonymous User object couldn't be constructed.
242 */
243 <T extends User> T getAnonymousUser() throws UnknownEntityException;
244
245 /**
246 * Checks whether a passed user object matches the anonymous user pattern
247 * according to the configured user manager
248 *
249 * @param u a user object
250 *
251 * @return True if this is an anonymous user
252 *
253 */
254 boolean isAnonymousUser(User u);
255
256 /**
257 * Construct a blank User object.
258 *
259 * This method calls getUserClass, and then creates a new object using the
260 * default constructor.
261 *
262 * @return an object implementing User interface.
263 * @throws DataBackendException
264 * if the object could not be instantiated.
265 */
266 <T extends User> T getUserInstance() throws DataBackendException;
267
268 /**
269 * Construct a blank User object.
270 *
271 * This method calls getUserClass, and then creates a new object using the
272 * default constructor.
273 *
274 * @param userName
275 * The name of the user.
276 *
277 * @return an object implementing User interface.
278 * @throws DataBackendException
279 * if the object could not be instantiated.
280 */
281 <T extends User> T getUserInstance(String userName) throws DataBackendException;
282
283 /**
284 * Return a Class object representing the system's chosen implementation of
285 * of ACL interface for the given user
286 *
287 * @param user the user
288 * @return systems's chosen implementation of ACL interface.
289 * @throws UnknownEntityException
290 * if the implementation of ACL interface could not be
291 * determined, or does not exist.
292 */
293 <T extends AccessControlList> T getACL(User user) throws UnknownEntityException;
294 }