1 package org.apache.fulcrum.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 import java.io.Serializable;
22
23 import org.apache.fulcrum.security.acl.AccessControlList;
24 import org.apache.fulcrum.security.entity.User;
25 import org.apache.fulcrum.security.util.DataBackendException;
26 import org.apache.fulcrum.security.util.EntityExistsException;
27 import org.apache.fulcrum.security.util.PasswordMismatchException;
28 import org.apache.fulcrum.security.util.UnknownEntityException;
29 import org.apache.fulcrum.security.util.UserSet;
30
31 /**
32 * An UserManager performs {@link org.apache.fulcrum.security.entity.User}
33 * objects related tasks on behalf of the
34 * {@link org.apache.fulcrum.security.BaseSecurityService}.
35 *
36 * The responsibilities of this class include loading data of an user from the
37 * storage and putting them into the
38 * {@link org.apache.fulcrum.security.entity.User} objects, saving those data to
39 * the permanent storage, and authenticating users.
40 *
41 * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
42 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
43 * @version $Id$
44 */
45 public interface UserManager extends Serializable
46 {
47 /** Avalon role - used to id the component within the manager */
48 String ROLE = UserManager.class.getName();
49
50 /**
51 * Construct a blank User object.
52 *
53 * This method calls getUserClass, and then creates a new object using the
54 * default constructor.
55 *
56 * @param <T> User type
57 * @return an object implementing User interface.
58 * @throws DataBackendException
59 * if the object could not be instantiated.
60 */
61 <T extends User> T getUserInstance() throws DataBackendException;
62
63 /**
64 * Construct a blank User object.
65 *
66 * This method calls getUserClass, and then creates a new object using the
67 * default constructor.
68 *
69 * @param <T> User
70 * @param userName
71 * The name of the user.
72 *
73 * @return an object implementing User interface.
74 * @throws DataBackendException
75 * if the object could not be instantiated.
76 */
77 <T extends User> T getUserInstance(String userName) throws DataBackendException;
78
79 /**
80 * Determines if the <code>User</code> exists in the security system.
81 *
82 * @param user
83 * a <code>User</code> value
84 * @return true if the user exists in the system, false otherwise
85 * @throws DataBackendException
86 * when more than one user with the same name exists.
87 */
88 boolean checkExists(User user) throws DataBackendException;
89
90 /**
91 * Check whether a specified user's account exists.
92 *
93 * The login name is used for looking up the account.
94 *
95 * @param userName
96 * The name of the user to be checked.
97 * @return true if the specified account exists
98 * @throws DataBackendException
99 * if there was an error accessing the data backend.
100 */
101 boolean checkExists(String userName) throws DataBackendException;
102
103 /**
104 * Retrieve a user from persistent storage using username as the key.
105 *
106 * @param <T> User
107 * @param username
108 * the name of the user.
109 * @return an User object.
110 * @throws UnknownEntityException
111 * if the user's record does not exist in the database.
112 * @throws DataBackendException
113 * if there is a problem accessing the storage.
114 */
115 <T extends User> T getUser(String username) throws UnknownEntityException, DataBackendException;
116
117 /**
118 * Retrieve a user from persistent storage using the id as the key.
119 *
120 * @param <T> User
121 * @param id
122 * the id of the user.
123 * @return an User object.
124 * @throws UnknownEntityException
125 * if the user's record does not exist in the database.
126 * @throws DataBackendException
127 * if there is a problem accessing the storage.
128 */
129 <T extends User> T getUserById(Object id) throws UnknownEntityException, DataBackendException;
130
131 /**
132 * Retrieve a user from persistent storage using username as the key, and
133 * authenticate the user. The implementation may chose to authenticate to
134 * the server as the user whose data is being retrieved.
135 *
136 * @param <T> User
137 * @param username
138 * the name of the user.
139 * @param password
140 * the user supplied password.
141 * @return an User object.
142 * @throws PasswordMismatchException
143 * if the supplied password was incorrect.
144 * @throws UnknownEntityException
145 * if the user's record does not exist in the database.
146 * @throws DataBackendException
147 * if there is a problem accessing the storage.
148 */
149 <T extends User> T getUser(String username, String password) throws PasswordMismatchException, UnknownEntityException, DataBackendException;
150
151 /**
152 * Retrieves all users defined in the system.
153 *
154 * @param <T> User type
155 * @return the names of all users defined in the system.
156 * @throws DataBackendException
157 * if there was an error accessing the data backend.
158 */
159 <T extends User> UserSet<T> getAllUsers() throws DataBackendException;
160
161 /**
162 * Saves User's data in the permanent storage. The user account is required
163 * to exist in the storage.
164 *
165 * @param user
166 * the user object to save
167 * @throws UnknownEntityException
168 * if the user's account does not exist in the database.
169 * @throws DataBackendException
170 * if there is a problem accessing the storage.
171 */
172 void saveUser(User user) throws UnknownEntityException, DataBackendException;
173
174 /**
175 * Authenticate an User with the specified password. If authentication is
176 * successful the method returns nothing. If there are any problems,
177 * exception was thrown.
178 *
179 * @param user
180 * an User object to authenticate.
181 * @param password
182 * the user supplied password.
183 * @throws PasswordMismatchException
184 * if the supplied password was incorrect.
185 * @throws UnknownEntityException
186 * if the user's record does not exist in the database.
187 * @throws DataBackendException
188 * if there is a problem accessing the storage.
189 */
190 void authenticate(User user, String password) throws PasswordMismatchException, UnknownEntityException, DataBackendException;
191
192 /**
193 * Creates new user account with specified attributes.
194 *
195 * @param user
196 * the object describing account to be created.
197 * @param password
198 * The password to use for the object creation
199 *
200 * @return User the user added
201 *
202 * @throws DataBackendException
203 * if there was an error accessing the data backend.
204 * @throws EntityExistsException
205 * if the user account already exists.
206 */
207 <T extends User> T addUser(T user, String password) throws EntityExistsException, DataBackendException;
208
209 /**
210 * Removes an user account from the system.
211 *
212 * @param user
213 * the object describing the account to be removed.
214 * @throws DataBackendException
215 * if there was an error accessing the data backend.
216 * @throws UnknownEntityException
217 * if the user account is not present.
218 */
219 void removeUser(User user) throws UnknownEntityException, DataBackendException;
220
221 /**
222 * Change the password for an User.
223 *
224 * @param user
225 * an User to change password for.
226 * @param oldPassword
227 * the current password suplied by the user.
228 * @param newPassword
229 * the current password requested by the user.
230 * @throws PasswordMismatchException
231 * if the supplied password was incorrect.
232 * @throws UnknownEntityException
233 * if the user's record does not exist in the database.
234 * @throws DataBackendException
235 * if there is a problem accessing the storage.
236 */
237 void changePassword(User user, String oldPassword, String newPassword) throws PasswordMismatchException, UnknownEntityException,
238 DataBackendException;
239
240 /**
241 * Forcibly sets new password for an User.
242 *
243 * This is supposed by the administrator to change the forgotten or
244 * compromised passwords. Certain implementatations of this feature would
245 * require administrative level access to the authenticating server /
246 * program.
247 *
248 * @param user
249 * an User to change password for.
250 * @param password
251 * the new password.
252 * @throws UnknownEntityException
253 * if the user's record does not exist in the database.
254 * @throws DataBackendException
255 * if there is a problem accessing the storage.
256 */
257 void forcePassword(User user, String password) throws UnknownEntityException, DataBackendException;
258
259 /**
260 * Return a Class object representing the system's chosen implementation of
261 * of ACL interface.
262 *
263 * @param <T> AccessControlList
264 * @param user the user
265 * @return systems's chosen implementation of ACL interface.
266 * @throws UnknownEntityException
267 * if the implementation of ACL interface could not be
268 * determined, or does not exist.
269 */
270 <T extends AccessControlList> T getACL(User user) throws UnknownEntityException;
271 }