org.kuali.rice.kim.api.permission
Interface PermissionService

All Known Implementing Classes:

PermissionServiceImpl

public interface PermissionService

This service provides operations for evaluating permissions and querying for permission data.

A permission is the ability to perform an action. All permissions have a permission template. Both permissions and permission templates are uniquely identified by a namespace code plus a name. The permission template defines the course-grained permission and specifies what additional permission details need to be collected on permissions that use that template. For example, a permission template might have a name of "Initiate Document" which requires a permission detail specifying the document type that can be initiated. A permission created from the "Initiate Document" template would define the name of the specific Document Type that can be initiated as a permission detail.

The isAuthorized and isAuthorizedByTemplate operations on this service are used to execute authorization checks for a principal against a permission. Permissions are always assigned to roles (never directly to a principal or group). A particular principal will be authorized for a given permission if the permission evaluates to true (according to the permission evaluation logic and based on any supplied permission details) and that principal is assigned to a role which has been granted the permission.

The actual logic for how permission evaluation logic is defined and executed is dependent upon the permission service implementation. However, it will typically be associated with the permission template used on the permission.

Author:

Kuali Rice Team (rice.collab@kuali.org)

Method Summary

Permission	createPermission(Permission permission) This will create a Permission exactly like the permission passed in.
Permission	findPermByNamespaceCodeAndName(String namespaceCode, String name) Gets a Permission with the unique combination of namespace and name.
PermissionQueryResults	findPermissions(QueryByCriteria queryByCriteria) This method find Permissions based on a query criteria.
List<Permission>	findPermissionsByTemplate(String namespaceCode, String templateName) Return the permissions for the given unique combination of namespace, component and permission template name.
TemplateQueryResults	findPermissionTemplates(QueryByCriteria queryByCriteria) This method find Permission Templates based on a query criteria.
Template	findPermTemplateByNamespaceCodeAndName(String namespaceCode, String name) Finds a Template for namespaceCode and name.
List<Template>	getAllTemplates() Finds a Template for namespaceCode and name.
List<Permission>	getAuthorizedPermissions(String principalId, String namespaceCode, String permissionName, Map<String,String> qualification) Returns permissions (with their details) that are granted to the principal given the passed qualification.
List<Permission>	getAuthorizedPermissionsByTemplate(String principalId, String namespaceCode, String permissionTemplateName, Map<String,String> permissionDetails, Map<String,String> qualification) Returns permissions (with their details) that are granted to the principal given the passed qualification.
Permission	getPermission(String id) Gets a Permission from an id.
List<Assignee>	getPermissionAssignees(String namespaceCode, String permissionName, Map<String,String> qualification) Get the list of principals/groups who have a given permission.
List<Assignee>	getPermissionAssigneesByTemplate(String namespaceCode, String permissionTemplateName, Map<String,String> permissionDetails, Map<String,String> qualification) Get the list of principals/groups who have a given permission that match the given permission template and permission details.
Template	getPermissionTemplate(String id) Gets a Template from an id.
List<String>	getRoleIdsForPermission(String namespaceCode, String permissionName) Get the role IDs for the given permission.
boolean	hasPermission(String principalId, String namespaceCode, String permissionName) Checks in a given principal id has a permission using the passed in permission information.
boolean	hasPermissionByTemplate(String principalId, String namespaceCode, String permissionTemplateName, Map<String,String> permissionDetails) Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account.
boolean	isAuthorized(String principalId, String namespaceCode, String permissionName, Map<String,String> qualification) Checks whether the given qualified permission is granted to the principal given the passed roleQualification.
boolean	isAuthorizedByTemplate(String principalId, String namespaceCode, String permissionTemplateName, Map<String,String> permissionDetails, Map<String,String> qualification) Checks whether the given qualified permission is granted to the principal given the passed roleQualification.
boolean	isPermissionDefined(String namespaceCode, String permissionName) Returns true if the given permission is defined on any Roles.
boolean	isPermissionDefinedByTemplate(String namespaceCode, String permissionTemplateName, Map<String,String> permissionDetails) Returns true if the given permission template is defined on any Roles.
Permission	updatePermission(Permission permission) This will update a Permission.

Method Detail

createPermission

@CacheEvict(value={"http://rice.kuali.org/kim/v2_0/PermissionType","http://rice.kuali.org/kim/v2_0/TemplateType{Permission}"},
            allEntries=true)
Permission createPermission(Permission permission)
                            throws RiceIllegalArgumentException,
                                   RiceIllegalStateException

