##### Coverage Report - org.apache.turbine.services.security.SecurityService

Classes in this File | Line Coverage | Branch Coverage | Complexity
SecurityService |
N/A | N/A
N/A | N/A
| 1.0;1

1 |  |
     package org.apache.turbine.services.security;
2 |  |
3 |  |
4 |  |
     /*
5 |  |
      * Licensed to the Apache Software Foundation (ASF) under one
6 |  |
      * or more contributor license agreements.  See the NOTICE file
7 |  |
      * distributed with this work for additional information
8 |  |
      * regarding copyright ownership.  The ASF licenses this file
9 |  |
      * to you under the Apache License, Version 2.0 (the
10 |  |
      * "License"); you may not use this file except in compliance
11 |  |
      * with the License.  You may obtain a copy of the License at
12 |  |
      *
13 |  |
      *   http://www.apache.org/licenses/LICENSE-2.0
14 |  |
      *
15 |  |
      * Unless required by applicable law or agreed to in writing,
16 |  |
      * software distributed under the License is distributed on an
17 |  |
      * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 |  |
      * KIND, either express or implied.  See the License for the
19 |  |
      * specific language governing permissions and limitations
20 |  |
      * under the License.
21 |  |
      */
22 |  |
23 |  |
24 |  |
     import java.util.List;
25 |  |
     import java.util.Map;
26 |  |
27 |  |
     import org.apache.turbine.om.security.Group;
28 |  |
     import org.apache.turbine.om.security.Permission;
29 |  |
     import org.apache.turbine.om.security.Role;
30 |  |
     import org.apache.turbine.om.security.TurbineGroup;
31 |  |
     import org.apache.turbine.om.security.TurbinePermission;
32 |  |
     import org.apache.turbine.om.security.TurbineRole;
33 |  |
     import org.apache.turbine.om.security.TurbineUser;
34 |  |
     import org.apache.turbine.om.security.User;
35 |  |
     import org.apache.turbine.services.Service;
36 |  |
     import org.apache.turbine.services.security.passive.PassiveUserManager;
37 |  |
     import org.apache.turbine.util.security.AccessControlList;
38 |  |
     import org.apache.turbine.util.security.DataBackendException;
39 |  |
     import org.apache.turbine.util.security.EntityExistsException;
40 |  |
     import org.apache.turbine.util.security.GroupSet;
41 |  |
     import org.apache.turbine.util.security.PasswordMismatchException;
42 |  |
     import org.apache.turbine.util.security.PermissionSet;
43 |  |
     import org.apache.turbine.util.security.RoleSet;
44 |  |
     import org.apache.turbine.util.security.TurbineAccessControlList;
45 |  |
     import org.apache.turbine.util.security.UnknownEntityException;
46 |  |
47 |  |
     /**
48 |  |
      * The Security Service manages Users, Groups Roles and Permissions in the
49 |  |
      * system.
50 |  |
      *
51 |  |
      * The task performed by the security service include creation and removal of
52 |  |
      * accounts, groups, roles, and permissions; assigning users roles in groups;
53 |  |
      * assigning roles specific permissions and construction of objects
54 |  |
      * representing these logical entities.
55 |  |
      *
56 |  |
      * <p> Because of pluggable nature of the Services, it is possible to create
57 |  |
      * multiple implementations of SecurityService, for example employing database
58 |  |
      * and directory server as the data backend.<br>
59 |  |
      *
60 |  |
      * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
61 |  |
      * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
62 |  |
      * @author <a href="mailto:marco@intermeta.de">Marco Kn&uuml;ttel</a>
63 |  |
      * @version $Id: SecurityService.java 1096130 2011-04-23 10:37:19Z ludwig $
64 |  |
      */
65 |  |
     public interface SecurityService
66 |  |
             extends Service
