001 package org.apache.turbine.services.security; 002 003 004 /* 005 * Licensed to the Apache Software Foundation (ASF) under one 006 * or more contributor license agreements. See the NOTICE file 007 * distributed with this work for additional information 008 * regarding copyright ownership. The ASF licenses this file 009 * to you under the Apache License, Version 2.0 (the 010 * "License"); you may not use this file except in compliance 011 * with the License. You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, 016 * software distributed under the License is distributed on an 017 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 018 * KIND, either express or implied. See the License for the 019 * specific language governing permissions and limitations 020 * under the License. 021 */ 022 023 024 import java.util.List; 025 import java.util.Map; 026 027 import org.apache.turbine.om.security.Group; 028 import org.apache.turbine.om.security.Permission; 029 import org.apache.turbine.om.security.Role; 030 import org.apache.turbine.om.security.TurbineGroup; 031 import org.apache.turbine.om.security.TurbinePermission; 032 import org.apache.turbine.om.security.TurbineRole; 033 import org.apache.turbine.om.security.TurbineUser; 034 import org.apache.turbine.om.security.User; 035 import org.apache.turbine.services.Service; 036 import org.apache.turbine.services.security.passive.PassiveUserManager; 037 import org.apache.turbine.util.security.AccessControlList; 038 import org.apache.turbine.util.security.DataBackendException; 039 import org.apache.turbine.util.security.EntityExistsException; 040 import org.apache.turbine.util.security.GroupSet; 041 import org.apache.turbine.util.security.PasswordMismatchException; 042 import org.apache.turbine.util.security.PermissionSet; 043 import org.apache.turbine.util.security.RoleSet; 044 import org.apache.turbine.util.security.TurbineAccessControlList; 045 import org.apache.turbine.util.security.UnknownEntityException; 046 047 /** 048 * The Security Service manages Users, Groups Roles and Permissions in the 049 * system. 050 * 051 * The task performed by the security service include creation and removal of 052 * accounts, groups, roles, and permissions; assigning users roles in groups; 053 * assigning roles specific permissions and construction of objects 054 * representing these logical entities. 055 * 056 * <p> Because of pluggable nature of the Services, it is possible to create 057 * multiple implementations of SecurityService, for example employing database 058 * and directory server as the data backend.<br> 059 * 060 * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a> 061 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> 062 * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a> 063 * @version $Id: SecurityService.java 1096130 2011-04-23 10:37:19Z ludwig $ 064 */ 065 public interface SecurityService 066 extends Service 067 { 068 /** The name of the service */ 069 String SERVICE_NAME = "SecurityService"; 070 071 /** 072 * the key within services's properties for user implementation 073 * classname (user.class) 074 */ 075 String USER_CLASS_KEY = "user.class"; 076 077 /** 078 * the default implementation of User interface 079 * (org.apache.turbine.om.security.TurbineUser) 080 */ 081 String USER_CLASS_DEFAULT 082 = TurbineUser.class.getName(); 083 084 /** 085 * The key within services' properties for the GROUP 086 * implementation classname (group.class) 087 */ 088 String GROUP_CLASS_KEY = "group.class"; 089 090 /** 091 * The default implementation of the Group interface 092 * (org.apache.turbine.om.security.TurbineGroup) 093 */ 094 String GROUP_CLASS_DEFAULT 095 = TurbineGroup.class.getName(); 096 097 /** 098 * The key within services' properties for the PERMISSION 099 * 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 }