This will create a Permission exactly like the permission passed in.

Parameters:

permission - the permission to create

Returns:

the newly created object. will never be null.

Throws:

RiceIllegalArgumentException - if the permission is null

RiceIllegalStateException - if the permission is already existing in the system

updatePermission

@CacheEvict(value={"http://rice.kuali.org/kim/v2_0/PermissionType","http://rice.kuali.org/kim/v2_0/TemplateType{Permission}"},
            allEntries=true)
Permission updatePermission(Permission permission)
                            throws RiceIllegalArgumentException,
                                   RiceIllegalStateException

This will update a Permission.

Parameters:

permission - the permission to update

Returns:

the updated object. will never be null

Throws:

RiceIllegalArgumentException - if the permission is null

RiceIllegalStateException - if the permission does not exist in the system

hasPermission

boolean hasPermission(String principalId,
                      String namespaceCode,
                      String permissionName)
                      throws RiceIllegalArgumentException

Checks in a given principal id has a permission using the passed in permission information. This method should not be used for true authorization checks since a principal may only have this permission within a given context. It could be used to identify that the user would have some permissions within a certain area. Later checks would identify exactly what permissions were granted. It can also be used when the client application KNOWS that this is a role which is never qualified.

Parameters:

principalId - the principal id to check. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

Returns:

true is principal has permission

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

isAuthorized

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{isAuthorized}\' + \'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1 + \'|\' + \'permissionName=\' + #p2 + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p3)")
boolean isAuthorized(String principalId,
                               String namespaceCode,
                               String permissionName,
                               Map<String,String> qualification)
                     throws RiceIllegalArgumentException

Checks whether the given qualified permission is granted to the principal given the passed roleQualification. If no roleQualification is passed (null or empty) then this method behaves the same as hasPermission(String, String, String). Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined.

Parameters:

principalId - the principal id to check. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

qualification - the qualifications to test against.

Returns:

true is principal has permission

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

hasPermissionByTemplate

boolean hasPermissionByTemplate(String principalId,
                                String namespaceCode,
                                String permissionTemplateName,
                                Map<String,String> permissionDetails)
                                throws RiceIllegalArgumentException

Checks whether the principal has been granted a permission matching the given details without taking role qualifiers into account. This method should not be used for true authorization checks since a principal may only have this permission within a given context. It could be used to identify that the user would have some permissions within a certain area. Later checks would identify exactly what permissions were granted. It can also be used when the client application KNOWS that this is a role which is never qualified.

Parameters:

principalId - the principal id to check. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionTemplateName - the permission name. cannot be null or blank.

permissionDetails - the permission details

Returns:

true is principal has permission

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

isAuthorizedByTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{isAuthorizedByTemplate}\' + \'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1 + \'|\' + \'permissionTemplateName=\' + #p2 + \'|\' + \'permissionDetails=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p3) + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p4)")
boolean isAuthorizedByTemplate(String principalId,
                                         String namespaceCode,
                                         String permissionTemplateName,
                                         Map<String,String> permissionDetails,
                                         Map<String,String> qualification)
                               throws RiceIllegalArgumentException

Checks whether the given qualified permission is granted to the principal given the passed roleQualification. If no roleQualification is passed (null or empty) then this method behaves the same as hasPermission(String, String, String). Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined. Each permission is checked against the permissionDetails. The PermissionTypeService is called for each permission with the given permissionName to see if the permissionDetails matches its details.

Parameters:

principalId - the principal id to check. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionTemplateName - the permission name. cannot be null or blank.

permissionDetails - the permission details

qualification - the permission qualifications

Returns:

true is principal has permission

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

getPermissionAssignees

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{getPermissionAssignees}\' + \'namespaceCode=\' + #p0 + \'|\' + \'permissionName=\' + #p1 + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p2)")
List<Assignee> getPermissionAssignees(String namespaceCode,
                                                String permissionName,
                                                Map<String,String> qualification)
                                      throws RiceIllegalArgumentException

Get the list of principals/groups who have a given permission. This also returns delegates for the given principals/groups who also have this permission given the context in the qualification parameter. Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined.

Parameters:

namespaceCode - the namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

qualification - the permission qualifications

Returns:

list of assignees that have been assigned the permissions

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

getPermissionAssigneesByTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{getPermissionAssigneesByTemplate}\' + \'namespaceCode=\' + #p0 + \'|\' + \'permissionTemplateName=\' + #p1  + \'permissionDetails=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p2) + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p3)")
List<Assignee> getPermissionAssigneesByTemplate(String namespaceCode,
                                                          String permissionTemplateName,
                                                          Map<String,String> permissionDetails,
                                                          Map<String,String> qualification)
                                                throws RiceIllegalArgumentException

Get the list of principals/groups who have a given permission that match the given permission template and permission details. This also returns delegates for the given principals/groups who also have this permission given the context in the qualification parameter. Each role assigned to the principal is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked first through the role's type service. Once it is determined that the principal has the role in the given context (qualification), the permissions are examined.

Parameters:

namespaceCode - the namespace code. cannot be null or blank.

permissionTemplateName - the permission name. cannot be null or blank.

permissionDetails - the permission details.

qualification - the permission qualifications

Returns:

list of assignees that have been assigned the permissions by template

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode, permissionName is null or blank

isPermissionDefined

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{isPermissionDefined}\' + \'namespaceCode=\' + #p0 + \'|\' + \'permissionName=\' + #p1")
boolean isPermissionDefined(String namespaceCode,
                                      String permissionName)
                            throws RiceIllegalArgumentException

Returns true if the given permission is defined on any Roles.

Parameters:

namespaceCode - the namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

Returns:

true if given permission is defined on any Roles

Throws:

RiceIllegalArgumentException - if the namespaceCode or permissionName is null or blank

isPermissionDefinedByTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{isPermissionDefinedByTemplate}\' + \'namespaceCode=\' + #p0 + \'|\' + \'permissionTemplateName=\' + #p1 + \'|\' + \'permissionDetails=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p2)")
boolean isPermissionDefinedByTemplate(String namespaceCode,
                                                String permissionTemplateName,
                                                Map<String,String> permissionDetails)
                                      throws RiceIllegalArgumentException

Returns true if the given permission template is defined on any Roles.

Parameters:

namespaceCode - the namespace code. cannot be null or blank.

permissionTemplateName - the permission name. cannot be null or blank.

permissionDetails - the permission template details

Returns:

true if given permission template is defined on any Roles

Throws:

RiceIllegalArgumentException - if the namespaceCode or permissionName is null or blank

getAuthorizedPermissions

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{getAuthorizedPermissions}\' + \'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1 + \'|\' + \'permissionName=\' + #p2 + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p3)")
List<Permission> getAuthorizedPermissions(String principalId,
                                                    String namespaceCode,
                                                    String permissionName,
                                                    Map<String,String> qualification)
                                          throws RiceIllegalArgumentException

Returns permissions (with their details) that are granted to the principal given the passed qualification. If no qualification is passed (null or empty) then this method does not check any qualifications on the roles. After the permissions are determined, the roles that hold those permissions are determined. Each role that matches between the principal and the permission objects is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked through the role's type service.

Parameters:

principalId - the principal Id. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

qualification - the permission qualifications

Returns:

list of permissions that are authorized with the given parameters

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode or permissionName is null or blank

getAuthorizedPermissionsByTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'{getAuthorizedPermissionsByTemplate}\' + \'principalId=\' + #p0 + \'|\' + \'namespaceCode=\' + #p1 + \'|\' + \'permissionTemplateName=\' + #p2 + \'|\' + \'permissionDetails=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p3) + \'|\' + \'qualification=\' + T(org.kuali.rice.core.api.cache.CacheKeyUtils).key(#p4)")
List<Permission> getAuthorizedPermissionsByTemplate(String principalId,
                                                              String namespaceCode,
                                                              String permissionTemplateName,
                                                              Map<String,String> permissionDetails,
                                                              Map<String,String> qualification)
                                                    throws RiceIllegalArgumentException

Returns permissions (with their details) that are granted to the principal given the passed qualification. If no qualification is passed (null or empty) then this method does not check any qualifications on the roles. All permissions with the given name are checked against the permissionDetails. The PermissionTypeService is called for each permission to see if the permissionDetails matches its details. An asterisk (*) as a value in any permissionDetails key-value pair will match any value. This forms a way to provide a wildcard to obtain multiple permissions in one call. After the permissions are determined, the roles that hold those permissions are determined. Each role that matches between the principal and the permission objects is checked for qualifications. If a qualifier exists on the principal's membership in that role, that is checked through the role's type service.

Parameters:

principalId - the principal Id. cannot be null or blank.

namespaceCode - the namespace code. cannot be null or blank.

