org.apache.turbine.services.security
Interface SecurityService

All Superinterfaces:

Initable, Service

All Known Implementing Classes:

BaseSecurityService

public interface SecurityService

extends Service

The Security Service manages Users, Groups Roles and Permissions in the system. The task performed by the security service include creation and removal of accounts, groups, roles, and permissions; assigning users roles in groups; assigning roles specific permissions and construction of objects representing these logical entities.

Because of pluggable nature of the Services, it is possible to create multiple implementations of SecurityService, for example employing database and directory server as the data backend.

Version:

$Id: SecurityService.java 264152 2005-08-29 14:50:22Z henning $

Author:

Rafal Krzewski, Henning P. Schmiedehausen, Marco Knüttel

Field Summary

static java.lang.String	ACL_CLASS_DEFAULT The default implementation of the Acl Interface (org.apache.turbine.util.security.TurbineAccessControlList)
static java.lang.String	ACL_CLASS_KEY The key within services' properties for the ACL implementation classname (acl.class)
static java.lang.String	GROUP_CLASS_DEFAULT The default implementation of the Group interface (org.apache.turbine.om.security.TurbineGroup)
static java.lang.String	GROUP_CLASS_KEY The key within services' properties for the GROUP implementation classname (group.class)
static java.lang.String	PERMISSION_CLASS_DEFAULT The default implementation of the Permissions interface (org.apache.turbine.om.security.TurbinePermission)
static java.lang.String	PERMISSION_CLASS_KEY The key within services' properties for the PERMISSION implementation classname (permission.class)
static java.lang.String	ROLE_CLASS_DEFAULT The default implementation of the Role Interface (org.apache.turbine.om.security.TurbineRole)
static java.lang.String	ROLE_CLASS_KEY The key within services' properties for the ROLE implementation classname (role.class)
static java.lang.String	SECURE_PASSWORDS_ALGORITHM_DEFAULT the default algorithm for password encryption (SHA)
static java.lang.String	SECURE_PASSWORDS_ALGORITHM_KEY the key within services's properties for secure passwords algorithm (secure.passwords.algorithm)
static java.lang.String	SECURE_PASSWORDS_DEFAULT the value of secure passwords flag (false)
static java.lang.String	SECURE_PASSWORDS_KEY the key within services's properties for secure passwords flag (secure.passwords)
static java.lang.String	SERVICE_NAME The name of the service
static java.lang.String	USER_CLASS_DEFAULT the default implementation of User interface (org.apache.turbine.om.security.TurbineUser)
static java.lang.String	USER_CLASS_KEY the key within services's properties for user implementation classname (user.class)
static java.lang.String	USER_MANAGER_DEFAULT the default implementation of UserManager interface (org.apache.turbine.services.security.DBUserManager)
static java.lang.String	USER_MANAGER_KEY the key within services's properties for user implementation classname (user.manager)

Method Summary

