com.atlassian.jira.security.roles
Interface ProjectRoleManager

public interface ProjectRoleManager

This class allows us to CRUD ProjectRoles. A Project Role is way of grouping the users associated with a project (eg 'Testers', 'Developers').

Nested Class Summary

static class

ProjectRoleManager.ProjectIdToProjectRoleIdsMap This class implements is backed by the map with project ID as a key and a collection of project role IDs as the mapped value of the map.

Method Summary

void	applyDefaultsRolesToProject(Project project) This method will insert all the default roles into the role associations for the provided project.
ProjectRoleManager.ProjectIdToProjectRoleIdsMap	createProjectIdToProjectRolesMap(com.atlassian.crowd.embedded.api.User user, Collection<Long> projectIds)
ProjectRoleManager.ProjectIdToProjectRoleIdsMap	createProjectIdToProjectRolesMap(User user, Collection<Long> projectIds) Deprecated. Please use createProjectIdToProjectRolesMap(com.atlassian.crowd.embedded.api.User, java.util.Collection). Since v4.3
ProjectRole	createRole(ProjectRole projectRole) Creates a project role object
void	deleteRole(ProjectRole projectRole) Deletes a project role object
DefaultRoleActors	getDefaultRoleActors(ProjectRole projectRole) This method will return the default role actors for a ProjectRole
Collection<Long>	getProjectIdsContainingRoleActorByNameAndType(String name, String type) Returns the project id's which contain a role actor of the specified name and type within any role.
Map<Long,List<String>>	getProjectIdsForUserInGroupsBecauseOfRole(List<Long> projectsToLimitBy, ProjectRole projectRole, String projectRoleType, String userName) Returns a Map of Lists.
ProjectRole	getProjectRole(Long id) Retrieves a project role object
ProjectRole	getProjectRole(String name) Retrieves a project role object by name
ProjectRoleActors	getProjectRoleActors(ProjectRole projectRole, Project project) This method will retrieve the object that represents the actors associate with the given projectRole and project context
Collection<ProjectRole>	getProjectRoles() Get all the ProjectRoles available in JIRA.
Collection<ProjectRole>	getProjectRoles(com.atlassian.crowd.embedded.api.User user, Project project) This will return all the ProjectRoles that the user is currently a member of for the given project.
Collection<ProjectRole>	getProjectRoles(User user, Project project) Deprecated. Please use getProjectRoles(com.atlassian.crowd.embedded.api.User, com.atlassian.jira.project.Project). Since v4.3
boolean	isRoleNameUnique(String name) Will tell you if a role name exists or not.
boolean	isUserInProjectRole(com.atlassian.crowd.embedded.api.User user, ProjectRole projectRole, Project project) Returns true only if the given user is in the given project role for the given project.
boolean	isUserInProjectRole(User user, ProjectRole projectRole, Project project) Deprecated. Please use isUserInProjectRole(com.atlassian.crowd.embedded.api.User, ProjectRole, com.atlassian.jira.project.Project). Since v4.3
void	removeAllRoleActorsByNameAndType(String name, String type) This will remove all role actors with the specified name and the specified type.
void	removeAllRoleActorsByProject(Project project) Will remove all role actors associated with the specified project.
List<Long>	roleActorOfTypeExistsForProjects(List<Long> projectsToLimitBy, ProjectRole projectRole, String projectRoleType, String projectRoleParameter) Returns a list of projectId's for which the role actor of the specified type exists in the project for the provided projectRole.
void	updateDefaultRoleActors(DefaultRoleActors defaultRoleActors) This method will update the associations of actors for the default projectRole, specified by the given defaultRoleActors object.
void	updateProjectRoleActors(ProjectRoleActors projectRoleActors) Commits the given ProjectRoleActors to permanent store, saving any updates made.
void	updateRole(ProjectRole projectRole) Updates a project role object

Method Detail

getProjectRoles

Collection<ProjectRole> getProjectRoles()

Get all the ProjectRoles available in JIRA. Currently this list is global.

Returns:

The global list of project roles in JIRA

getProjectRoles

Collection<ProjectRole> getProjectRoles(com.atlassian.crowd.embedded.api.User user,
                                        Project project)

This will return all the ProjectRoles that the user is currently a member of for the given project.

Parameters:

user - the user

project - the project

Returns:

a Collection of ProjectRoles.

Throws:

IllegalArgumentException - is thrown if the project is null

getProjectRoles

