0001: package org.apache.turbine.services.security;
0002:
0003: /*
0004: * Copyright 2001-2005 The Apache Software Foundation.
0005: *
0006: * Licensed under the Apache License, Version 2.0 (the "License")
0007: * you may not use this file except in compliance with the License.
0008: * You may obtain a copy of the License at
0009: *
0010: * http://www.apache.org/licenses/LICENSE-2.0
0011: *
0012: * Unless required by applicable law or agreed to in writing, software
0013: * distributed under the License is distributed on an "AS IS" BASIS,
0014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0015: * See the License for the specific language governing permissions and
0016: * limitations under the License.
0017: */
0018:
0019: import java.util.List;
0020: import java.util.Map;
0021:
0022: import org.apache.torque.util.Criteria;
0023:
0024: import org.apache.turbine.om.security.Group;
0025: import org.apache.turbine.om.security.Permission;
0026: import org.apache.turbine.om.security.Role;
0027: import org.apache.turbine.om.security.TurbineGroup;
0028: import org.apache.turbine.om.security.TurbinePermission;
0029: import org.apache.turbine.om.security.TurbineRole;
0030: import org.apache.turbine.om.security.TurbineUser;
0031: import org.apache.turbine.om.security.User;
0032: import org.apache.turbine.services.Service;
0033: import org.apache.turbine.services.security.db.DBUserManager;
0034: import org.apache.turbine.util.security.AccessControlList;
0035: import org.apache.turbine.util.security.DataBackendException;
0036: import org.apache.turbine.util.security.EntityExistsException;
0037: import org.apache.turbine.util.security.GroupSet;
0038: import org.apache.turbine.util.security.PasswordMismatchException;
0039: import org.apache.turbine.util.security.PermissionSet;
0040: import org.apache.turbine.util.security.RoleSet;
0041: import org.apache.turbine.util.security.TurbineAccessControlList;
0042: import org.apache.turbine.util.security.UnknownEntityException;
0043:
0044: /**
0045: * The Security Service manages Users, Groups Roles and Permissions in the
0046: * system.
0047: *
0048: * The task performed by the security service include creation and removal of
0049: * accounts, groups, roles, and permissions; assigning users roles in groups;
0050: * assigning roles specific permissions and construction of objects
0051: * representing these logical entities.
0052: *
0053: * <p> Because of pluggable nature of the Services, it is possible to create
0054: * multiple implementations of SecurityService, for example employing database
0055: * and directory server as the data backend.<br>
0056: *
0057: * @author <a href="mailto:Rafal.Krzewski@e-point.pl">Rafal Krzewski</a>
0058: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
0059: * @author <a href="mailto:marco@intermeta.de">Marco Knüttel</a>
0060: * @version $Id: SecurityService.java 264152 2005-08-29 14:50:22Z henning $
0061: */
0062: public interface SecurityService extends Service {
0063: /** The name of the service */
0064: String SERVICE_NAME = "SecurityService";
0065:
0066: /**
0067: * the key within services's properties for user implementation
0068: * classname (user.class)
0069: */
0070: String USER_CLASS_KEY = "user.class";
0071:
0072: /**
0073: * the default implementation of User interface
0074: * (org.apache.turbine.om.security.TurbineUser)
0075: */
0076: String USER_CLASS_DEFAULT = TurbineUser.class.getName();
0077:
0078: /**
0079: * The key within services' properties for the GROUP
0080: * implementation classname (group.class)
0081: */
0082: String GROUP_CLASS_KEY = "group.class";
0083:
0084: /**
0085: * The default implementation of the Group interface
0086: * (org.apache.turbine.om.security.TurbineGroup)
0087: */
0088: String GROUP_CLASS_DEFAULT = TurbineGroup.class.getName();
0089:
0090: /**
0091: * The key within services' properties for the PERMISSION
0092: * implementation classname (permission.class)
0093: */
0094: String PERMISSION_CLASS_KEY = "permission.class";
0095:
0096: /**
0097: * The default implementation of the Permissions interface
0098: * (org.apache.turbine.om.security.TurbinePermission)
0099: */
0100: String PERMISSION_CLASS_DEFAULT = TurbinePermission.class.getName();
0101:
0102: /**
0103: * The key within services' properties for the ROLE
0104: * implementation classname (role.class)
0105: */
0106: String ROLE_CLASS_KEY = "role.class";
0107:
0108: /**
0109: * The default implementation of the Role Interface
0110: * (org.apache.turbine.om.security.TurbineRole)
0111: */
0112: String ROLE_CLASS_DEFAULT = TurbineRole.class.getName();
0113:
0114: /**
0115: * The key within services' properties for the
0116: * ACL implementation classname (acl.class)
0117: */
0118: String ACL_CLASS_KEY = "acl.class";
0119:
0120: /**
0121: * The default implementation of the Acl Interface
0122: * (org.apache.turbine.util.security.TurbineAccessControlList)
0123: */
0124: String ACL_CLASS_DEFAULT = TurbineAccessControlList.class.getName();
0125:
0126: /**
0127: * the key within services's properties for user implementation
0128: * classname (user.manager)
0129: */
0130: String USER_MANAGER_KEY = "user.manager";
0131:
0132: /**
0133: * the default implementation of UserManager interface
0134: * (org.apache.turbine.services.security.DBUserManager)
0135: */
0136: String USER_MANAGER_DEFAULT = DBUserManager.class.getName();
0137:
0138: /**
0139: * the key within services's properties for secure passwords flag
0140: * (secure.passwords)
0141: */
0142: String SECURE_PASSWORDS_KEY = "secure.passwords";
0143:
0144: /** the value of secure passwords flag (false) */
0145: String SECURE_PASSWORDS_DEFAULT = "false";
0146:
0147: /**
0148: * the key within services's properties for secure passwords algorithm
0149: * (secure.passwords.algorithm)
0150: */
0151: String SECURE_PASSWORDS_ALGORITHM_KEY = "secure.passwords.algorithm";
0152:
0153: /** the default algorithm for password encryption (SHA) */
0154: String SECURE_PASSWORDS_ALGORITHM_DEFAULT = "SHA";
0155:
0156: /*-----------------------------------------------------------------------
0157: Management of User objects
0158: -----------------------------------------------------------------------*/
0159:
0160: /**
0161: * Returns the Class object for the implementation of User interface
0162: * used by the system.
0163: *
0164: * @return the implementation of User interface used by the system.
0165: * @throws UnknownEntityException if the system's implementation of User
0166: * interface could not be determined.
0167: */
0168: Class getUserClass() throws UnknownEntityException;
0169:
0170: /**
0171: * Construct a blank User object.
0172: *
0173: * This method calls getUserClass, and then creates a new object using
0174: * the default constructor.
0175: *
0176: * @return an object implementing User interface.
0177: * @throws UnknownEntityException if the object could not be instantiated.
0178: */
0179: User getUserInstance() throws UnknownEntityException;
0180:
0181: /**
0182: * Construct a blank User object.
0183: *
0184: * This method calls getUserClass, and then creates a new object using
0185: * the default constructor.
0186: *
0187: * @param userName The name of the user.
0188: *
0189: * @return an object implementing User interface.
0190: * @throws UnknownEntityException if the object could not be instantiated.
0191: */
0192: User getUserInstance(String userName) throws UnknownEntityException;
0193:
0194: /**
0195: * Returns the Class object for the implementation of Group interface
0196: * used by the system.
0197: *
0198: * @return the implementation of Group interface used by the system.
0199: * @throws UnknownEntityException if the system's implementation of Group
0200: * interface could not be determined.
0201: */
0202: Class getGroupClass() throws UnknownEntityException;
0203:
0204: /**
0205: * Construct a blank Group object.
0206: *
0207: * This method calls getGroupClass, and then creates a new object using
0208: * the default constructor.
0209: *
0210: * @return an object implementing Group interface.
0211: * @throws UnknownEntityException if the object could not be instantiated.
0212: */
0213: Group getGroupInstance() throws UnknownEntityException;
0214:
0215: /**
0216: * Construct a blank Group object.
0217: *
0218: * This method calls getGroupClass, and then creates a new object using
0219: * the default constructor.
0220: *
0221: * @param groupName The name of the Group
0222: *
0223: * @return an object implementing Group interface.
0224: * @throws UnknownEntityException if the object could not be instantiated.
0225: */
0226: Group getGroupInstance(String groupName)
0227: throws UnknownEntityException;
0228:
0229: /**
0230: * Returns the Class object for the implementation of Permission interface
0231: * used by the system.
0232: *
0233: * @return the implementation of Permission interface used by the system.
0234: * @throws UnknownEntityException if the system's implementation of Permission
0235: * interface could not be determined.
0236: */
0237: Class getPermissionClass() throws UnknownEntityException;
0238:
0239: /**
0240: * Construct a blank Permission object.
0241: *
0242: * This method calls getPermissionClass, and then creates a new object using
0243: * the default constructor.
0244: *
0245: * @return an object implementing Permission interface.
0246: * @throws UnknownEntityException if the object could not be instantiated.
0247: */
0248: Permission getPermissionInstance() throws UnknownEntityException;
0249:
0250: /**
0251: * Construct a blank Permission object.
0252: *
0253: * This method calls getPermissionClass, and then creates a new object using
0254: * the default constructor.
0255: *
0256: * @param permName The name of the Permission
0257: *
0258: * @return an object implementing Permission interface.
0259: * @throws UnknownEntityException if the object could not be instantiated.
0260: */
0261: Permission getPermissionInstance(String permName)
0262: throws UnknownEntityException;
0263:
0264: /**
0265: * Returns the Class object for the implementation of Role interface
0266: * used by the system.
0267: *
0268: * @return the implementation of Role interface used by the system.
0269: * @throws UnknownEntityException if the system's implementation of Role
0270: * interface could not be determined.
0271: */
0272: Class getRoleClass() throws UnknownEntityException;
0273:
0274: /**
0275: * Construct a blank Role object.
0276: *
0277: * This method calls getRoleClass, and then creates a new object using
0278: * the default constructor.
0279: *
0280: * @return an object implementing Role interface.
0281: * @throws UnknownEntityException if the object could not be instantiated.
0282: */
0283: Role getRoleInstance() throws UnknownEntityException;
0284:
0285: /**
0286: * Construct a blank Role object.
0287: *
0288: * This method calls getRoleClass, and then creates a new object using
0289: * the default constructor.
0290: *
0291: * @param roleName The name of the Role
0292: *
0293: * @return an object implementing Role interface.
0294: * @throws UnknownEntityException if the object could not be instantiated.
0295: */
0296: Role getRoleInstance(String roleName) throws UnknownEntityException;
0297:
0298: /**
0299: * Returns the Class object for the implementation of AccessControlList interface
0300: * used by the system.
0301: *
0302: * @return the implementation of AccessControlList interface used by the system.
0303: * @throws UnknownEntityException if the system's implementation of AccessControlList
0304: * interface could not be determined.
0305: */
0306: Class getAclClass() throws UnknownEntityException;
0307:
0308: /**
0309: * Construct a new ACL object.
0310: *
0311: * This constructs a new ACL object from the configured class and
0312: * initializes it with the supplied roles and permissions.
0313: *
0314: * @param roles The roles that this ACL should contain
0315: * @param permissions The permissions for this ACL
0316: *
0317: * @return an object implementing ACL interface.
0318: * @throws UnknownEntityException if the object could not be instantiated.
0319: */
0320: AccessControlList getAclInstance(Map roles, Map permissions)
0321: throws UnknownEntityException;
0322:
0323: /**
0324: * Returns the configured UserManager.
0325: *
0326: * @return An UserManager object
0327: */
0328: UserManager getUserManager();
0329:
0330: /**
0331: * Configure a new user Manager.
0332: *
0333: * @param userManager An UserManager object
0334: */
0335: void setUserManager(UserManager userManager);
0336:
0337: /**
0338: * Check whether a specified user's account exists.
0339: *
0340: * The login name is used for looking up the account.
0341: *
0342: * @param userName The user to be checked.
0343: * @return true if the specified account exists
0344: * @throws DataBackendException if there was an error accessing the data
0345: * backend.
0346: */
0347: boolean accountExists(String userName) throws DataBackendException;
0348:
0349: /**
0350: * Check whether a specified user's account exists.
0351: * An User object is used for looking up the account.
0352: *
0353: * @param user The user object to be checked.
0354: * @return true if the specified account exists
0355: * @throws DataBackendException if there was an error accessing the data
0356: * backend.
0357: */
0358: boolean accountExists(User user) throws DataBackendException;
0359:
0360: /**
0361: * Authenticates an user, and constructs an User object to represent
0362: * him/her.
0363: *
0364: * @param username The user name.
0365: * @param password The user password.
0366: * @return An authenticated Turbine User.
0367: * @throws DataBackendException if there was an error accessing the data
0368: * backend.
0369: * @throws UnknownEntityException if user account is not present.
0370: * @throws PasswordMismatchException if the supplied password was incorrect.
0371: */
0372: User getAuthenticatedUser(String username, String password)
0373: throws DataBackendException, UnknownEntityException,
0374: PasswordMismatchException;
0375:
0376: /**
0377: * Constructs an User object to represent a registered user of the
0378: * application.
0379: *
0380: * @param username The user name.
0381: * @return A Turbine User.
0382: * @throws DataBackendException if there was an error accessing the data
0383: * backend.
0384: * @throws UnknownEntityException if user account is not present.
0385: */
0386: User getUser(String username) throws DataBackendException,
0387: UnknownEntityException;
0388:
0389: /**
0390: * Retrieve a set of users that meet the specified criteria.
0391: *
0392: * As the keys for the criteria, you should use the constants that
0393: * are defined in {@link User} interface, plus the names
0394: * of the custom attributes you added to your user representation
0395: * in the data storage. Use verbatim names of the attributes -
0396: * without table name prefix in case of DB implementation.
0397: *
0398: * @param criteria The criteria of selection.
0399: * @return a List of users meeting the criteria.
0400: * @throws DataBackendException if there is a problem accessing the
0401: * storage.
0402: * @deprecated Use <a href="#retrieveList">retrieveList</a> instead.
0403: */
0404: User[] getUsers(Criteria criteria) throws DataBackendException;
0405:
0406: /**
0407: * Retrieve a set of users that meet the specified criteria.
0408: *
0409: * As the keys for the criteria, you should use the constants that
0410: * are defined in {@link User} interface, plus the names
0411: * of the custom attributes you added to your user representation
0412: * in the data storage. Use verbatim names of the attributes -
0413: * without table name prefix in case of Torque implementation.
0414: *
0415: * @param criteria The criteria of selection.
0416: * @return a List of users meeting the criteria.
0417: * @throws DataBackendException if there is a problem accessing the
0418: * storage.
0419: */
0420: List getUserList(Criteria criteria) throws DataBackendException;
0421:
0422: /**
0423: * Constructs an User object to represent an anonymous user of the
0424: * application.
0425: *
0426: * @return An anonymous Turbine User.
0427: * @throws UnknownEntityException if the anonymous User object couldn't be
0428: * constructed.
0429: */
0430: User getAnonymousUser() throws UnknownEntityException;
0431:
0432: /**
0433: * Checks whether a passed user object matches the anonymous user pattern
0434: * according to the configured user manager
0435: *
0436: * @param An user object
0437: *
0438: * @return True if this is an anonymous user
0439: *
0440: */
0441: boolean isAnonymousUser(User u);
0442:
0443: /**
0444: * Saves User's data in the permanent storage. The user account is required
0445: * to exist in the storage.
0446: *
0447: * @param user the user object to save
0448: * @throws UnknownEntityException if the user's account does not
0449: * exist in the database.
0450: * @throws DataBackendException if there is a problem accessing the storage.
0451: */
0452: void saveUser(User user) throws UnknownEntityException,
0453: DataBackendException;
0454:
0455: /**
0456: * Saves User data when the session is unbound. The user account is required
0457: * to exist in the storage.
0458: *
0459: * LastLogin, AccessCounter, persistent pull tools, and any data stored
0460: * in the permData hashtable that is not mapped to a column will be saved.
0461: *
0462: * @exception UnknownEntityException if the user's account does not
0463: * exist in the database.
0464: * @exception DataBackendException if there is a problem accessing the
0465: * storage.
0466: */
0467: void saveOnSessionUnbind(User user) throws UnknownEntityException,
0468: DataBackendException;
0469:
0470: /*-----------------------------------------------------------------------
0471: Account management
0472: -----------------------------------------------------------------------*/
0473:
0474: /**
0475: * Creates new user account with specified attributes.
0476: *
0477: * @param user the object describing account to be created.
0478: * @param password The password to use.
0479: * @throws DataBackendException if there was an error accessing the data
0480: * backend.
0481: * @throws EntityExistsException if the user account already exists.
0482: */
0483: void addUser(User user, String password)
0484: throws DataBackendException, EntityExistsException;
0485:
0486: /**
0487: * Removes an user account from the system.
0488: *
0489: * @param user the object describing the account to be removed.
0490: * @throws DataBackendException if there was an error accessing the data
0491: * backend.
0492: * @throws UnknownEntityException if the user account is not present.
0493: */
0494: void removeUser(User user) throws DataBackendException,
0495: UnknownEntityException;
0496:
0497: /*-----------------------------------------------------------------------
0498: Management of passwords
0499: -----------------------------------------------------------------------*/
0500:
0501: /**
0502: * This method provides client-side encryption mechanism for passwords.
0503: *
0504: * This is an utility method that is used by other classes to maintain
0505: * a consistent approach to encrypting password. The behavior of the
0506: * method can be configured in service's properties.
0507: *
0508: * @param password the password to process
0509: * @return processed password
0510: */
0511: String encryptPassword(String password);
0512:
0513: /**
0514: * This method provides client-side encryption mechanism for passwords.
0515: *
0516: * This is an utility method that is used by other classes to maintain
0517: * a consistent approach to encrypting password. The behavior of the
0518: * method can be configured in service's properties.
0519: *
0520: * Algorithms that must supply a salt for encryption
0521: * can use this method to provide it.
0522: *
0523: * @param password the password to process
0524: * @param salt Salt parameter for some crypto algorithms
0525: *
0526: * @return processed password
0527: */
0528: String encryptPassword(String password, String salt);
0529:
0530: /**
0531: * Checks if a supplied password matches the encrypted password
0532: * when using the current encryption algorithm
0533: *
0534: * @param checkpw The clear text password supplied by the user
0535: * @param encpw The current, encrypted password
0536: *
0537: * @return true if the password matches, else false
0538: *
0539: */
0540: boolean checkPassword(String checkpw, String encpw);
0541:
0542: /**
0543: * Change the password for an User.
0544: *
0545: * @param user an User to change password for.
0546: * @param oldPassword the current password supplied by the user.
0547: * @param newPassword the current password requested by the user.
0548: * @exception PasswordMismatchException if the supplied password was
0549: * incorrect.
0550: * @exception UnknownEntityException if the user's record does not
0551: * exist in the database.
0552: * @exception DataBackendException if there is a problem accessing the
0553: * storage.
0554: */
0555: void changePassword(User user, String oldPassword,
0556: String newPassword) throws PasswordMismatchException,
0557: UnknownEntityException, DataBackendException;
0558:
0559: /**
0560: * Forcibly sets new password for an User.
0561: *
0562: * This is supposed by the administrator to change the forgotten or
0563: * compromised passwords. Certain implementatations of this feature
0564: * would require administrative level access to the authenticating
0565: * server / program.
0566: *
0567: * @param user an User to change password for.
0568: * @param password the new password.
0569: * @exception UnknownEntityException if the user's record does not
0570: * exist in the database.
0571: * @exception DataBackendException if there is a problem accessing the
0572: * storage.
0573: */
0574: void forcePassword(User user, String password)
0575: throws UnknownEntityException, DataBackendException;
0576:
0577: /*-----------------------------------------------------------------------
0578: Retrieval of security information
0579: -----------------------------------------------------------------------*/
0580:
0581: /**
0582: * Constructs an AccessControlList for a specific user.
0583: *
0584: * @param user the user for whom the AccessControlList are to be retrieved
0585: * @return A new AccessControlList object.
0586: * @throws DataBackendException if there was an error accessing the data backend.
0587: * @throws UnknownEntityException if user account is not present.
0588: */
0589: AccessControlList getACL(User user) throws DataBackendException,
0590: UnknownEntityException;
0591:
0592: /**
0593: * Retrieves all permissions associated with a role.
0594: *
0595: * @param role the role name, for which the permissions are to be retrieved.
0596: * @return the permissions associated with the role
0597: * @throws DataBackendException if there was an error accessing the data
0598: * backend.
0599: * @throws UnknownEntityException if the role is not present.
0600: */
0601: PermissionSet getPermissions(Role role)
0602: throws DataBackendException, UnknownEntityException;
0603:
0604: /*-----------------------------------------------------------------------
0605: Manipulation of security information
0606: -----------------------------------------------------------------------*/
0607:
0608: /**
0609: * Grant an User a Role in a Group.
0610: *
0611: * @param user the user.
0612: * @param group the group.
0613: * @param role the role.
0614: * @throws DataBackendException if there was an error accessing the data
0615: * backend.
0616: * @throws UnknownEntityException if user account, group or role is not
0617: * present.
0618: */
0619: void grant(User user, Group group, Role role)
0620: throws DataBackendException, UnknownEntityException;
0621:
0622: /**
0623: * Revoke a Role in a Group from an User.
0624: *
0625: * @param user the user.
0626: * @param group the group.
0627: * @param role the role.
0628: * @throws DataBackendException if there was an error accessing the data
0629: * backend.
0630: * @throws UnknownEntityException if user account, group or role is not
0631: * present.
0632: */
0633: void revoke(User user, Group group, Role role)
0634: throws DataBackendException, UnknownEntityException;
0635:
0636: /**
0637: * Revokes all roles from an User.
0638: *
0639: * This method is used when deleting an account.
0640: *
0641: * @param user the User.
0642: * @throws DataBackendException if there was an error accessing the data
0643: * backend.
0644: * @throws UnknownEntityException if the account is not present.
0645: */
0646: void revokeAll(User user) throws DataBackendException,
0647: UnknownEntityException;
0648:
0649: /**
0650: * Grants a Role a Permission
0651: *
0652: * @param role the Role.
0653: * @param permission the Permission.
0654: * @throws DataBackendException if there was an error accessing the data
0655: * backend.
0656: * @throws UnknownEntityException if role or permission is not present.
0657: */
0658: void grant(Role role, Permission permission)
0659: throws DataBackendException, UnknownEntityException;
0660:
0661: /**
0662: * Revokes a Permission from a Role.
0663: *
0664: * @param role the Role.
0665: * @param permission the Permission.
0666: * @throws DataBackendException if there was an error accessing the data
0667: * backend.
0668: * @throws UnknownEntityException if role or permission is not present.
0669: */
0670: void revoke(Role role, Permission permission)
0671: throws DataBackendException, UnknownEntityException;
0672:
0673: /**
0674: * Revokes all permissions from a Role.
0675: *
0676: * This method is user when deleting a Role.
0677: *
0678: * @param role the Role
0679: * @throws DataBackendException if there was an error accessing the data
0680: * backend.
0681: * @throws UnknownEntityException if the Role is not present.
0682: */
0683: void revokeAll(Role role) throws DataBackendException,
0684: UnknownEntityException;
0685:
0686: /*-----------------------------------------------------------------------
0687: Retrieval & storage of SecurityObjects
0688: -----------------------------------------------------------------------*/
0689:
0690: /**
0691: * Provides a reference to the Group object that represents the
0692: * <a href="#global">global group</a>.
0693: *
0694: * @return A Group object that represents the global group.
0695: */
0696: Group getGlobalGroup();
0697:
0698: /**
0699: * @deprecated Use getGroupInstance(String name) instead.
0700: */
0701: Group getNewGroup(String groupName);
0702:
0703: /**
0704: * @deprecated Use getRoleInstance(String name) instead.
0705: */
0706: Role getNewRole(String roleName);
0707:
0708: /**
0709: * @deprecated Use getPermissionInstance(String name) instead.
0710: */
0711: Permission getNewPermission(String permissionName);
0712:
0713: /**
0714: * Retrieve a Group object with specified name.
0715: *
0716: * @param name the name of the Group.
0717: * @return an object representing the Group with specified name.
0718: * @throws DataBackendException if there was an error accessing the data
0719: * backend.
0720: * @throws UnknownEntityException if the group does not exist.
0721: * @deprecated Use <a href="#getGroupByName">getGroupByName</a> instead.
0722: */
0723: Group getGroup(String name) throws DataBackendException,
0724: UnknownEntityException;
0725:
0726: /**
0727: * Retrieve a Group object with specified name.
0728: *
0729: * @param name the name of the Group.
0730: * @return an object representing the Group with specified name.
0731: * @throws DataBackendException if there was an error accessing the data
0732: * backend.
0733: * @throws UnknownEntityException if the group does not exist.
0734: */
0735: Group getGroupByName(String name) throws DataBackendException,
0736: UnknownEntityException;
0737:
0738: /**
0739: * Retrieve a Group object with specified Id.
0740: *
0741: * @param name the name of the Group.
0742: *
0743: * @return an object representing the Group with specified name.
0744: *
0745: * @exception UnknownEntityException if the permission does not
0746: * exist in the database.
0747: * @exception DataBackendException if there is a problem accessing the
0748: * storage.
0749: */
0750: Group getGroupById(int id) throws DataBackendException,
0751: UnknownEntityException;
0752:
0753: /**
0754: * Retrieve a Role object with specified name.
0755: *
0756: * @param name the name of the Role.
0757: * @return an object representing the Role with specified name.
0758: * @throws DataBackendException if there was an error accessing the data
0759: * backend.
0760: * @throws UnknownEntityException if the role does not exist.
0761: * @deprecated Use <a href="#getRoleByName">getRoleByName</a> instead.
0762: */
0763: Role getRole(String name) throws DataBackendException,
0764: UnknownEntityException;
0765:
0766: /**
0767: * Retrieve a Role object with specified name.
0768: *
0769: * @param name the name of the Role.
0770: * @return an object representing the Role with specified name.
0771: * @throws DataBackendException if there was an error accessing the data
0772: * backend.
0773: * @throws UnknownEntityException if the role does not exist.
0774: */
0775: Role getRoleByName(String name) throws DataBackendException,
0776: UnknownEntityException;
0777:
0778: /**
0779: * Retrieve a Role object with specified Id.
0780: *
0781: * @param name the name of the Role.
0782: *
0783: * @return an object representing the Role with specified name.
0784: *
0785: * @exception UnknownEntityException if the permission does not
0786: * exist in the database.
0787: * @exception DataBackendException if there is a problem accessing the
0788: * storage.
0789: */
0790: Role getRoleById(int id) throws DataBackendException,
0791: UnknownEntityException;
0792:
0793: /**
0794: * Retrieve a Permission object with specified name.
0795: *
0796: * @param name the name of the Permission.
0797: * @return an object representing the Permission with specified name.
0798: * @throws DataBackendException if there was an error accessing the data
0799: * backend.
0800: * @throws UnknownEntityException if the permission does not exist.
0801: * @deprecated Use <a href="#getPermissionByName">getPermissionByName</a> instead.
0802: */
0803: Permission getPermission(String name) throws DataBackendException,
0804: UnknownEntityException;
0805:
0806: /**
0807: * Retrieve a Permission object with specified name.
0808: *
0809: * @param name the name of the Permission.
0810: * @return an object representing the Permission with specified name.
0811: * @throws DataBackendException if there was an error accessing the data
0812: * backend.
0813: * @throws UnknownEntityException if the permission does not exist.
0814: */
0815: Permission getPermissionByName(String name)
0816: throws DataBackendException, UnknownEntityException;
0817:
0818: /**
0819: * Retrieve a Permission object with specified Id.
0820: *
0821: * @param name the name of the Permission.
0822: *
0823: * @return an object representing the Permission with specified name.
0824: *
0825: * @exception UnknownEntityException if the permission does not
0826: * exist in the database.
0827: * @exception DataBackendException if there is a problem accessing the
0828: * storage.
0829: */
0830: Permission getPermissionById(int id) throws DataBackendException,
0831: UnknownEntityException;
0832:
0833: /**
0834: * Retrieve a set of Groups that meet the specified Criteria.
0835: *
0836: * @param criteria a Criteria of Group selection.
0837: * @return a set of Groups that meet the specified Criteria.
0838: * @throws DataBackendException if there was an error accessing the data
0839: * backend.
0840: */
0841: GroupSet getGroups(Criteria criteria) throws DataBackendException;
0842:
0843: /**
0844: * Retrieve a set of Roles that meet the specified Criteria.
0845: *
0846: * @param criteria a Criteria of Roles selection.
0847: * @return a set of Roles that meet the specified Criteria.
0848: * @throws DataBackendException if there was an error accessing the data
0849: * backend.
0850: */
0851: RoleSet getRoles(Criteria criteria) throws DataBackendException;
0852:
0853: /**
0854: * Retrieve a set of Permissions that meet the specified Criteria.
0855: *
0856: * @param criteria a Criteria of Permissions selection.
0857: * @return a set of Permissions that meet the specified Criteria.
0858: * @throws DataBackendException if there was an error accessing the data
0859: * backend.
0860: */
0861: PermissionSet getPermissions(Criteria criteria)
0862: throws DataBackendException;
0863:
0864: /**
0865: * Retrieves all groups defined in the system.
0866: *
0867: * @return the names of all groups defined in the system.
0868: * @throws DataBackendException if there was an error accessing the data
0869: * backend.
0870: */
0871: GroupSet getAllGroups() throws DataBackendException;
0872:
0873: /**
0874: * Retrieves all roles defined in the system.
0875: *
0876: * @return the names of all roles defined in the system.
0877: * @throws DataBackendException if there was an error accessing the data
0878: * backend.
0879: */
0880: RoleSet getAllRoles() throws DataBackendException;
0881:
0882: /**
0883: * Retrieves all permissions defined in the system.
0884: *
0885: * @return the names of all roles defined in the system.
0886: * @throws DataBackendException if there was an error accessing the data
0887: * backend.
0888: */
0889: PermissionSet getAllPermissions() throws DataBackendException;
0890:
0891: /**
0892: * Stores Group's attributes. The Groups is required to exist in the system.
0893: *
0894: * @param group The Group to be stored.
0895: * @throws DataBackendException if there was an error accessing the data
0896: * backend.
0897: * @throws UnknownEntityException if the group does not exist.
0898: */
0899: void saveGroup(Group group) throws DataBackendException,
0900: UnknownEntityException;
0901:
0902: /**
0903: * Stores Role's attributes. The Roles is required to exist in the system.
0904: *
0905: * @param role The Role to be stored.
0906: * @throws DataBackendException if there was an error accessing the data
0907: * backend.
0908: * @throws UnknownEntityException if the role does not exist.
0909: */
0910: void saveRole(Role role) throws DataBackendException,
0911: UnknownEntityException;
0912:
0913: /**
0914: * Stores Permission's attributes. The Permission is required to exist in
0915: * the system.
0916: *
0917: * @param permission The Permission to be stored.
0918: * @throws DataBackendException if there was an error accessing the data
0919: * backend.
0920: * @throws UnknownEntityException if the permission does not exist.
0921: */
0922: void savePermission(Permission permission)
0923: throws DataBackendException, UnknownEntityException;
0924:
0925: /*-----------------------------------------------------------------------
0926: Group/Role/Permission management
0927: -----------------------------------------------------------------------*/
0928:
0929: /**
0930: * Creates a new group with specified attributes.
0931: *
0932: * @param group the object describing the group to be created.
0933: * @return the new Group object.
0934: * @throws DataBackendException if there was an error accessing the data
0935: * backend.
0936: * @throws EntityExistsException if the group already exists.
0937: */
0938: Group addGroup(Group group) throws DataBackendException,
0939: EntityExistsException;
0940:
0941: /**
0942: * Creates a new role with specified attributes.
0943: *
0944: * @param role The object describing the role to be created.
0945: * @return the new Role object.
0946: * @throws DataBackendException if there was an error accessing the data
0947: * backend.
0948: * @throws EntityExistsException if the role already exists.
0949: */
0950: Role addRole(Role role) throws DataBackendException,
0951: EntityExistsException;
0952:
0953: /**
0954: * Creates a new permission with specified attributes.
0955: *
0956: * @param permission The object describing the permission to be created.
0957: * @return the new Permission object.
0958: * @throws DataBackendException if there was an error accessing the data
0959: * backend.
0960: * @throws EntityExistsException if the permission already exists.
0961: */
0962: Permission addPermission(Permission permission)
0963: throws DataBackendException, EntityExistsException;
0964:
0965: /**
0966: * Removes a Group from the system.
0967: *
0968: * @param group The object describing the group to be removed.
0969: * @throws DataBackendException if there was an error accessing the data
0970: * backend.
0971: * @throws UnknownEntityException if the group does not exist.
0972: */
0973: void removeGroup(Group group) throws DataBackendException,
0974: UnknownEntityException;
0975:
0976: /**
0977: * Removes a Role from the system.
0978: *
0979: * @param role The object describing the role to be removed.
0980: * @throws DataBackendException if there was an error accessing the data
0981: * backend.
0982: * @throws UnknownEntityException if the role does not exist.
0983: */
0984: void removeRole(Role role) throws DataBackendException,
0985: UnknownEntityException;
0986:
0987: /**
0988: * Removes a Permission from the system.
0989: *
0990: * @param permission The object describing the permission to be removed.
0991: * @throws DataBackendException if there was an error accessing the data
0992: * backend.
0993: * @throws UnknownEntityException if the permission does not exist.
0994: */
0995: void removePermission(Permission permission)
0996: throws DataBackendException, UnknownEntityException;
0997:
0998: /**
0999: * Renames an existing Group.
1000: *
1001: * @param group The object describing the group to be renamed.
1002: * @param name the new name for the group.
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 renameGroup(Group group, String name)
1008: throws DataBackendException, UnknownEntityException;
1009:
1010: /**
1011: * Renames an existing Role.
1012: *
1013: * @param role The object describing the role to be renamed.
1014: * @param name the new name for the role.
1015: * @throws DataBackendException if there was an error accessing the data
1016: * backend.
1017: * @throws UnknownEntityException if the role does not exist.
1018: */
1019: void renameRole(Role role, String name)
1020: throws DataBackendException, UnknownEntityException;
1021:
1022: /**
1023: * Renames an existing Permission.
1024: *
1025: * @param permission The object describing the permission to be renamed.
1026: * @param name the new name for the permission.
1027: * @throws DataBackendException if there was an error accessing the data
1028: * backend.
1029: * @throws UnknownEntityException if the permission does not exist.
1030: */
1031: void renamePermission(Permission permission, String name)
1032: throws DataBackendException, UnknownEntityException;
1033: }
|