boolean	accountExists(java.lang.String userName) Check whether a specified user's account exists.
boolean	accountExists(User user) Check whether a specified user's account exists.
Group	addGroup(Group group) Creates a new group with specified attributes.
Permission	addPermission(Permission permission) Creates a new permission with specified attributes.
Role	addRole(Role role) Creates a new role with specified attributes.
void	addUser(User user, java.lang.String password) Creates new user account with specified attributes.
void	changePassword(User user, java.lang.String oldPassword, java.lang.String newPassword) Change the password for an User.
boolean	checkPassword(java.lang.String checkpw, java.lang.String encpw) Checks if a supplied password matches the encrypted password when using the current encryption algorithm
java.lang.String	encryptPassword(java.lang.String password) This method provides client-side encryption mechanism for passwords.
java.lang.String	encryptPassword(java.lang.String password, java.lang.String salt) This method provides client-side encryption mechanism for passwords.
void	forcePassword(User user, java.lang.String password) Forcibly sets new password for an User.
AccessControlList	getACL(User user) Constructs an AccessControlList for a specific user.
java.lang.Class	getAclClass() Returns the Class object for the implementation of AccessControlList interface used by the system.
AccessControlList	getAclInstance(java.util.Map roles, java.util.Map permissions) Construct a new ACL object.
GroupSet	getAllGroups() Retrieves all groups defined in the system.
PermissionSet	getAllPermissions() Retrieves all permissions defined in the system.
RoleSet	getAllRoles() Retrieves all roles defined in the system.
User	getAnonymousUser() Constructs an User object to represent an anonymous user of the application.
User	getAuthenticatedUser(java.lang.String username, java.lang.String password) Authenticates an user, and constructs an User object to represent him/her.
Group	getGlobalGroup() Provides a reference to the Group object that represents the global group.
Group	getGroup(java.lang.String name) Deprecated. Use getGroupByName instead.
Group	getGroupById(int id) Retrieve a Group object with specified Id.
Group	getGroupByName(java.lang.String name) Retrieve a Group object with specified name.
java.lang.Class	getGroupClass() Returns the Class object for the implementation of Group interface used by the system.
Group	getGroupInstance() Construct a blank Group object.
Group	getGroupInstance(java.lang.String groupName) Construct a blank Group object.
GroupSet	getGroups(org.apache.torque.util.Criteria criteria) Retrieve a set of Groups that meet the specified Criteria.
Group	getNewGroup(java.lang.String groupName) Deprecated. Use getGroupInstance(String name) instead.
Permission	getNewPermission(java.lang.String permissionName) Deprecated. Use getPermissionInstance(String name) instead.
Role	getNewRole(java.lang.String roleName) Deprecated. Use getRoleInstance(String name) instead.
Permission	getPermission(java.lang.String name) Deprecated. Use getPermissionByName instead.
Permission	getPermissionById(int id) Retrieve a Permission object with specified Id.
Permission	getPermissionByName(java.lang.String name) Retrieve a Permission object with specified name.
java.lang.Class	getPermissionClass() Returns the Class object for the implementation of Permission interface used by the system.
Permission	getPermissionInstance() Construct a blank Permission object.
Permission	getPermissionInstance(java.lang.String permName) Construct a blank Permission object.
PermissionSet	getPermissions(org.apache.torque.util.Criteria criteria) Retrieve a set of Permissions that meet the specified Criteria.
PermissionSet	getPermissions(Role role) Retrieves all permissions associated with a role.
Role	getRole(java.lang.String name) Deprecated. Use getRoleByName instead.
Role	getRoleById(int id) Retrieve a Role object with specified Id.
Role	getRoleByName(java.lang.String name) Retrieve a Role object with specified name.
java.lang.Class	getRoleClass() Returns the Class object for the implementation of Role interface used by the system.
Role	getRoleInstance() Construct a blank Role object.
Role	getRoleInstance(java.lang.String roleName) Construct a blank Role object.
RoleSet	getRoles(org.apache.torque.util.Criteria criteria) Retrieve a set of Roles that meet the specified Criteria.
User	getUser(java.lang.String username) Constructs an User object to represent a registered user of the application.
java.lang.Class	getUserClass() Returns the Class object for the implementation of User interface used by the system.
User	getUserInstance() Construct a blank User object.
User	getUserInstance(java.lang.String userName) Construct a blank User object.
java.util.List	getUserList(org.apache.torque.util.Criteria criteria) Retrieve a set of users that meet the specified criteria.
UserManager	getUserManager() Returns the configured UserManager.
User[]	getUsers(org.apache.torque.util.Criteria criteria) Deprecated. Use retrieveList instead.
void	grant(Role role, Permission permission) Grants a Role a Permission
void	grant(User user, Group group, Role role) Grant an User a Role in a Group.
boolean	isAnonymousUser(User u) Checks whether a passed user object matches the anonymous user pattern according to the configured user manager
void	removeGroup(Group group) Removes a Group from the system.
void	removePermission(Permission permission) Removes a Permission from the system.
void	removeRole(Role role) Removes a Role from the system.
void	removeUser(User user) Removes an user account from the system.
void	renameGroup(Group group, java.lang.String name) Renames an existing Group.
void	renamePermission(Permission permission, java.lang.String name) Renames an existing Permission.
void	renameRole(Role role, java.lang.String name) Renames an existing Role.
void	revoke(Role role, Permission permission) Revokes a Permission from a Role.
void	revoke(User user, Group group, Role role) Revoke a Role in a Group from an User.
void	revokeAll(Role role) Revokes all permissions from a Role.
void	revokeAll(User user) Revokes all roles from an User.
void	saveGroup(Group group) Stores Group's attributes.
void	saveOnSessionUnbind(User user) Saves User data when the session is unbound.
void	savePermission(Permission permission) Stores Permission's attributes.
void	saveRole(Role role) Stores Role's attributes.
void	saveUser(User user) Saves User's data in the permanent storage.
void	setUserManager(UserManager userManager) Configure a new user Manager.