Collection<ProjectRole> getProjectRoles(User user,
                                        Project project)

Deprecated. Please use getProjectRoles(com.atlassian.crowd.embedded.api.User, com.atlassian.jira.project.Project). Since v4.3

This will return all the ProjectRoles that the user is currently a member of for the given project.

Parameters:

user - the user

project - the project

Returns:

a Collection of ProjectRoles.

Throws:

IllegalArgumentException - is thrown if the project is null

getProjectRole

ProjectRole getProjectRole(Long id)

Retrieves a project role object

Parameters:

id -

Returns:

the project role based on the id or null if it doesn't exist.

Throws:

IllegalArgumentException - is thrown if the id is null

getProjectRole

ProjectRole getProjectRole(String name)

Retrieves a project role object by name

Parameters:

name -

Returns:

the project role based on the name or null if it doesn't exist.

Throws:

IllegalArgumentException - is thrown if the name is null, or an empty String

createRole

ProjectRole createRole(ProjectRole projectRole)

Creates a project role object

Parameters:

projectRole - the project role to create, if the id field is non-null then this will be ignored. Only the roles name and description are used by this method.

Returns:

the created project role object

Throws:

IllegalArgumentException - is thrown if projectRole or projectRole.getName are null

isRoleNameUnique

boolean isRoleNameUnique(String name)

Will tell you if a role name exists or not.

Parameters:

name - the name of the project role to check

Returns:

true if unique, false if one already exists with that name

deleteRole

void deleteRole(ProjectRole projectRole)

Deletes a project role object

Parameters:

projectRole -

Throws:

IllegalArgumentException - is thrown if the projectRole is null

updateRole

void updateRole(ProjectRole projectRole)

Updates a project role object

Parameters:

projectRole -

Throws:

IllegalArgumentException - is thrown if the projectRole or projectRole.getName() is null

getProjectRoleActors

ProjectRoleActors getProjectRoleActors(ProjectRole projectRole,
                                       Project project)

This method will retrieve the object that represents the actors associate with the given projectRole and project context

Parameters:

projectRole -

project -

Returns:

the projectRoleActors object for the given projectRole and project context

Throws:

IllegalArgumentException - if the given projectRole or project is null

updateProjectRoleActors

void updateProjectRoleActors(ProjectRoleActors projectRoleActors)

Commits the given ProjectRoleActors to permanent store, saving any updates made.

Parameters:

projectRoleActors -

Throws:

IllegalArgumentException - if the given projectRoleActors is null or the projectRoleActors project, projectRole or roleActors is null.

getDefaultRoleActors

DefaultRoleActors getDefaultRoleActors(ProjectRole projectRole)

This method will return the default role actors for a ProjectRole

Parameters:

projectRole -

Throws:

IllegalArgumentException - will be thrown if ProjectRole is null

updateDefaultRoleActors

void updateDefaultRoleActors(DefaultRoleActors defaultRoleActors)

This method will update the associations of actors for the default projectRole, specified by the given defaultRoleActors object. The actors will be updated to reflect the state of the roleActors set contained within the given defaultRoleActors object.

Parameters:

defaultRoleActors -

Throws:

IllegalArgumentException - if the given defaultRoleActors is null or the projectRole or roleActors is null.

applyDefaultsRolesToProject

void applyDefaultsRolesToProject(Project project)

This method will insert all the default roles into the role associations for the provided project. If one of the default actors is already associated with the project, we will leave that association. NOTE: This method is meant to only be called immediatly after a project is created.

Parameters:

project - the project to associate the role defaults with

Throws:

IllegalArgumentException - if project

removeAllRoleActorsByNameAndType

void removeAllRoleActorsByNameAndType(String name,
                                      String type)

This will remove all role actors with the specified name and the specified type. This method should be used to clean up after the actual subject of the role actor has been deleted (ex. deleting a user from the system).

Parameters:

name - this is the name that the role actor is stored under (ex. username of 'admin', group name of 'jira-users')

type - this is the role type parameter, (ex. GroupRoleActor.TYPE, UserRoleActor.TYPE)

Throws:

IllegalArgumentException - if name or type is null

removeAllRoleActorsByProject

void removeAllRoleActorsByProject(Project project)

Will remove all role actors associated with the specified project. This method should be used to clean up just before the actual project has been deleted (ex. deleting a project from the system).

Parameters:

project - this is the project that the role actors are associated with

Throws:

IllegalArgumentException - if the project is null

isUserInProjectRole

