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