Methods inherited from interface org.apache.turbine.services.Service

getConfiguration, getName, getProperties, setName, setServiceBroker

Methods inherited from interface org.apache.turbine.services.Initable

getInit, init, init, setInitableBroker, shutdown

Field Detail

SERVICE_NAME

public static final java.lang.String SERVICE_NAME

The name of the service

See Also:

Constant Field Values

USER_CLASS_KEY

public static final java.lang.String USER_CLASS_KEY

the key within services's properties for user implementation classname (user.class)

See Also:

Constant Field Values

USER_CLASS_DEFAULT

public static final java.lang.String USER_CLASS_DEFAULT

the default implementation of User interface (org.apache.turbine.om.security.TurbineUser)

GROUP_CLASS_KEY

public static final java.lang.String GROUP_CLASS_KEY

The key within services' properties for the GROUP implementation classname (group.class)

See Also:

Constant Field Values

GROUP_CLASS_DEFAULT

public static final java.lang.String GROUP_CLASS_DEFAULT

The default implementation of the Group interface (org.apache.turbine.om.security.TurbineGroup)

PERMISSION_CLASS_KEY

public static final java.lang.String PERMISSION_CLASS_KEY

The key within services' properties for the PERMISSION implementation classname (permission.class)

See Also:

Constant Field Values

PERMISSION_CLASS_DEFAULT

public static final java.lang.String PERMISSION_CLASS_DEFAULT

The default implementation of the Permissions interface (org.apache.turbine.om.security.TurbinePermission)

ROLE_CLASS_KEY

public static final java.lang.String ROLE_CLASS_KEY

The key within services' properties for the ROLE implementation classname (role.class)

See Also:

Constant Field Values

ROLE_CLASS_DEFAULT

public static final java.lang.String ROLE_CLASS_DEFAULT

The default implementation of the Role Interface (org.apache.turbine.om.security.TurbineRole)

ACL_CLASS_KEY

public static final java.lang.String ACL_CLASS_KEY

The key within services' properties for the ACL implementation classname (acl.class)

See Also:

Constant Field Values

ACL_CLASS_DEFAULT

public static final java.lang.String ACL_CLASS_DEFAULT

The default implementation of the Acl Interface (org.apache.turbine.util.security.TurbineAccessControlList)

USER_MANAGER_KEY

public static final java.lang.String USER_MANAGER_KEY

the key within services's properties for user implementation classname (user.manager)

See Also:

Constant Field Values

USER_MANAGER_DEFAULT

public static final java.lang.String USER_MANAGER_DEFAULT

the default implementation of UserManager interface (org.apache.turbine.services.security.DBUserManager)

SECURE_PASSWORDS_KEY

public static final java.lang.String SECURE_PASSWORDS_KEY

the key within services's properties for secure passwords flag (secure.passwords)

See Also:

Constant Field Values

SECURE_PASSWORDS_DEFAULT

public static final java.lang.String SECURE_PASSWORDS_DEFAULT

the value of secure passwords flag (false)

See Also:

Constant Field Values

SECURE_PASSWORDS_ALGORITHM_KEY

public static final java.lang.String SECURE_PASSWORDS_ALGORITHM_KEY

