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