Coverage report

  %line %branch
org.apache.turbine.services.security.SecurityService$1
100% 
100% 

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

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.