the key within services's properties for secure passwords algorithm (secure.passwords.algorithm)

See Also:

Constant Field Values

SECURE_PASSWORDS_ALGORITHM_DEFAULT

public static final java.lang.String SECURE_PASSWORDS_ALGORITHM_DEFAULT

the default algorithm for password encryption (SHA)

See Also:

Constant Field Values

Method Detail

getUserClass

public java.lang.Class getUserClass()
                             throws UnknownEntityException

Returns the Class object for the implementation of User interface used by the system.

Returns:

the implementation of User interface used by the system.

Throws:

UnknownEntityException - if the system's implementation of User interface could not be determined.

getUserInstance

public User getUserInstance()
                     throws UnknownEntityException

Construct a blank User object. This method calls getUserClass, and then creates a new object using the default constructor.

Returns:

an object implementing User interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getUserInstance

public User getUserInstance(java.lang.String userName)
                     throws UnknownEntityException

Construct a blank User object. This method calls getUserClass, and then creates a new object using the default constructor.

Parameters:

userName - The name of the user.

Returns:

an object implementing User interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getGroupClass

public java.lang.Class getGroupClass()
                              throws UnknownEntityException

Returns the Class object for the implementation of Group interface used by the system.

Returns:

the implementation of Group interface used by the system.

Throws:

UnknownEntityException - if the system's implementation of Group interface could not be determined.

getGroupInstance

public Group getGroupInstance()
                       throws UnknownEntityException

Construct a blank Group object. This method calls getGroupClass, and then creates a new object using the default constructor.

Returns:

an object implementing Group interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getGroupInstance

public Group getGroupInstance(java.lang.String groupName)
                       throws UnknownEntityException

Construct a blank Group object. This method calls getGroupClass, and then creates a new object using the default constructor.

Parameters:

groupName - The name of the Group

Returns:

an object implementing Group interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getPermissionClass

public java.lang.Class getPermissionClass()
                                   throws UnknownEntityException

Returns the Class object for the implementation of Permission interface used by the system.

Returns:

the implementation of Permission interface used by the system.

Throws:

UnknownEntityException - if the system's implementation of Permission interface could not be determined.

getPermissionInstance

public Permission getPermissionInstance()
                                 throws UnknownEntityException

Construct a blank Permission object. This method calls getPermissionClass, and then creates a new object using the default constructor.

Returns:

an object implementing Permission interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getPermissionInstance

public Permission getPermissionInstance(java.lang.String permName)
                                 throws UnknownEntityException

Construct a blank Permission object. This method calls getPermissionClass, and then creates a new object using the default constructor.

Parameters:

permName - The name of the Permission

Returns:

an object implementing Permission interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getRoleClass

public java.lang.Class getRoleClass()
                             throws UnknownEntityException

Returns the Class object for the implementation of Role interface used by the system.

Returns:

the implementation of Role interface used by the system.

Throws:

UnknownEntityException - if the system's implementation of Role interface could not be determined.

getRoleInstance

public Role getRoleInstance()
                     throws UnknownEntityException

Construct a blank Role object. This method calls getRoleClass, and then creates a new object using the default constructor.

Returns:

an object implementing Role interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getRoleInstance

public Role getRoleInstance(java.lang.String roleName)
                     throws UnknownEntityException

Construct a blank Role object. This method calls getRoleClass, and then creates a new object using the default constructor.

Parameters:

roleName - The name of the Role

Returns:

an object implementing Role interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getAclClass

public java.lang.Class getAclClass()
                            throws UnknownEntityException

Returns the Class object for the implementation of AccessControlList interface used by the system.

Returns:

the implementation of AccessControlList interface used by the system.

Throws:

UnknownEntityException - if the system's implementation of AccessControlList interface could not be determined.

getAclInstance

public AccessControlList getAclInstance(java.util.Map roles,
                                        java.util.Map permissions)
                                 throws UnknownEntityException

Construct a new ACL object. This constructs a new ACL object from the configured class and initializes it with the supplied roles and permissions.

Parameters:

