1 /*
2 * This software was designed and created by Jason Carroll.
3 * Copyright (c) 2002, 2003, 2004 Jason Carroll.
4 * The author can be reached at jcarroll@cowsultants.com
5 * ITracker website: http://www.cowsultants.com
6 * ITracker forums: http://www.cowsultants.com/phpBB/index.php
7 *
8 * This program is free software; you can redistribute it and/or modify
9 * it only under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2 of the License, or
11 * (at your option) any later version.
12 *
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
17 */
18
19 package org.itracker.services;
20
21 import org.itracker.PasswordException;
22 import org.itracker.UserException;
23 import org.itracker.model.*;
24 import org.itracker.services.exceptions.AuthenticatorException;
25 import org.springframework.security.core.userdetails.UserDetailsService;
26
27 import java.util.Collection;
28 import java.util.List;
29 import java.util.Map;
30 import java.util.Set;
31
32 public interface UserService extends UserDetailsService {
33
34 User getUser(Integer userId);
35
36 User getUserByLogin(String login);
37
38 String getUserPasswordByLogin(String login);
39
40 List<User> getAllUsers();
41
42 int getNumberUsers();
43
44 List<User> getActiveUsers();
45
46 List<User> getSuperUsers();
47
48 List<User> getPossibleOwners(Issue issue, Integer projectId, Integer userId);
49
50 User createUser(User user) throws UserException;
51
52 User updateUser(User user) throws UserException;
53
54 String generateUserPassword(User user) throws PasswordException;
55
56 UserPreferences updateUserPreferences(UserPreferences user) throws UserException;
57
58 void clearOwnedProjects(User user);
59
60 /**
61 * Finds all users assigned to a project having all of the given permissionTypes.
62 *
63 * @param projectID the project ID
64 * @param permissionTypes array of permission types
65 * @return users having the required permissions
66 */
67 List<User> findUsersForProjectByPermissionTypeList(Integer projectID, PermissionType[] permissionTypes);
68
69 /**
70 * This method will call local EJBs to find users with a specific permission.
71 * This method is used by the deafult authenticator to manage permissions locally.
72 * If a pluggable authenticator is implemented that stores permissions in an
73 * external system, calling this method may not have up to date information.
74 *
75 * @param projectId id of the project on which the returned users have permissions
76 * @param permissionType the type of permission to search for
77 * @return an array of UserModels containing the users with the permission
78 */
79
80 List<User> getUsersWithPermissionLocal(Integer projectId, PermissionType permissionType);
81
82 @Deprecated
83 List<User> getUsersWithPermissionLocal(Integer projectId, int permissionType);
84
85 /**
86 * This method will call local EJBs to find all permissions for a user.
87 * This method is used by the deafult authenticator to manage permissions locally.
88 * If a pluggable authenticator is implemented that stores permissions in an
89 * external system, calling this method may not have up to date information.
90 *
91 * @param user the user to find the permissions for
92 * @return an array of PermissionModels containing the user's permissions
93 */
94 List<Permission> getUserPermissionsLocal(User user);
95
96 /**
97 * Adds an additional set of permissions to a user in the database. This does not remove any existing
98 * permissions. Any duplication permissions will be ignored. Before updating the permissions, this
99 * method will call the pluggable authenticator to have the permission set augmented. This augmented
100 * set of permissions will then be used for the actual update.
101 *
102 * @param userId the userId, not login, of the user to add the permissions to
103 * @param newPermissions an array of PermissionModels that represent the new permissions to add to the user
104 * @return true if the operation was successful
105 */
106
107 boolean updateAuthenticator(Integer userId, List<Permission> newPermissions);
108
109 /**
110 * Resets all of the permissions for a user in the database. The new permissions for the user are contained in a
111 * HashMap object. The keys of this map MUST be in the format Perm<permission type>Prod<productId>. For example to add the
112 * VIEW_ALL permission to project 3, the key would be Perm7Prod3. The value of the key would be a Permission
113 * object. Before updating the permissions, this method will call the pluggable authenticator to have the permission
114 * set augmented. This augmented set of permissions will then be used for the actual update.
115 *
116 * @param userId the userId, not login, of the user to add the permissions to
117 * @param newPermissions a HashMap containing keys and Permission values as described in the method description.
118 * @return true if the operation was successful
119 * @see org.itracker.model.util.UserUtilities
120 */
121
122 boolean addUserPermissions(Integer userId, List<Permission> newPermissions);
123
124 /**
125 * Resets all of the permissions for a user in the database. The new permissions for the user are contained in a
126 * HashMap object. The keys of this map MUST be in the format Perm<permission type>Prod<productId>. For example to add the
127 * VIEW_ALL permission to project 3, the key would be Perm7Prod3. The value of the key would be a Permission
128 * object. Before updating the permissions, this method will call the pluggable authenticator to have the permission
129 * set augmented. This augmented set of permissions will then be used for the actual update.
130 *
131 * @param userId the userId, not login, of the user to add the permissions to
132 * @param newPermissions a HashMap containing keys and Permission values as described in the method description.
133 * @return true if the operation was successful
134 * @see org.itracker.model.util.UserUtilities
135 */
136
137 boolean setUserPermissions(Integer userId, List<Permission> newPermissions);
138
139 /**
140 * Resets all of the permissions for a user in the database. The new permissions for the user are contained in a
141 * HashMap object. The keys of this map MUST be in the format Perm<permission type>Prod<productId>. For example to add the
142 * VIEW_ALL permission to project 3, the key would be Perm7Prod3. The value of the key would be a Permission
143 * object. Before updating the permissions, this method will call the pluggable authenticator to have the permission
144 * set augmented. This augmented set of permissions will then be used for the actual update.
145 *
146 * @param userId the userId, not login, of the user to add the permissions to
147 * @param newPermissions a HashMap containing keys and Permission values as described in the method description.
148 * @return true if the operation was successful
149 * @see org.itracker.model.util.UserUtilities
150 */
151
152 boolean removeUserPermissions(Integer userId, List<Permission> newPermissions);
153
154 /**
155 * Returns an array of Permission objects for the requested userId.
156 *
157 * @param userId the userId, not the login, to find the permissions of
158 */
159
160 List<Permission> getPermissionsByUserId(Integer userId);
161
162 /**
163 * Returns a HashMap of all permissions a user has. The HashMap uses the projectId
164 * as the key values, and then contains a HashSet as the value of the key containing
165 * Integer objects of the permissions a user has.
166 * <p/>
167 * A special key of the Integer -1 may also be in the HashMap. This key is used
168 * to represent if the user is a super user, and in which case the user has all
169 * permissions be default.
170 * <p/>
171 * The value of this key would be a Boolen object with the value true
172 * if the user was a super user.
173 * <p/>
174 * This HashMap is usually not used directly, but in conjunction with the hasPermission
175 * methods in UserUtilities to determine if a user has a particular permission.
176 *
177 * @param user a User representing the user that the permissions should be obtained for
178 * @param reqSource the source of the request
179 * @return a Map of permission types by project ID
180 * @see org.itracker.model.util.UserUtilities#hasPermission
181 */
182 Map<Integer, Set<PermissionType>> getUsersMapOfProjectIdsAndSetOfPermissionTypes(User user, int reqSource);
183
184 /**
185 * This method will return a list of users with a specific permission, either explicitly, or
186 * by their role as a super user. This list is obtained calling a method in the pluggable
187 * authenticator, so the actual source of the data may not
188 * be the local datastore.
189 *
190 * @param projectId the project to find the permission for
191 * @param permission the permission to check for
192 * @return an array of Users that represent the users that have the permission
193 */
194 List<User> getUsersWithProjectPermission(Integer projectId, PermissionType permission);
195
196 @Deprecated
197 List<User> getUsersWithProjectPermission(Integer projectId, int permission);
198
199 /**
200 * This method will return a list of users with a specific permission, either explicitly, or
201 * by their role as a super user. This list is obtained calling a method in the pluggable
202 * authenticator, so the actual source of the data may not
203 * be the local datastore.
204 *
205 * @param projectId the project to find the permission for
206 * @param permission the permission to check for
207 * @param activeOnly only include users who are currently active
208 * @return an array of UserModels that represent the users that have the permission
209 */
210 @Deprecated
211 List<User> getUsersWithProjectPermission(Integer projectId, int permission, boolean activeOnly);
212
213 /**
214 * This method will return a list of users with the supplied permission, either explicitly, or
215 * by their role as a super user. This list is obtained calling a method in the pluggable
216 * authenticator, so the actual source of the data may not be the local datastore.
217 *
218 * @param projectId the project to find the permission for
219 * @param permissions the permissions that are checked against
220 * @param requireAll true if all the permissions in the array are required, false if only one is required
221 * @param activeOnly only include users who are currently active
222 * @return an array of UserModels that represent the users that have the permission
223 */
224 List<User> getUsersWithProjectPermission(Integer projectId, PermissionType[] permissions, boolean requireAll, boolean activeOnly);
225
226 @Deprecated
227 List<User> getUsersWithProjectPermission(Integer projectId, int[] permissions, boolean requireAll, boolean activeOnly);
228
229 /**
230 * This method will return a list of users with any of the supplied permission, either explicitly, or
231 * by their role as a super user. This list is obtained calling a method in the pluggable
232 * authenticator, so the actual source of the data may not
233 * be the local datastore.
234 *
235 * @param projectId the project to find the permission for
236 * @param permissions the permissions that are checked against
237 * @return an array of UserModels that represent the users that have the permission
238 */
239 List<User> getUsersWithAnyProjectPermission(Integer projectId, PermissionType[] permissions);
240
241 List<User> getUsersWithProjectPermission(Integer projectId, PermissionType permissionType, boolean activeOnly);
242
243 /**
244 * This method will return a list of users with any of the supplied permission, either explicitly, or
245 * by their role as a super user. This list is obtained calling a method in the pluggable
246 * authenticator, so the actual source of the data may not
247 * be the local datastore.
248 *
249 * @param projectId the project to find the permission for
250 * @param permissionTypes the permissions that are checked against
251 * @return an array of UserModels that represent the users that have the permission
252 */
253 @Deprecated
254 List<User> getUsersWithAnyProjectPermission(Integer projectId, int[] permissionTypes);
255
256 /**
257 * This method will return a list of users with any of the supplied permission, either explicitly, or
258 * by their role as a super user. This list is obtained calling a method in the pluggable
259 * authenticator, so the actual source of the data may not
260 * be the local datastore.
261 *
262 * @param projectId the project to find the permission for
263 * @param permissions the permissions that are checked against
264 * @param activeOnly only include users who are currently active
265 * @return an array of UserModels that represent the users that have the permission
266 */
267 List<User> getUsersWithAnyProjectPermission(Integer projectId, PermissionType[] permissions, boolean activeOnly);
268
269 @Deprecated
270 List<User> getUsersWithAnyProjectPermission(Integer projectId, int[] permissions, boolean activeOnly);
271
272 /**
273 * This method checks the login of a user, and returns the user if authentication was successful.
274 *
275 * @param login the login the user/client provided
276 * @param authentication the user's authentication information, if known
277 * @param authType the type of authentication information being provided
278 * @param reqSource the source from which the request was made (eg web, api)
279 * @return a User if the login is successful
280 * @throws AuthenticatorException an exception if the login is unsuccessful, or an error occurs
281 */
282 User checkLogin(String login, Object authentication, int authType, int reqSource) throws AuthenticatorException;
283
284 /**
285 * This method checks to see if the given user is allowed to self register.
286 *
287 * @param user a User object that contains the data the user submitted
288 * @param authentication the user's authentication information, if known
289 * @param authType the type of authentication information being provided
290 * @param reqSource the source from which the request was made (eg web, api)
291 * @return true if the user is allowed to register
292 * @throws AuthenticatorException an exception if an error occurs
293 */
294 boolean allowRegistration(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
295
296 /**
297 * This method checks to see if a new user profile can be created within ITracker
298 *
299 * @param user a User object that contains the data for the new user. If null,
300 * then the request is being made for an unknown future user. For example,
301 * the system may request this with an null user if it needs to know if the system
302 * should even present the option to create a new user
303 * @param authentication the user's authentication information, if known
304 * @param authType the type of authentication information being provided
305 * @param reqSource the source from which the request was made (eg web, api)
306 * @return a boolean indicating whether new user profile can be created through ITracker
307 * @throws AuthenticatorException an exception if an error occurs
308 */
309 boolean allowProfileCreation(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
310
311 /**
312 * This method checks to see if the given user's core user profile information
313 * can be updated locally.
314 *
315 * @param user a User object that contains the data the user submitted
316 * @param authentication the user's authentication information, if known
317 * @param authType the type of authentication information being provided
318 * @param reqSource the source from which the request was made (eg web, api)
319 * @return a boolean whether the user's core profile information can be updated
320 * @throws AuthenticatorException an exception if an error occurs
321 */
322 boolean allowProfileUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
323
324 /**
325 * This method checks to see if the given user's password can be updated locally.
326 *
327 * @param user a User object that contains the data the user submitted
328 * @param authentication the user's authentication information, if known
329 * @param authType the type of authentication information being provided
330 * @param reqSource the source from which the request was made (eg web, api)
331 * @return a boolean whether the user's core profile information can be updated
332 * @throws AuthenticatorException an exception if an error occurs
333 */
334 boolean allowPasswordUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
335
336 /**
337 * This method checks to see if the given user's permission information
338 * can be updated locally.
339 *
340 * @param user a User object that contains the data the user submitted
341 * @param authentication the user's authentication information, if known
342 * @param authType the type of authentication information being provided
343 * @param reqSource the source from which the request was made (eg web, api)
344 * @return a boolean whether the user's core profile information can be updated
345 * @throws AuthenticatorException an exception if an error occurs
346 */
347 boolean allowPermissionUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
348
349 /**
350 * This method checks to see if the given user's preference information
351 * can be updated locally.
352 *
353 * @param user a User object that contains the data the user submitted
354 * @param authentication the user's authentication information, if known
355 * @param authType the type of authentication information being provided
356 * @param reqSource the source from which the request was made (eg web, api)
357 * @return a boolean whether the user's core profile information can be updated
358 * @throws AuthenticatorException an exception if an error occurs
359 */
360 boolean allowPreferenceUpdates(User user, Object authentication, int authType, int reqSource) throws AuthenticatorException;
361
362
363
364 }