67 |  |
     {
68 |  |
         /** The name of the service */
69 |  |
         String SERVICE_NAME = "SecurityService";
70 |  |
71 |  |
         /**
72 |  |
          * the key within services's properties for user implementation
73 |  |
          * classname (user.class)
74 |  |
          */
75 |  |
         String USER_CLASS_KEY = "user.class";
76 |  |
77 |  |
         /**
78 |  |
          * the default implementation of User interface
79 |  |
          * (org.apache.turbine.om.security.TurbineUser)
80 |  |
          */
81 |  |
         String USER_CLASS_DEFAULT
82 |  |
                 = TurbineUser.class.getName();
83 |  |
84 |  |
         /**
85 |  |
          * The key within services' properties for the GROUP
86 |  |
          * implementation classname (group.class)
87 |  |
          */
88 |  |
         String GROUP_CLASS_KEY = "group.class";
89 |  |
90 |  |
         /**
91 |  |
          * The default implementation of the Group interface
92 |  |
          * (org.apache.turbine.om.security.TurbineGroup)
93 |  |
          */
94 |  |
         String GROUP_CLASS_DEFAULT
95 |  |
                 = TurbineGroup.class.getName();
96 |  |
97 |  |
         /**
98 |  |
          * The key within services' properties for the PERMISSION
99 |  |
          * implementation classname (permission.class)
100 |  |
          */
101 |  |
         String PERMISSION_CLASS_KEY = "permission.class";
102 |  |
103 |  |
         /**
104 |  |
          * The default implementation of the Permissions interface
105 |  |
          * (org.apache.turbine.om.security.TurbinePermission)
106 |  |
          */
107 |  |
         String PERMISSION_CLASS_DEFAULT
108 |  |
                 = TurbinePermission.class.getName();
109 |  |
110 |  |
         /**
111 |  |
          * The key within services' properties for the ROLE
112 |  |
          * implementation classname (role.class)
113 |  |
          */
114 |  |
         String ROLE_CLASS_KEY = "role.class";
115 |  |
116 |  |
         /**
117 |  |
          * The default implementation of the Role Interface
118 |  |
          * (org.apache.turbine.om.security.TurbineRole)
119 |  |
          */
120 |  |
         String ROLE_CLASS_DEFAULT
121 |  |
                 = TurbineRole.class.getName();
122 |  |
123 |  |
         /**
124 |  |
          * The key within services' properties for the
125 |  |
          * ACL implementation classname (acl.class)
126 |  |
          */
127 |  |
         String ACL_CLASS_KEY = "acl.class";
128 |  |
129 |  |
         /**
130 |  |
          * The default implementation of the Acl Interface
131 |  |
          * (org.apache.turbine.util.security.TurbineAccessControlList)
132 |  |
          */
133 |  |
         String ACL_CLASS_DEFAULT
134 |  |
                 = TurbineAccessControlList.class.getName();
135 |  |
136 |  |
         /**
137 |  |
          * the key within services's properties for user implementation
138 |  |
          * classname (user.manager)
139 |  |
          */
140 |  |
         String USER_MANAGER_KEY = "user.manager";
141 |  |
142 |  |
         /**
143 |  |
          * the default implementation of UserManager interface
144 |  |
          * (org.apache.turbine.services.security.passive.PassiveUserManager)
145 |  |
          */
146 |  |
         String USER_MANAGER_DEFAULT
147 |  |
                 = PassiveUserManager.class.getName();
148 |  |
149 |  |
         /**
150 |  |
          * the key within services's properties for secure passwords flag
151 |  |
          * (secure.passwords)
152 |  |
          */
153 |  |
         String SECURE_PASSWORDS_KEY = "secure.passwords";
154 |  |
155 |  |
         /** the value of secure passwords flag (false) */
156 |  |
         String SECURE_PASSWORDS_DEFAULT = "false";
157 |  |
158 |  |
         /**
159 |  |
          * the key within services's properties for secure passwords algorithm
160 |  |
          * (secure.passwords.algorithm)
161 |  |
          */
162 |  |
         String SECURE_PASSWORDS_ALGORITHM_KEY
163 |  |
                 = "secure.passwords.algorithm";
164 |  |
165 |  |
         /** the default algorithm for password encryption (SHA) */
166 |  |
         String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
167 |  |
168 |  |
         /*-----------------------------------------------------------------------
169 |  |
           Management of User objects
170 |  |
           -----------------------------------------------------------------------*/
171 |  |
172 |  |
         /**
173 |  |
          * Returns the Class object for the implementation of User interface
174 |  |
          * used by the system.
175 |  |
          *
176 |  |
          * @return the implementation of User interface used by the system.
177 |  |
          * @throws UnknownEntityException if the system's implementation of User
178 |  |
          *         interface could not be determined.
179 |  |
          */
180 |  |
         Class getUserClass()
181 |  |
                 throws UnknownEntityException;
182 |  |
183 |  |
         /**
184 |  |
          * Construct a blank User object.
185 |  |
          *
186 |  |
          * This method calls getUserClass, and then creates a new object using
187 |  |
          * the default constructor.
188 |  |
          *
189 |  |
          * @return an object implementing User interface.
190 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
191 |  |
          */
192 |  |
         User getUserInstance()
193 |  |
                 throws UnknownEntityException;
194 |  |
195 |  |
         /**
196 |  |
          * Construct a blank User object.
197 |  |
          *
198 |  |
          * This method calls getUserClass, and then creates a new object using
199 |  |
          * the default constructor.
200 |  |
          *
201 |  |
          * @param userName The name of the user.
202 |  |
          *
203 |  |
          * @return an object implementing User interface.
204 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
205 |  |
          */
206 |  |
         User getUserInstance(String userName)
207 |  |
                 throws UnknownEntityException;
208 |  |
209 |  |
         /**
210 |  |
          * Returns the Class object for the implementation of Group interface
211 |  |
          * used by the system.
212 |  |
          *
213 |  |
          * @return the implementation of Group interface used by the system.
214 |  |
          * @throws UnknownEntityException if the system's implementation of Group
215 |  |
          *         interface could not be determined.
216 |  |
          */
217 |  |
         Class getGroupClass()
218 |  |
                 throws UnknownEntityException;
219 |  |
220 |  |
         /**
221 |  |
          * Construct a blank Group object.
222 |  |
          *
223 |  |
          * This method calls getGroupClass, and then creates a new object using
224 |  |
          * the default constructor.
225 |  |
          *
226 |  |
          * @return an object implementing Group interface.
227 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
228 |  |
          */
229 |  |
         Group getGroupInstance()
230 |  |
                 throws UnknownEntityException;
231 |  |
232 |  |
         /**
233 |  |
          * Construct a blank Group object.
234 |  |
          *
235 |  |
          * This method calls getGroupClass, and then creates a new object using
236 |  |
          * the default constructor.
237 |  |
          *
238 |  |
          * @param groupName The name of the Group
239 |  |
          *
240 |  |
          * @return an object implementing Group interface.
241 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
242 |  |
          */
243 |  |
         Group getGroupInstance(String groupName)
244 |  |
                 throws UnknownEntityException;
245 |  |
246 |  |
         /**
247 |  |
          * Returns the Class object for the implementation of Permission interface
248 |  |
          * used by the system.
249 |  |
          *
250 |  |
          * @return the implementation of Permission interface used by the system.
251 |  |
          * @throws UnknownEntityException if the system's implementation of Permission
252 |  |
          *         interface could not be determined.
253 |  |
          */
254 |  |
         Class getPermissionClass()
255 |  |
                 throws UnknownEntityException;
256 |  |
257 |  |
         /**
258 |  |
          * Construct a blank Permission object.
259 |  |
          *
260 |  |
          * This method calls getPermissionClass, and then creates a new object using
261 |  |
          * the default constructor.
262 |  |
          *
263 |  |
          * @return an object implementing Permission interface.
264 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
265 |  |
          */
266 |  |
         Permission getPermissionInstance()
267 |  |
                 throws UnknownEntityException;
268 |  |
269 |  |
         /**
270 |  |
          * Construct a blank Permission object.
271 |  |
          *
272 |  |
          * This method calls getPermissionClass, and then creates a new object using
273 |  |
          * the default constructor.
274 |  |
          *
275 |  |
          * @param permName The name of the Permission
276 |  |
          *
277 |  |
          * @return an object implementing Permission interface.
278 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
279 |  |
          */
280 |  |
         Permission getPermissionInstance(String permName)
281 |  |
                 throws UnknownEntityException;
282 |  |
283 |  |
         /**
284 |  |
          * Returns the Class object for the implementation of Role interface
285 |  |
          * used by the system.
286 |  |
          *
287 |  |
          * @return the implementation of Role interface used by the system.
288 |  |
          * @throws UnknownEntityException if the system's implementation of Role
289 |  |
          *         interface could not be determined.
290 |  |
          */
291 |  |
         Class getRoleClass()
292 |  |
                 throws UnknownEntityException;
293 |  |
294 |  |
         /**
295 |  |
          * Construct a blank Role object.
296 |  |
          *
297 |  |
          * This method calls getRoleClass, and then creates a new object using
298 |  |
          * the default constructor.
299 |  |
          *
300 |  |
          * @return an object implementing Role interface.
301 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
302 |  |
          */
303 |  |
         Role getRoleInstance()
304 |  |
                 throws UnknownEntityException;
305 |  |
306 |  |
         /**
307 |  |
          * Construct a blank Role object.
308 |  |
          *
309 |  |
          * This method calls getRoleClass, and then creates a new object using
310 |  |
          * the default constructor.
311 |  |
          *
312 |  |
          * @param roleName The name of the Role
313 |  |
          *
314 |  |
          * @return an object implementing Role interface.
315 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
316 |  |
          */
317 |  |
         Role getRoleInstance(String roleName)
318 |  |
                 throws UnknownEntityException;
319 |  |
320 |  |
         /**
321 |  |
          * Returns the Class object for the implementation of AccessControlList interface
322 |  |
          * used by the system.
323 |  |
          *
324 |  |
          * @return the implementation of AccessControlList interface used by the system.
325 |  |
          * @throws UnknownEntityException if the system's implementation of AccessControlList
326 |  |
          *         interface could not be determined.
327 |  |
          */
328 |  |
         Class getAclClass()
329 |  |
                 throws UnknownEntityException;
330 |  |
331 |  |
         /**
332 |  |
          * Construct a new ACL object.
333 |  |
          *
334 |  |
          * This constructs a new ACL object from the configured class and
335 |  |
          * initializes it with the supplied roles and permissions.
336 |  |
          *
337 |  |
          * @param roles The roles that this ACL should contain
338 |  |
          * @param permissions The permissions for this ACL
339 |  |
          *
340 |  |
          * @return an object implementing ACL interface.
341 |  |
          * @throws UnknownEntityException if the object could not be instantiated.
342 |  |
          */
343 |  |
         AccessControlList getAclInstance(Map roles, Map permissions)
344 |  |
                 throws UnknownEntityException;
345 |  |
346 |  |
         /**
347 |  |
          * Returns the configured UserManager.
348 |  |
          *
349 |  |
          * @return An UserManager object
350 |  |
          */
351 |  |
         UserManager getUserManager();
352 |  |
353 |  |
         /**
354 |  |
          * Configure a new user Manager.
355 |  |
          *
356 |  |
          * @param userManager An UserManager object
357 |  |
          */
358 |  |
         void setUserManager(UserManager userManager);
359 |  |
360 |  |
         /**
361 |  |
          * Check whether a specified user's account exists.
362 |  |
          *
363 |  |
          * The login name is used for looking up the account.
364 |  |
          *
365 |  |
          * @param userName The user to be checked.
366 |  |
          * @return true if the specified account exists
367 |  |
          * @throws DataBackendException if there was an error accessing the data
368 |  |
          *         backend.
369 |  |
          */
370 |  |
         boolean accountExists(String userName)
371 |  |
                 throws DataBackendException;
372 |  |
373 |  |
         /**
374 |  |
          * Check whether a specified user's account exists.
375 |  |
          * An User object is used for looking up the account.
376 |  |
          *
377 |  |
          * @param user The user object to be checked.
378 |  |
          * @return true if the specified account exists
379 |  |
          * @throws DataBackendException if there was an error accessing the data
380 |  |
          *         backend.
381 |  |
          */
382 |  |
         boolean accountExists(User user)
383 |  |
                 throws DataBackendException;
384 |  |
385 |  |
         /**
386 |  |
          * Authenticates an user, and constructs an User object to represent
387 |  |
          * him/her.
388 |  |
          *
389 |  |
          * @param username The user name.
390 |  |
          * @param password The user password.
391 |  |
          * @return An authenticated Turbine User.
392 |  |
          * @throws DataBackendException if there was an error accessing the data
393 |  |
          *         backend.
394 |  |
          * @throws UnknownEntityException if user account is not present.
395 |  |
          * @throws PasswordMismatchException if the supplied password was incorrect.
396 |  |
          */
397 |  |
         User getAuthenticatedUser(String username, String password)
398 |  |
                 throws DataBackendException, UnknownEntityException,
399 |  |
                 PasswordMismatchException;
400 |  |
401 |  |
         /**
402 |  |
          * Constructs an User object to represent a registered user of the
403 |  |
          * application.
404 |  |
          *
405 |  |
          * @param username The user name.
406 |  |
          * @return A Turbine User.
407 |  |
          * @throws DataBackendException if there was an error accessing the data
408 |  |
          *         backend.
409 |  |
          * @throws UnknownEntityException if user account is not present.
410 |  |
          */
411 |  |
         User getUser(String username)
412 |  |
                 throws DataBackendException, UnknownEntityException;
413 |  |
414 |  |
         /**
415 |  |
          * Retrieve a set of users that meet the specified criteria.
416 |  |
          *
417 |  |
          * As the keys for the criteria, you should use the constants that
418 |  |
          * are defined in {@link User} interface, plus the names
419 |  |
          * of the custom attributes you added to your user representation
420 |  |
          * in the data storage. Use verbatim names of the attributes -
421 |  |
          * without table name prefix in case of Torque implementation.
422 |  |
          *
423 |  |
          * @param criteria The criteria of selection.
424 |  |
          * @return a List of users meeting the criteria.
425 |  |
          * @throws DataBackendException if there is a problem accessing the
426 |  |
          *         storage.
427 |  |
          */
428 |  |
         List getUserList(Object criteria)
429 |  |
                 throws DataBackendException;
430 |  |
431 |  |
         /**
432 |  |
          * Constructs an User object to represent an anonymous user of the
433 |  |
          * application.
434 |  |
          *
435 |  |
          * @return An anonymous Turbine User.
436 |  |
          * @throws UnknownEntityException if the anonymous User object couldn't be
437 |  |
          *         constructed.
438 |  |
          */
439 |  |
         User getAnonymousUser()
440 |  |
                 throws UnknownEntityException;
441 |  |
442 |  |
         /**
443 |  |
          * Checks whether a passed user object matches the anonymous user pattern
444 |  |
          * according to the configured user manager
445 |  |
          *
446 |  |
          * @param An user object
447 |  |
          *
448 |  |
          * @return True if this is an anonymous user
449 |  |
          *
450 |  |
          */
451 |  |
         boolean isAnonymousUser(User u);
452 |  |
453 |  |
         /**
454 |  |
          * Saves User's data in the permanent storage. The user account is required
455 |  |
          * to exist in the storage.
456 |  |
          *
457 |  |
          * @param user the user object to save
458 |  |
          * @throws UnknownEntityException if the user's account does not
459 |  |
          *         exist in the database.
460 |  |
          * @throws DataBackendException if there is a problem accessing the storage.
461 |  |
          */
462 |  |
         void saveUser(User user)
463 |  |
                 throws UnknownEntityException, DataBackendException;
464 |  |
465 |  |
         /**
466 |  |
          * Saves User data when the session is unbound. The user account is required
467 |  |
          * to exist in the storage.
468 |  |
          *
469 |  |
          * LastLogin, AccessCounter, persistent pull tools, and any data stored
470 |  |
          * in the permData hashtable that is not mapped to a column will be saved.
471 |  |
          *
472 |  |
          * @exception UnknownEntityException if the user's account does not
473 |  |
          *            exist in the database.
474 |  |
          * @exception DataBackendException if there is a problem accessing the
475 |  |
          *            storage.
476 |  |
          */
477 |  |
         void saveOnSessionUnbind(User user)
478 |  |
                 throws UnknownEntityException, DataBackendException;
479 |  |
480 |  |
         /*-----------------------------------------------------------------------
481 |  |
           Account management
482 |  |
           -----------------------------------------------------------------------*/
483 |  |
484 |  |
         /**
485 |  |
          * Creates new user account with specified attributes.
486 |  |
          *
487 |  |
          * @param user the object describing account to be created.
488 |  |
          * @param password The password to use.
489 |  |
          * @throws DataBackendException if there was an error accessing the data
490 |  |
          *         backend.
491 |  |
          * @throws EntityExistsException if the user account already exists.
492 |  |
          */
493 |  |
         void addUser(User user, String password)
494 |  |
                 throws DataBackendException, EntityExistsException;
495 |  |
496 |  |
         /**
497 |  |
          * Removes an user account from the system.
498 |  |
          *
499 |  |
          * @param user the object describing the account to be removed.
500 |  |
          * @throws DataBackendException if there was an error accessing the data
501 |  |
          *         backend.
502 |  |
          * @throws UnknownEntityException if the user account is not present.
503 |  |
          */
504 |  |
         void removeUser(User user)
505 |  |
                 throws DataBackendException, UnknownEntityException;
506 |  |
507 |  |
         /*-----------------------------------------------------------------------
508 |  |
           Management of passwords
509 |  |
           -----------------------------------------------------------------------*/
510 |  |
511 |  |
         /**
512 |  |
          * This method provides client-side encryption mechanism for passwords.
513 |  |
          *
514 |  |
          * This is an utility method that is used by other classes to maintain
515 |  |
          * a consistent approach to encrypting password. The behavior of the
516 |  |
          * method can be configured in service's properties.
517 |  |
          *
518 |  |
          * @param password the password to process
519 |  |
          * @return processed password
520 |  |
          */
521 |  |
         String encryptPassword(String password);
522 |  |
523 |  |
         /**
524 |  |
          * This method provides client-side encryption mechanism for passwords.
525 |  |
          *
526 |  |
          * This is an utility method that is used by other classes to maintain
527 |  |
          * a consistent approach to encrypting password. The behavior of the
528 |  |
          * method can be configured in service's properties.
529 |  |
          *
530 |  |
          * Algorithms that must supply a salt for encryption
531 |  |
          * can use this method to provide it.
532 |  |
          *
533 |  |
          * @param password the password to process
534 |  |
          * @param salt Salt parameter for some crypto algorithms
535 |  |
          *
536 |  |
          * @return processed password
537 |  |
          */
538 |  |
         String encryptPassword(String password, String salt);
539 |  |
540 |  |
         /**
541 |  |
          * Checks if a supplied password matches the encrypted password
542 |  |
          * when using the current encryption algorithm
543 |  |
          *
544 |  |
          * @param checkpw      The clear text password supplied by the user
545 |  |
          * @param encpw        The current, encrypted password
546 |  |
          *
547 |  |
          * @return true if the password matches, else false
548 |  |
          *
549 |  |
          */
550 |  |
         boolean checkPassword(String checkpw, String encpw);
551 |  |
552 |  |
         /**
553 |  |
          * Change the password for an User.
554 |  |
          *
555 |  |
          * @param user an User to change password for.
556 |  |
          * @param oldPassword the current password supplied by the user.
557 |  |
          * @param newPassword the current password requested by the user.
558 |  |
          * @exception PasswordMismatchException if the supplied password was
559 |  |
          *            incorrect.
560 |  |
          * @exception UnknownEntityException if the user's record does not
561 |  |
          *            exist in the database.
562 |  |
          * @exception DataBackendException if there is a problem accessing the
563 |  |
          *            storage.
564 |  |
          */
565 |  |
         void changePassword(User user, String oldPassword,
566 |  |
                             String newPassword)
567 |  |
                 throws PasswordMismatchException, UnknownEntityException,
568 |  |
                 DataBackendException;
569 |  |
570 |  |
         /**
571 |  |
          * Forcibly sets new password for an User.
572 |  |
          *
573 |  |
          * This is supposed by the administrator to change the forgotten or
574 |  |
          * compromised passwords. Certain implementatations of this feature
575 |  |
          * would require administrative level access to the authenticating
576 |  |
          * server / program.
577 |  |
          *
578 |  |
          * @param user an User to change password for.
579 |  |
          * @param password the new password.
580 |  |
          * @exception UnknownEntityException if the user's record does not
581 |  |
          *            exist in the database.
582 |  |
          * @exception DataBackendException if there is a problem accessing the
583 |  |
          *            storage.
584 |  |
          */
585 |  |
         void forcePassword(User user, String password)
586 |  |
                 throws UnknownEntityException, DataBackendException;
587 |  |
588 |  |
         /*-----------------------------------------------------------------------
589 |  |
           Retrieval of security information
590 |  |
           -----------------------------------------------------------------------*/
591 |  |
592 |  |
         /**
593 |  |
          * Constructs an AccessControlList for a specific user.
594 |  |
          *
595 |  |
          * @param user the user for whom the AccessControlList are to be retrieved
596 |  |
          * @return A new AccessControlList object.
597 |  |
          * @throws DataBackendException if there was an error accessing the data backend.
598 |  |
          * @throws UnknownEntityException if user account is not present.
599 |  |
          */
600 |  |
         AccessControlList getACL(User user)
601 |  |
                 throws DataBackendException, UnknownEntityException;
602 |  |
603 |  |
         /**
604 |  |
          * Retrieves all permissions associated with a role.
605 |  |
          *
606 |  |
          * @param role the role name, for which the permissions are to be retrieved.
607 |  |
          * @return the permissions associated with the role
608 |  |
          * @throws DataBackendException if there was an error accessing the data
609 |  |
          *         backend.
610 |  |
          * @throws UnknownEntityException if the role is not present.
611 |  |
          */
612 |  |
         PermissionSet getPermissions(Role role)
613 |  |
                 throws DataBackendException, UnknownEntityException;
614 |  |
615 |  |
         /*-----------------------------------------------------------------------
616 |  |
           Manipulation of security information
617 |  |
           -----------------------------------------------------------------------*/
618 |  |
619 |  |
         /**
620 |  |
          * Grant an User a Role in a Group.
621 |  |
          *
622 |  |
          * @param user the user.
623 |  |
          * @param group the group.
624 |  |
          * @param role the role.
625 |  |
          * @throws DataBackendException if there was an error accessing the data
626 |  |
          *         backend.
627 |  |
          * @throws UnknownEntityException if user account, group or role is not
628 |  |
          *         present.
629 |  |
          */
630 |  |
         void grant(User user, Group group, Role role)
631 |  |
                 throws DataBackendException, UnknownEntityException;
632 |  |
633 |  |
         /**
634 |  |
          * Revoke a Role in a Group from an User.
635 |  |
          *
636 |  |
          * @param user the user.
637 |  |
          * @param group the group.
638 |  |
          * @param role the role.
639 |  |
          * @throws DataBackendException if there was an error accessing the data
640 |  |
          *         backend.
641 |  |
          * @throws UnknownEntityException if user account, group or role is not
642 |  |
          *         present.
643 |  |
          */
644 |  |
         void revoke(User user, Group group, Role role)
645 |  |
                 throws DataBackendException, UnknownEntityException;
646 |  |
647 |  |
         /**
648 |  |
          * Revokes all roles from an User.
649 |  |
          *
650 |  |
          * This method is used when deleting an account.
651 |  |
          *
652 |  |
          * @param user the User.
653 |  |
          * @throws DataBackendException if there was an error accessing the data
654 |  |
          *         backend.
655 |  |
          * @throws UnknownEntityException if the account is not present.
656 |  |
          */
657 |  |
         void revokeAll(User user)
658 |  |
                 throws DataBackendException, UnknownEntityException;
659 |  |
660 |  |
         /**
661 |  |
          * Grants a Role a Permission
662 |  |
          *
663 |  |
          * @param role the Role.
664 |  |
          * @param permission the Permission.
665 |  |
          * @throws DataBackendException if there was an error accessing the data
666 |  |
          *         backend.
667 |  |
          * @throws UnknownEntityException if role or permission is not present.
668 |  |
          */
669 |  |
         void grant(Role role, Permission permission)
670 |  |
                 throws DataBackendException, UnknownEntityException;
671 |  |
672 |  |
         /**
673 |  |
          * Revokes a Permission from a Role.
674 |  |
          *
675 |  |
          * @param role the Role.
676 |  |
          * @param permission the Permission.
677 |  |
          * @throws DataBackendException if there was an error accessing the data
678 |  |
          *         backend.
679 |  |
          * @throws UnknownEntityException if role or permission is not present.
680 |  |
          */
681 |  |
         void revoke(Role role, Permission permission)
682 |  |
                 throws DataBackendException, UnknownEntityException;
683 |  |
684 |  |
         /**
685 |  |
          * Revokes all permissions from a Role.
686 |  |
          *
687 |  |
          * This method is user when deleting a Role.
688 |  |
          *
689 |  |
          * @param role the Role
690 |  |
          * @throws DataBackendException if there was an error accessing the data
691 |  |
          *         backend.
692 |  |
          * @throws  UnknownEntityException if the Role is not present.
693 |  |
          */
694 |  |
         void revokeAll(Role role)
695 |  |
                 throws DataBackendException, UnknownEntityException;
696 |  |
697 |  |
         /*-----------------------------------------------------------------------
698 |  |
           Retrieval & storage of SecurityObjects
699 |  |
           -----------------------------------------------------------------------*/
700 |  |
701 |  |
         /**
702 |  |
          * Provides a reference to the Group object that represents the
703 |  |
          * <a href="#global">global group</a>.
704 |  |
          *
705 |  |
          * @return A Group object that represents the global group.
706 |  |
          */
707 |  |
         Group getGlobalGroup();
708 |  |
709 |  |
         /**
710 |  |
          * Retrieve a Group object with specified name.
711 |  |
          *
712 |  |
          * @param name the name of the Group.
713 |  |
          * @return an object representing the Group with specified name.
714 |  |
          * @throws DataBackendException if there was an error accessing the data
715 |  |
          *         backend.
716 |  |
          * @throws UnknownEntityException if the group does not exist.
717 |  |
          */
718 |  |
         Group getGroupByName(String name)
719 |  |
                 throws DataBackendException, UnknownEntityException;
720 |  |
721 |  |
         /**
722 |  |
          * Retrieve a Group object with specified Id.
723 |  |
          *
724 |  |
          * @param name the name of the Group.
725 |  |
          *
726 |  |
          * @return an object representing the Group with specified name.
727 |  |
          *
728 |  |
          * @exception UnknownEntityException if the permission does not
729 |  |
          *            exist in the database.
730 |  |
          * @exception DataBackendException if there is a problem accessing the
731 |  |
          *            storage.
732 |  |
          */
733 |  |
         Group getGroupById(int id)
734 |  |
                 throws DataBackendException,
735 |  |
                        UnknownEntityException;
736 |  |
737 |  |
         /**
738 |  |
          * Retrieve a Role object with specified name.
739 |  |
          *
740 |  |
          * @param name the name of the Role.
741 |  |
          * @return an object representing the Role with specified name.
742 |  |
          * @throws DataBackendException if there was an error accessing the data
743 |  |
          *         backend.
744 |  |
          * @throws UnknownEntityException if the role does not exist.
745 |  |
          */
746 |  |
         Role getRoleByName(String name)
747 |  |
                 throws DataBackendException, UnknownEntityException;
748 |  |
749 |  |
         /**
750 |  |
          * Retrieve a Role object with specified Id.
751 |  |
          *
752 |  |
          * @param name the name of the Role.
753 |  |
          *
754 |  |
          * @return an object representing the Role with specified name.
755 |  |
          *
756 |  |
          * @exception UnknownEntityException if the permission does not
757 |  |
          *            exist in the database.
758 |  |
          * @exception DataBackendException if there is a problem accessing the
759 |  |
          *            storage.
760 |  |
          */
761 |  |
         Role getRoleById(int id)
762 |  |
                 throws DataBackendException,
763 |  |
                        UnknownEntityException;
764 |  |
765 |  |
         /**
766 |  |
          * Retrieve a Permission object with specified name.
767 |  |
          *
768 |  |
          * @param name the name of the Permission.
769 |  |
          * @return an object representing the Permission with specified name.
770 |  |
          * @throws DataBackendException if there was an error accessing the data
771 |  |
          *         backend.
772 |  |
          * @throws UnknownEntityException if the permission does not exist.
773 |  |
          */
774 |  |
         Permission getPermissionByName(String name)
775 |  |
                 throws DataBackendException, UnknownEntityException;
776 |  |
777 |  |
         /**
778 |  |
          * Retrieve a Permission object with specified Id.
779 |  |
          *
780 |  |
          * @param name the name of the Permission.
781 |  |
          *
782 |  |
          * @return an object representing the Permission with specified name.
783 |  |
          *
784 |  |
          * @exception UnknownEntityException if the permission does not
785 |  |
          *            exist in the database.
786 |  |
          * @exception DataBackendException if there is a problem accessing the
787 |  |
          *            storage.
788 |  |
          */
789 |  |
         Permission getPermissionById(int id)
790 |  |
                 throws DataBackendException,
791 |  |
                        UnknownEntityException;
792 |  |
793 |  |
         /**
794 |  |
          * Retrieve a set of Groups that meet the specified Criteria.
795 |  |
          *
796 |  |
          * @param criteria a Criteria of Group selection.
797 |  |
          * @return a set of Groups that meet the specified Criteria.
798 |  |
          * @throws DataBackendException if there was an error accessing the data
799 |  |
          *         backend.
800 |  |
          */
801 |  |
         GroupSet getGroups(Object criteria)
802 |  |
                 throws DataBackendException;
803 |  |
804 |  |
         /**
805 |  |
          * Retrieve a set of Roles that meet the specified Criteria.
806 |  |
          *
807 |  |
          * @param criteria a Criteria of Roles selection.
808 |  |
          * @return a set of Roles that meet the specified Criteria.
809 |  |
          * @throws DataBackendException if there was an error accessing the data
810 |  |
          *         backend.
811 |  |
          */
812 |  |
         RoleSet getRoles(Object criteria)
813 |  |
                 throws DataBackendException;
814 |  |
815 |  |
         /**
816 |  |
          * Retrieve a set of Permissions that meet the specified Criteria.
817 |  |
          *
818 |  |
          * @param criteria a Criteria of Permissions selection.
819 |  |
          * @return a set of Permissions that meet the specified Criteria.
820 |  |
          * @throws DataBackendException if there was an error accessing the data
821 |  |
          *         backend.
822 |  |
          */
823 |  |
         PermissionSet getPermissions(Object criteria)
824 |  |
                 throws DataBackendException;
825 |  |
826 |  |
         /**
827 |  |
          * Retrieves all groups defined in the system.
828 |  |
          *
829 |  |
          * @return the names of all groups defined in the system.
830 |  |
          * @throws DataBackendException if there was an error accessing the data
831 |  |
          *         backend.
832 |  |
          */
833 |  |
         GroupSet getAllGroups()
834 |  |
                 throws DataBackendException;
835 |  |
836 |  |
         /**
837 |  |
          * Retrieves all roles defined in the system.
838 |  |
          *
839 |  |
          * @return the names of all roles defined in the system.
840 |  |
          * @throws DataBackendException if there was an error accessing the data
841 |  |
          *         backend.
842 |  |
          */
843 |  |
         RoleSet getAllRoles()
844 |  |
                 throws DataBackendException;
845 |  |
846 |  |
         /**
847 |  |
          * Retrieves all permissions defined in the system.
848 |  |
          *
849 |  |
          * @return the names of all roles defined in the system.
850 |  |
          * @throws DataBackendException if there was an error accessing the data
851 |  |
          *         backend.
852 |  |
          */
853 |  |
         PermissionSet getAllPermissions()
854 |  |
                 throws DataBackendException;
855 |  |
856 |  |
         /**
857 |  |
          * Stores Group's attributes. The Groups is required to exist in the system.
858 |  |
          *
859 |  |
          * @param group The Group to be stored.
860 |  |
          * @throws DataBackendException if there was an error accessing the data
861 |  |
          *         backend.
862 |  |
          * @throws UnknownEntityException if the group does not exist.
863 |  |
          */
864 |  |
         void saveGroup(Group group)
865 |  |
                 throws DataBackendException, UnknownEntityException;
866 |  |
867 |  |
         /**
868 |  |
          * Stores Role's attributes. The Roles is required to exist in the system.
869 |  |
          *
870 |  |
          * @param role The Role to be stored.
871 |  |
          * @throws DataBackendException if there was an error accessing the data
872 |  |
          *         backend.
873 |  |
          * @throws UnknownEntityException if the role does not exist.
874 |  |
          */
875 |  |
         void saveRole(Role role)
876 |  |
                 throws DataBackendException, UnknownEntityException;
877 |  |
878 |  |
         /**
879 |  |
          * Stores Permission's attributes. The Permission is required to exist in
880 |  |
          * the system.
881 |  |
          *
882 |  |
          * @param permission The Permission to be stored.
883 |  |
          * @throws DataBackendException if there was an error accessing the data
884 |  |
          *         backend.
885 |  |
          * @throws UnknownEntityException if the permission does not exist.
886 |  |
          */
887 |  |
         void savePermission(Permission permission)
888 |  |
                 throws DataBackendException, UnknownEntityException;
889 |  |
890 |  |
         /*-----------------------------------------------------------------------
891 |  |
           Group/Role/Permission management
892 |  |
           -----------------------------------------------------------------------*/
893 |  |
894 |  |
         /**
895 |  |
          * Creates a new group with specified attributes.
896 |  |
          *
897 |  |
          * @param group the object describing the group to be created.
898 |  |
          * @return the new Group object.
899 |  |
          * @throws DataBackendException if there was an error accessing the data
900 |  |
          *         backend.
901 |  |
          * @throws EntityExistsException if the group already exists.
902 |  |
          */
903 |  |
         Group addGroup(Group group)
904 |  |
                 throws DataBackendException, EntityExistsException;
905 |  |
906 |  |
         /**
907 |  |
          * Creates a new role with specified attributes.
908 |  |
          *
909 |  |
          * @param role The object describing the role to be created.
910 |  |
          * @return the new Role object.
911 |  |
          * @throws DataBackendException if there was an error accessing the data
912 |  |
          *         backend.
913 |  |
          * @throws EntityExistsException if the role already exists.
914 |  |
          */
915 |  |
         Role addRole(Role role)
916 |  |
                 throws DataBackendException, EntityExistsException;
917 |  |
918 |  |
         /**
919 |  |
          * Creates a new permission with specified attributes.
920 |  |
          *
921 |  |
          * @param permission The object describing the permission to be created.
922 |  |
          * @return the new Permission object.
923 |  |
          * @throws DataBackendException if there was an error accessing the data
924 |  |
          *         backend.
925 |  |
          * @throws EntityExistsException if the permission already exists.
926 |  |
          */
927 |  |
         Permission addPermission(Permission permission)
928 |  |
                 throws DataBackendException, EntityExistsException;
929 |  |
930 |  |
         /**
931 |  |
          * Removes a Group from the system.
932 |  |
          *
933 |  |
          * @param group The object describing the group to be removed.
934 |  |
          * @throws DataBackendException if there was an error accessing the data
935 |  |
          *         backend.
936 |  |
          * @throws UnknownEntityException if the group does not exist.
937 |  |
          */
938 |  |
         void removeGroup(Group group)
939 |  |
                 throws DataBackendException, UnknownEntityException;
940 |  |
941 |  |
         /**
942 |  |
          * Removes a Role from the system.
943 |  |
          *
944 |  |
          * @param role The object describing the role to be removed.
945 |  |
          * @throws DataBackendException if there was an error accessing the data
946 |  |
          *         backend.
947 |  |
          * @throws UnknownEntityException if the role does not exist.
948 |  |
          */
949 |  |
         void removeRole(Role role)
950 |  |
                 throws DataBackendException, UnknownEntityException;
951 |  |
952 |  |
         /**
953 |  |
          * Removes a Permission from the system.
954 |  |
          *
955 |  |
          * @param permission The object describing the permission to be removed.
956 |  |
          * @throws DataBackendException if there was an error accessing the data
957 |  |
          *         backend.
958 |  |
          * @throws UnknownEntityException if the permission does not exist.
959 |  |
          */
960 |  |
         void removePermission(Permission permission)
961 |  |
                 throws DataBackendException, UnknownEntityException;
962 |  |
963 |  |
         /**
964 |  |
          * Renames an existing Group.
965 |  |
          *
966 |  |
          * @param group The object describing the group to be renamed.
967 |  |
          * @param name the new name for the group.
968 |  |
          * @throws DataBackendException if there was an error accessing the data
969 |  |
          *         backend.
970 |  |
          * @throws UnknownEntityException if the group does not exist.
971 |  |
          */
972 |  |
         void renameGroup(Group group, String name)
973 |  |
                 throws DataBackendException, UnknownEntityException;
974 |  |
975 |  |
         /**
976 |  |
          * Renames an existing Role.
977 |  |
          *
978 |  |
          * @param role The object describing the role to be renamed.
979 |  |
          * @param name the new name for the role.
980 |  |
          * @throws DataBackendException if there was an error accessing the data
981 |  |
          *         backend.
982 |  |
          * @throws UnknownEntityException if the role does not exist.
983 |  |
          */
984 |  |
         void renameRole(Role role, String name)
985 |  |
                 throws DataBackendException, UnknownEntityException;
986 |  |
987 |  |
         /**
988 |  |
          * Renames an existing Permission.
989 |  |
          *
990 |  |
          * @param permission The object describing the permission to be renamed.
991 |  |
          * @param name the new name for the permission.
992 |  |
          * @throws DataBackendException if there was an error accessing the data
993 |  |
          *         backend.
994 |  |
          * @throws UnknownEntityException if the permission does not exist.
995 |  |
          */
996 |  |
         void renamePermission(Permission permission, String name)
997 |  |
                 throws DataBackendException, UnknownEntityException;
998 |  |
     }