roles - The roles that this ACL should contain

permissions - The permissions for this ACL

Returns:

an object implementing ACL interface.

Throws:

UnknownEntityException - if the object could not be instantiated.

getUserManager

public UserManager getUserManager()

Returns the configured UserManager.

Returns:

An UserManager object

setUserManager

public void setUserManager(UserManager userManager)

Configure a new user Manager.

Parameters:

userManager - An UserManager object

accountExists

public boolean accountExists(java.lang.String userName)
                      throws DataBackendException

Check whether a specified user's account exists. The login name is used for looking up the account.

Parameters:

userName - The user to be checked.

Returns:

true if the specified account exists

Throws:

DataBackendException - if there was an error accessing the data backend.

accountExists

public boolean accountExists(User user)
                      throws DataBackendException

Check whether a specified user's account exists. An User object is used for looking up the account.

Parameters:

user - The user object to be checked.

Returns:

true if the specified account exists

Throws:

DataBackendException - if there was an error accessing the data backend.

getAuthenticatedUser

public User getAuthenticatedUser(java.lang.String username,
                                 java.lang.String password)
                          throws DataBackendException,
                                 UnknownEntityException,
                                 PasswordMismatchException

Authenticates an user, and constructs an User object to represent him/her.

Parameters:

username - The user name.

password - The user password.

Returns:

An authenticated Turbine User.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if user account is not present.

PasswordMismatchException - if the supplied password was incorrect.

getUser

public User getUser(java.lang.String username)
             throws DataBackendException,
                    UnknownEntityException

Constructs an User object to represent a registered user of the application.

Parameters:

username - The user name.

Returns:

A Turbine User.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if user account is not present.

getUsers

public User[] getUsers(org.apache.torque.util.Criteria criteria)
                throws DataBackendException

Deprecated. Use retrieveList instead.

Retrieve a set of users that meet the specified criteria. As the keys for the criteria, you should use the constants that are defined in User interface, plus the names of the custom attributes you added to your user representation in the data storage. Use verbatim names of the attributes - without table name prefix in case of DB implementation.

Parameters:

criteria - The criteria of selection.

Returns:

a List of users meeting the criteria.

Throws:

DataBackendException - if there is a problem accessing the storage.

getUserList

public java.util.List getUserList(org.apache.torque.util.Criteria criteria)
                           throws DataBackendException

Retrieve a set of users that meet the specified criteria. As the keys for the criteria, you should use the constants that are defined in User interface, plus the names of the custom attributes you added to your user representation in the data storage. Use verbatim names of the attributes - without table name prefix in case of Torque implementation.

Parameters:

criteria - The criteria of selection.

Returns:

a List of users meeting the criteria.

Throws:

DataBackendException - if there is a problem accessing the storage.

getAnonymousUser

public User getAnonymousUser()
                      throws UnknownEntityException

Constructs an User object to represent an anonymous user of the application.

Returns:

An anonymous Turbine User.

Throws:

UnknownEntityException - if the anonymous User object couldn't be constructed.

isAnonymousUser

public boolean isAnonymousUser(User u)

Checks whether a passed user object matches the anonymous user pattern according to the configured user manager

Returns:

True if this is an anonymous user

saveUser

public void saveUser(User user)
              throws UnknownEntityException,
                     DataBackendException

Saves User's data in the permanent storage. The user account is required to exist in the storage.

Parameters:

user - the user object to save

Throws:

UnknownEntityException - if the user's account does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

saveOnSessionUnbind

public void saveOnSessionUnbind(User user)
                         throws UnknownEntityException,
                                DataBackendException

Saves User data when the session is unbound. The user account is required to exist in the storage. LastLogin, AccessCounter, persistent pull tools, and any data stored in the permData hashtable that is not mapped to a column will be saved.

Throws:

UnknownEntityException - if the user's account does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

addUser

public void addUser(User user,
                    java.lang.String password)
             throws DataBackendException,
                    EntityExistsException

Creates new user account with specified attributes.

Parameters:

user - the object describing account to be created.

password - The password to use.

Throws:

