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