permissionTemplateName - the permission name. cannot be null or blank.

permissionDetails - the permission template details.

qualification - the permission qualifications

Returns:

list of permissions that are authorized with the given parameters

Throws:

RiceIllegalArgumentException - if the principalId, namespaceCode or permissionTemplateName is null or blank

getPermission

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'id=\' + #p0")
Permission getPermission(String id)

Gets a Permission from an id.

This method will return null if the permission does not exist.

Parameters:

id - the unique id to retrieve the permission by. cannot be null or blank.

Returns:

a Permission or null

Throws:

RiceIllegalArgumentException - if the id is null or blank

findPermByNamespaceCodeAndName

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'namespaceCode=\' + #p0 + \'|\' + \'name=\' + #p1")
Permission findPermByNamespaceCodeAndName(String namespaceCode,
                                                    String name)
                                          throws RiceIllegalArgumentException

Gets a Permission with the unique combination of namespace and name.

This method will return null if the permission does not exist.

Parameters:

namespaceCode - namespace code for permission. cannot be null or blank.

name - name of permission. cannot be null or blank.

Returns:

a Permission or null

Throws:

RiceIllegalArgumentException - if the namespaceCode or name is null or blank

findPermissionsByTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/PermissionType",
           key="\'namespaceCode=\' + #p1 + \'|\' + \'templateName=\' + #p2")
List<Permission> findPermissionsByTemplate(String namespaceCode,
                                                     String templateName)
                                           throws RiceIllegalArgumentException

Return the permissions for the given unique combination of namespace, component and permission template name.

Parameters:

namespaceCode - namespace code for permission. cannot be null or blank.

templateName - name of permission template. cannot be null or blank.

Returns:

a list of Permission or null

Throws:

RiceIllegalArgumentException - if the namespaceCode or name is null or blank

getPermissionTemplate

@Cacheable(value="http://rice.kuali.org/kim/v2_0/TemplateType{Permission}",
           key="\'id=\' + #p0")
Template getPermissionTemplate(String id)
                               throws RiceIllegalArgumentException

Gets a Template from an id.

This method will return null if the template does not exist.

Parameters:

id - the unique id to retrieve the template by. cannot be null or blank.

Returns:

a Template or null

Throws:

RiceIllegalArgumentException - if the id is null or blank

findPermTemplateByNamespaceCodeAndName

@Cacheable(value="http://rice.kuali.org/kim/v2_0/TemplateType{Permission}",
           key="\'namespaceCode=\' + #p0 + \'|\' + \'name=\' + #p1")
Template findPermTemplateByNamespaceCodeAndName(String namespaceCode,
                                                          String name)
                                                throws RiceIllegalArgumentException

Finds a Template for namespaceCode and name.

Parameters:

namespaceCode - the namespace code. cannot be null or blank.

name - the template name. cannot be null or blank.

Returns:

a Template or null

Throws:

RiceIllegalArgumentException - if the id or namespaceCode is null or blank

getAllTemplates

@Cacheable(value="http://rice.kuali.org/kim/v2_0/TemplateType{Permission}",
           key="\'all\'")
List<Template> getAllTemplates()

Finds a Template for namespaceCode and name.

Returns:

a list of Template or an empty list if none found

getRoleIdsForPermission

List<String> getRoleIdsForPermission(String namespaceCode,
                                     String permissionName)
                                     throws RiceIllegalArgumentException

Get the role IDs for the given permission.

Parameters:

namespaceCode - the permission namespace code. cannot be null or blank.

permissionName - the permission name. cannot be null or blank.

Returns:

a list of role Ids, or an empty list if none found

Throws:

RiceIllegalArgumentException - if the namespaceCode or permissionName is null or blank

findPermissions

PermissionQueryResults findPermissions(QueryByCriteria queryByCriteria)
                                       throws RiceIllegalArgumentException

This method find Permissions based on a query criteria. The criteria cannot be null.

Parameters:

queryByCriteria - the criteria. Cannot be null.

Returns:

query results. will never return null.

Throws:

RiceIllegalArgumentException - if the queryByCriteria is null

findPermissionTemplates

TemplateQueryResults findPermissionTemplates(QueryByCriteria queryByCriteria)
                                             throws RiceIllegalArgumentException

This method find Permission Templates based on a query criteria. The criteria cannot be null.

Parameters:

queryByCriteria - the criteria. Cannot be null.

Returns:

query results. will never return null.

Throws:

RiceIllegalArgumentException - if the queryByCriteria is null