DataBackendException - if there was an error accessing the data backend.

EntityExistsException - if the user account already exists.

removeUser

public void removeUser(User user)
                throws DataBackendException,
                       UnknownEntityException

Removes an user account from the system.

Parameters:

user - the object describing the account to be removed.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the user account is not present.

encryptPassword

public java.lang.String encryptPassword(java.lang.String password)

This method provides client-side encryption mechanism for passwords. This is an utility method that is used by other classes to maintain a consistent approach to encrypting password. The behavior of the method can be configured in service's properties.

Parameters:

password - the password to process

Returns:

processed password

encryptPassword

public java.lang.String encryptPassword(java.lang.String password,
                                        java.lang.String salt)

This method provides client-side encryption mechanism for passwords. This is an utility method that is used by other classes to maintain a consistent approach to encrypting password. The behavior of the method can be configured in service's properties. Algorithms that must supply a salt for encryption can use this method to provide it.

Parameters:

password - the password to process

salt - Salt parameter for some crypto algorithms

Returns:

processed password

checkPassword

public boolean checkPassword(java.lang.String checkpw,
                             java.lang.String encpw)

Checks if a supplied password matches the encrypted password when using the current encryption algorithm

Parameters:

checkpw - The clear text password supplied by the user

encpw - The current, encrypted password

Returns:

true if the password matches, else false

changePassword

public void changePassword(User user,
                           java.lang.String oldPassword,
                           java.lang.String newPassword)
                    throws PasswordMismatchException,
                           UnknownEntityException,
                           DataBackendException

Change the password for an User.

Parameters:

user - an User to change password for.

oldPassword - the current password supplied by the user.

newPassword - the current password requested by the user.

Throws:

PasswordMismatchException - if the supplied password was incorrect.

UnknownEntityException - if the user's record does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

forcePassword

public void forcePassword(User user,
                          java.lang.String password)
                   throws UnknownEntityException,
                          DataBackendException

Forcibly sets new password for an User. This is supposed by the administrator to change the forgotten or compromised passwords. Certain implementatations of this feature would require administrative level access to the authenticating server / program.

Parameters:

user - an User to change password for.

password - the new password.

Throws:

UnknownEntityException - if the user's record does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

getACL

public AccessControlList getACL(User user)
                         throws DataBackendException,
                                UnknownEntityException

Constructs an AccessControlList for a specific user.

Parameters:

user - the user for whom the AccessControlList are to be retrieved

Returns:

A new AccessControlList object.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if user account is not present.

getPermissions

public PermissionSet getPermissions(Role role)
                             throws DataBackendException,
                                    UnknownEntityException

Retrieves all permissions associated with a role.

Parameters:

role - the role name, for which the permissions are to be retrieved.

Returns:

the permissions associated with the role

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role is not present.

grant

public void grant(User user,
                  Group group,
                  Role role)
           throws DataBackendException,
                  UnknownEntityException

Grant an User a Role in a Group.

Parameters:

user - the user.

group - the group.

role - the role.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if user account, group or role is not present.

revoke

public void revoke(User user,
                   Group group,
                   Role role)
            throws DataBackendException,
                   UnknownEntityException

Revoke a Role in a Group from an User.

Parameters:

user - the user.

group - the group.

role - the role.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if user account, group or role is not present.

revokeAll

public void revokeAll(User user)
               throws DataBackendException,
                      UnknownEntityException

Revokes all roles from an User. This method is used when deleting an account.

Parameters:

user - the User.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the account is not present.

grant

public void grant(Role role,
                  Permission permission)
           throws DataBackendException,
                  UnknownEntityException

Grants a Role a Permission

Parameters:

role - the Role.

permission - the Permission.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if role or permission is not present.

revoke

public void revoke(Role role,
                   Permission permission)
            throws DataBackendException,
                   UnknownEntityException

Revokes a Permission from a Role.

Parameters:

role - the Role.

permission - the Permission.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if role or permission is not present.

revokeAll

public void revokeAll(Role role)
               throws DataBackendException,
                      UnknownEntityException

