Coverage Report - org.apache.turbine.services.security.SecurityService
 
Classes in this File Line Coverage Branch Coverage Complexity
SecurityService
N/A
N/A
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  
 }