boolean isUserInProjectRole(com.atlassian.crowd.embedded.api.User user,
                            ProjectRole projectRole,
                            Project project)

Returns true only if the given user is in the given project role for the given project. This could be because they are a member of a particular group (groups can be in roles) as well as being a user in a role.

Parameters:

user - The user to check. If user is null, this will implicitly return false.

projectRole - The role.

project - The project.

Returns:

true if the User is in the role.

Throws:

IllegalArgumentException - if ProjectRole or Project is null.

isUserInProjectRole

boolean isUserInProjectRole(User user,
                            ProjectRole projectRole,
                            Project project)

Deprecated. Please use isUserInProjectRole(com.atlassian.crowd.embedded.api.User, ProjectRole, com.atlassian.jira.project.Project). Since v4.3

Returns true only if the given user is in the given project role for the given project. This could be because they are a member of a particular group (groups can be in roles) as well as being a user in a role.

Parameters:

user - The user to check. If user is null, this will implicitly return false.

projectRole - The role.

project - The project.

Returns:

true if the User is in the role.

Throws:

IllegalArgumentException - if ProjectRole or Project is null.

getProjectIdsContainingRoleActorByNameAndType

Collection<Long> getProjectIdsContainingRoleActorByNameAndType(String name,
                                                               String type)

Returns the project id's which contain a role actor of the specified name and type within any role. This is a method that is provided so that you can efficiently tell which users or groups have been associated with any role within projects.

Parameters:

name - this is the name that the role actor is stored under (ex. username of 'admin', group name of 'jira-users')

type - this is the role type parameter, (ex. GroupRoleActor.TYPE, UserRoleActor.TYPE)

Returns:

a collection of Long project id's which have a role which contains the role actor with the specified name and type.

roleActorOfTypeExistsForProjects

List<Long> roleActorOfTypeExistsForProjects(List<Long> projectsToLimitBy,
                                            ProjectRole projectRole,
                                            String projectRoleType,
                                            String projectRoleParameter)

Returns a list of projectId's for which the role actor of the specified type exists in the project for the provided projectRole. This is a method that is meant to efficiently allow discovery of whether a UserRoleActor exists in a project role for a subset of projects.

Parameters:

projectsToLimitBy - this will limit the range of projects the method queries. This is a list of Long, project id's. The returned list will be either the same as this list or a subset.

projectRole - the project role to find out if an actor is a member of.

projectRoleType - the type of role actor you want to query for, in most cases this will be UserRoleActor.TYPE.

projectRoleParameter - the parameter describing the role actor, in the case of a UserRoleActor this will be the username.

Returns:

A list of Long, project id's. If a projectId is in this list then the project contains has a role associated for the passed in actor and project role.

getProjectIdsForUserInGroupsBecauseOfRole

Map<Long,List<String>> getProjectIdsForUserInGroupsBecauseOfRole(List<Long> projectsToLimitBy,
                                                                 ProjectRole projectRole,
                                                                 String projectRoleType,
                                                                 String userName)

Returns a Map of Lists. The key of the map is a Long, project id and the value of the map is a list of group names that the user is a member of for the project. This method is meant to provide an efficient means to discover which groups that are associated with a project role implicitly include the specified user in that project role. We allow you to specify a range of projectsToLimitBy so that you can perform only one query to find this information for many projects for a single projectRole.

Parameters:

projectsToLimitBy - this will limit the range of projects the method queries. This is a list of Long, project id's. The returned list will be either the same as this list or a subset.

projectRole - the project role to find out if an actor is a member of.

projectRoleType - the type of role actor you want to query for, in most cases this will be UserRoleActor.TYPE.

userName - the username to find out if the user is in the role because of a group

Returns:

Returns a Map of Lists. The key of the map is a Long, project id and the value of the map is a list of group names that the user is a member of for the project.

createProjectIdToProjectRolesMap

ProjectRoleManager.ProjectIdToProjectRoleIdsMap createProjectIdToProjectRolesMap(com.atlassian.crowd.embedded.api.User user,
                                                                                 Collection<Long> projectIds)

createProjectIdToProjectRolesMap

ProjectRoleManager.ProjectIdToProjectRoleIdsMap createProjectIdToProjectRolesMap(User user,
                                                                                 Collection<Long> projectIds)

Deprecated. Please use createProjectIdToProjectRolesMap(com.atlassian.crowd.embedded.api.User, java.util.Collection). Since v4.3