Revokes all permissions from a Role. This method is user when deleting a Role.

Parameters:

role - the Role

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the Role is not present.

getGlobalGroup

public Group getGlobalGroup()

Provides a reference to the Group object that represents the global group.

Returns:

A Group object that represents the global group.

getNewGroup

public Group getNewGroup(java.lang.String groupName)

Deprecated. Use getGroupInstance(String name) instead.

getNewRole

public Role getNewRole(java.lang.String roleName)

Deprecated. Use getRoleInstance(String name) instead.

getNewPermission

public Permission getNewPermission(java.lang.String permissionName)

Deprecated. Use getPermissionInstance(String name) instead.

getGroup

public Group getGroup(java.lang.String name)
               throws DataBackendException,
                      UnknownEntityException

Deprecated. Use getGroupByName instead.

Retrieve a Group object with specified name.

Parameters:

name - the name of the Group.

Returns:

an object representing the Group with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the group does not exist.

getGroupByName

public Group getGroupByName(java.lang.String name)
                     throws DataBackendException,
                            UnknownEntityException

Retrieve a Group object with specified name.

Parameters:

name - the name of the Group.

Returns:

an object representing the Group with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the group does not exist.

getGroupById

public Group getGroupById(int id)
                   throws DataBackendException,
                          UnknownEntityException

Retrieve a Group object with specified Id.

Returns:

an object representing the Group with specified name.

Throws:

UnknownEntityException - if the permission does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

getRole

public Role getRole(java.lang.String name)
             throws DataBackendException,
                    UnknownEntityException

Deprecated. Use getRoleByName instead.

Retrieve a Role object with specified name.

Parameters:

name - the name of the Role.

Returns:

an object representing the Role with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role does not exist.

getRoleByName

public Role getRoleByName(java.lang.String name)
                   throws DataBackendException,
                          UnknownEntityException

Retrieve a Role object with specified name.

Parameters:

name - the name of the Role.

Returns:

an object representing the Role with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role does not exist.

getRoleById

public Role getRoleById(int id)
                 throws DataBackendException,
                        UnknownEntityException

Retrieve a Role object with specified Id.

Returns:

an object representing the Role with specified name.

Throws:

UnknownEntityException - if the permission does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

getPermission

public Permission getPermission(java.lang.String name)
                         throws DataBackendException,
                                UnknownEntityException

Deprecated. Use getPermissionByName instead.

Retrieve a Permission object with specified name.

Parameters:

name - the name of the Permission.

Returns:

an object representing the Permission with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the permission does not exist.

getPermissionByName

public Permission getPermissionByName(java.lang.String name)
                               throws DataBackendException,
                                      UnknownEntityException

Retrieve a Permission object with specified name.

Parameters:

name - the name of the Permission.

Returns:

an object representing the Permission with specified name.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the permission does not exist.

getPermissionById

public Permission getPermissionById(int id)
                             throws DataBackendException,
                                    UnknownEntityException

Retrieve a Permission object with specified Id.

Returns:

an object representing the Permission with specified name.

Throws:

UnknownEntityException - if the permission does not exist in the database.

DataBackendException - if there is a problem accessing the storage.

getGroups

public GroupSet getGroups(org.apache.torque.util.Criteria criteria)
                   throws DataBackendException

Retrieve a set of Groups that meet the specified Criteria.

Parameters:

criteria - a Criteria of Group selection.

Returns:

a set of Groups that meet the specified Criteria.

Throws:

DataBackendException - if there was an error accessing the data backend.

getRoles

public RoleSet getRoles(org.apache.torque.util.Criteria criteria)
                 throws DataBackendException

Retrieve a set of Roles that meet the specified Criteria.

Parameters:

criteria - a Criteria of Roles selection.

Returns:

a set of Roles that meet the specified Criteria.

Throws:

DataBackendException - if there was an error accessing the data backend.

getPermissions

public PermissionSet getPermissions(org.apache.torque.util.Criteria criteria)
                             throws DataBackendException

Retrieve a set of Permissions that meet the specified Criteria.

