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