Parameters:

criteria - a Criteria of Permissions selection.

Returns:

a set of Permissions that meet the specified Criteria.

Throws:

DataBackendException - if there was an error accessing the data backend.

getAllGroups

public GroupSet getAllGroups()
                      throws DataBackendException

Retrieves all groups defined in the system.

Returns:

the names of all groups defined in the system.

Throws:

DataBackendException - if there was an error accessing the data backend.

getAllRoles

public RoleSet getAllRoles()
                    throws DataBackendException

Retrieves all roles defined in the system.

Returns:

the names of all roles defined in the system.

Throws:

DataBackendException - if there was an error accessing the data backend.

getAllPermissions

public PermissionSet getAllPermissions()
                                throws DataBackendException

Retrieves all permissions defined in the system.

Returns:

the names of all roles defined in the system.

Throws:

DataBackendException - if there was an error accessing the data backend.

saveGroup

public void saveGroup(Group group)
               throws DataBackendException,
                      UnknownEntityException

Stores Group's attributes. The Groups is required to exist in the system.

Parameters:

group - The Group to be stored.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the group does not exist.

saveRole

public void saveRole(Role role)
              throws DataBackendException,
                     UnknownEntityException

Stores Role's attributes. The Roles is required to exist in the system.

Parameters:

role - The Role to be stored.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role does not exist.

savePermission

public void savePermission(Permission permission)
                    throws DataBackendException,
                           UnknownEntityException

Stores Permission's attributes. The Permission is required to exist in the system.

Parameters:

permission - The Permission to be stored.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the permission does not exist.

addGroup

public Group addGroup(Group group)
               throws DataBackendException,
                      EntityExistsException

Creates a new group with specified attributes.

Parameters:

group - the object describing the group to be created.

Returns:

the new Group object.

Throws:

DataBackendException - if there was an error accessing the data backend.

EntityExistsException - if the group already exists.

addRole

public Role addRole(Role role)
             throws DataBackendException,
                    EntityExistsException

Creates a new role with specified attributes.

Parameters:

role - The object describing the role to be created.

Returns:

the new Role object.

Throws:

DataBackendException - if there was an error accessing the data backend.

EntityExistsException - if the role already exists.

addPermission

public Permission addPermission(Permission permission)
                         throws DataBackendException,
                                EntityExistsException

Creates a new permission with specified attributes.

Parameters:

permission - The object describing the permission to be created.

Returns:

the new Permission object.

Throws:

DataBackendException - if there was an error accessing the data backend.

EntityExistsException - if the permission already exists.

removeGroup

public void removeGroup(Group group)
                 throws DataBackendException,
                        UnknownEntityException

Removes a Group from the system.

Parameters:

group - The object describing the group to be removed.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the group does not exist.

removeRole

public void removeRole(Role role)
                throws DataBackendException,
                       UnknownEntityException

Removes a Role from the system.

Parameters:

role - The object describing the role to be removed.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role does not exist.

removePermission

public void removePermission(Permission permission)
                      throws DataBackendException,
                             UnknownEntityException

Removes a Permission from the system.

Parameters:

permission - The object describing the permission to be removed.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the permission does not exist.

renameGroup

public void renameGroup(Group group,
                        java.lang.String name)
                 throws DataBackendException,
                        UnknownEntityException

Renames an existing Group.

Parameters:

group - The object describing the group to be renamed.

name - the new name for the group.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the group does not exist.

renameRole

public void renameRole(Role role,
                       java.lang.String name)
                throws DataBackendException,
                       UnknownEntityException

Renames an existing Role.

Parameters:

role - The object describing the role to be renamed.

name - the new name for the role.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the role does not exist.

renamePermission

public void renamePermission(Permission permission,
                             java.lang.String name)
                      throws DataBackendException,
                             UnknownEntityException

Renames an existing Permission.

Parameters:

permission - The object describing the permission to be renamed.

name - the new name for the permission.

Throws:

DataBackendException - if there was an error accessing the data backend.

UnknownEntityException - if the permission does not exist.