com.atlassian.jira.application

Interface ApplicationRoleManager

All Known Implementing Classes:

DefaultApplicationRoleManager, MockApplicationRoleManager

public interface ApplicationRoleManager

Provides low-level read and write capabilities regarding ApplicationRoles. It is generally recommended to use ApplicationAuthorizationService or ApplicationRoleAdminService rather than this class, as the service layer contains additional validation and business logic.

Since:

7.0

See Also:

ApplicationAuthorizationService, ApplicationRoleAdminService, ApplicationRole

Method Summary

Modifier and Type	Method and Description
Set<com.atlassian.application.api.ApplicationKey>	getDefaultApplicationKeys() Returns an immutable Set of ApplicationKeys that are configured as the default applications for new users.
Set<com.atlassian.crowd.embedded.api.Group>	getDefaultGroups(com.atlassian.application.api.ApplicationKey key) Get the default Groups associated with the ApplicationRole backed by a (potentially exceeded) license.
Set<ApplicationRole>	getDefaultRoles() Deprecated. Use getDefaultApplicationKeys() instead. Since v7.0
Set<com.atlassian.crowd.embedded.api.Group>	getGroupsForLicensedRoles() Get the Set of group names that have been associated with all the ApplicationRoles that have a backing (but potentially exceeded) license.
Set<ApplicationRole>	getOccupiedLicenseRolesForUser(ApplicationUser user) Returns the Set of ApplicationRoles that the given ApplicationUser occupies seats in.
int	getRemainingSeats(com.atlassian.application.api.ApplicationKey key) Retrieve the number of available (unoccupied) user seats for the ApplicationRole backed by a (potentially exceeded) license.
int	getRemainingSeatsAsync(com.atlassian.application.api.ApplicationKey key) Async version of getRemainingSeats(ApplicationKey).
io.atlassian.fugue.Option<ApplicationRole>	getRole(com.atlassian.application.api.ApplicationKey key) Returns the ApplicationRole identified by the given ApplicationKey, or Option.none() if no such ApplicationRole exists.
Set<ApplicationRole>	getRoles() Returns an immutable Set of all ApplicationRoles that are backed by a (potentially exceeded) license.
Set<ApplicationRole>	getRolesForGroup(com.atlassian.crowd.embedded.api.Group group) Returns the Set of ApplicationRoles associated with the given Group, or groups for which the given group is a nested group (sub-group).
Set<ApplicationRole>	getRolesForUser(ApplicationUser user) Returns the Set of ApplicationRoles granted to the given ApplicationUser.
int	getUserCount(com.atlassian.application.api.ApplicationKey key) Retrieve the number of active users for the given ApplicationRole.
int	getUserCountAsync(com.atlassian.application.api.ApplicationKey key) Async version of getUserCount(ApplicationKey).
boolean	hasAnyRole(ApplicationUser user) Returns true if the given user has been assigned to any ApplicationRole that is backed by a (potentially exceeded) license.
boolean	hasExceededAllRoles(ApplicationUser user) Returns true if the user limits of all of the given user's assigned ApplicationRoles have been exceeded.
boolean	hasExceededAllRolesAsync(ApplicationUser user) Async version of hasExceededAllRoles(ApplicationUser).
boolean	hasSeatsAvailable(com.atlassian.application.api.ApplicationKey key, int seatCount) Determines whether the ApplicationRole backed by a license has the requested number of user seats available.
boolean	hasSeatsAvailableAsync(com.atlassian.application.api.ApplicationKey key, int seatCount) Async version of hasSeatsAvailable(ApplicationKey, int).
boolean	isAnyRoleLimitExceeded() Returns true if the number of users assigned to any ApplicationRole exceeds the number of seats granted to that role by its license.
boolean	isAnyRoleLimitExceededAsync() Async version of isAnyRoleLimitExceeded().
boolean	isRoleInstalledAndLicensed(com.atlassian.application.api.ApplicationKey key) Determines whether an application identified by the given ApplicationKey is installed and running in this JIRA instance AND has a backing license key.
boolean	isRoleLimitExceeded(com.atlassian.application.api.ApplicationKey role) Returns true if the number of users assigned to the given ApplicationRole exceeds the number of seats granted by its license.
boolean	isRoleLimitExceededAsync(com.atlassian.application.api.ApplicationKey role) Async version of isRoleLimitExceeded(ApplicationKey).
void	removeGroupFromRoles(com.atlassian.crowd.embedded.api.Group group) Removes any/all associations of the given group from all ApplicationRoles (irrespective of whether the ApplicationRoles is backed by a license).
default boolean	rolesEnabled() Deprecated. since 7.0.1 as this always returns true in JIRA 7
ApplicationRole	setRole(ApplicationRole role) Save the passed ApplicationRole information to the database.
boolean	userHasRole(ApplicationUser user, com.atlassian.application.api.ApplicationKey key) Returns true if the passed user belongs to the ApplicationRole associated with the given key.
boolean	userOccupiesRole(ApplicationUser user, com.atlassian.application.api.ApplicationKey key) Returns true if the passed user occupies a seat in the ApplicationRole associated with the given key.

Method Detail

getRole

@Nonnull
io.atlassian.fugue.Option<ApplicationRole> getRole(@Nonnull
                                                            com.atlassian.application.api.ApplicationKey key)

Returns the ApplicationRole identified by the given ApplicationKey, or Option.none() if no such ApplicationRole exists.

Note: ApplicationRoles returned by this method are guaranteed to be backed by a (potentially exceeded) license, however the installation state of the plugin/product that uses this role may not necessarily physically installed.

Parameters:

key - the ApplicationKey of the role to search for.

Returns:

the ApplicationRole associated with the passed role identifier, or Option.none().

getRoles

@Nonnull
Set<ApplicationRole> getRoles()

Returns an immutable Set of all ApplicationRoles that are backed by a (potentially exceeded) license.

Returns:

the Set of all ApplicationRoles that are backed by a (potentially exceeded) license.

getDefaultRoles

@Nonnull
 @Deprecated
 @ExperimentalApi
Set<ApplicationRole> getDefaultRoles()

Deprecated. Use getDefaultApplicationKeys() instead. Since v7.0

Returns an immutable Set of ApplicationRoles that are configured be default for new users.

Returns:

the Set of ApplicationRoles that are configured be default for new users.

getDefaultApplicationKeys

@Nonnull
Set<com.atlassian.application.api.ApplicationKey> getDefaultApplicationKeys()

Returns an immutable Set of ApplicationKeys that are configured as the default applications for new users.

Returns:

the Set of ApplicationKeys that are configured as the default applications for new users.

See Also:

for defaul roles.

hasAnyRole

boolean hasAnyRole(@Nullable
                   ApplicationUser user)

Returns true if the given user has been assigned to any ApplicationRole that is backed by a (potentially exceeded) license.

Returns:

true if the given user has been assigned to any ApplicationRole that is backed by a (potentially exceeded) license.

userHasRole

boolean userHasRole(@Nullable
                    ApplicationUser user,
                    com.atlassian.application.api.ApplicationKey key)

Returns true if the passed user belongs to the ApplicationRole associated with the given key. NOTE: This does not check that the application is licensed with a valid license.

Parameters:

user - the user to check - if this is null, returns false

key - the key corresponding to the ApplicationRole

Returns:

true if the user belongs to a group of the given application

userOccupiesRole

boolean userOccupiesRole(@Nullable
                         ApplicationUser user,
                         com.atlassian.application.api.ApplicationKey key)

Returns true if the passed user occupies a seat in the ApplicationRole associated with the given key.

Parameters:

user - the user to check - if this is null, returns false

key - the key corresponding to the ApplicationRole

Returns:

true if the user occupies seat in the given application

hasExceededAllRoles

boolean hasExceededAllRoles(@Nonnull
                            ApplicationUser user)

Returns true if the user limits of all of the given user's assigned ApplicationRoles have been exceeded. The user limit of an ApplicationRole is exceeded when the combined number of users assigned to that role (through assigned groups) exceeds the number of seats granted for that role in its license.

Note: this method does NOT take into account whether licenses for application roles are expired; this must be tested separately.

The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use hasExceededAllRolesAsync(ApplicationUser) async version of the method}

Parameters:

user - the user whose roles will be checked.

Returns:

true if all of the user's roles have user counts that exceed the number of seats granted by licenses.

hasExceededAllRolesAsync

boolean hasExceededAllRolesAsync(@Nonnull
                                 ApplicationUser user)

Async version of hasExceededAllRoles(ApplicationUser). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Returns true if the user limits of all of the given user's assigned ApplicationRoles have been exceeded. The user limit of an ApplicationRole is exceeded when the combined number of users assigned to that role (through assigned groups) exceeds the number of seats granted for that role in its license.

Note: this method does NOT take into account whether licenses for application roles are expired; this must be tested separately.

Parameters:

user - the user whose roles will be checked.

Returns:

true if all of the user's roles have user counts that exceed the number of seats granted by licenses.

isAnyRoleLimitExceeded

boolean isAnyRoleLimitExceeded()

Returns true if the number of users assigned to any ApplicationRole exceeds the number of seats granted to that role by its license.

The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use isAnyRoleLimitExceededAsync() async version of the method} Note: this method does NOT take into account whether licenses for installed roles are expired; this must be tested separately.

Returns:

true if the number of users for any role is greater than the number of seats granted to that role by its license.

isAnyRoleLimitExceededAsync

boolean isAnyRoleLimitExceededAsync()

Async version of isAnyRoleLimitExceeded(). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Returns true if the number of users assigned to any ApplicationRole exceeds the number of seats granted to that role by its license.

Note: this method does NOT take into account whether licenses for installed roles are expired; this must be tested separately.

Returns:

true if the number of users for any role is greater than the number of seats granted to that role by its license.

isRoleLimitExceeded

boolean isRoleLimitExceeded(@Nonnull
                            com.atlassian.application.api.ApplicationKey role)

Returns true if the number of users assigned to the given ApplicationRole exceeds the number of seats granted by its license. This method unconditionally returns false if the passed role is not considered to be installed (ie: backed by a license).

Note: this method does NOT take into account whether licenses for installed roles are expired; this must be tested separately.

The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use async version of the method

Parameters:

role - the identifier of the ApplicationRole.

Returns:

true if the installed ApplicationRole is exceeded or false otherwise.

isRoleLimitExceededAsync

boolean isRoleLimitExceededAsync(@Nonnull
                                 com.atlassian.application.api.ApplicationKey role)

Async version of isRoleLimitExceeded(ApplicationKey). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Returns true if the number of users assigned to the given ApplicationRole exceeds the number of seats granted by its license. This method unconditionally returns false if the passed role is not considered to be installed (ie: backed by a license).

Note: this method does NOT take into account whether licenses for installed roles are expired; this must be tested separately.

Parameters:

role - the identifier of the ApplicationRole.

Returns:

true if the installed ApplicationRole is exceeded or false otherwise.

getRolesForUser

Set<ApplicationRole> getRolesForUser(@Nonnull
                                     ApplicationUser user)

Returns the Set of ApplicationRoles granted to the given ApplicationUser.

Parameters:

user - the user whose roles will be checked.

Returns:

the Set of ApplicationRoles for the given user.

getOccupiedLicenseRolesForUser

Set<ApplicationRole> getOccupiedLicenseRolesForUser(@Nonnull
                                                    ApplicationUser user)

Returns the Set of ApplicationRoles that the given ApplicationUser occupies seats in. ApplicationUser has to actively take a seat in the returned ApplicationRoles eg. for an ApplicationUser who has access to SOFTWARE and implicitly (or explicitly) CORE, they will only have SOFTWARE returned. For an ApplicationUser who has explicit access to SOFTWARE and CORE - with the SOFTWARE license exceeded, this will return both as the user effectively occupies a seat in both CORE and SOFTWARE now.

Parameters:

user - the user whose roles will be checked.

Returns:

the Set of ApplicationRoles that the given user is actively taking seats.

getRolesForGroup

Set<ApplicationRole> getRolesForGroup(@Nonnull
                                      com.atlassian.crowd.embedded.api.Group group)

Returns the Set of ApplicationRoles associated with the given Group, or groups for which the given group is a nested group (sub-group).

Parameters:

group - the group which roles will be checked.

Returns:

the Set of ApplicationRoles associated with the group or its super-groups.

getGroupsForLicensedRoles

@Nonnull
Set<com.atlassian.crowd.embedded.api.Group> getGroupsForLicensedRoles()

Get the Set of group names that have been associated with all the ApplicationRoles that have a backing (but potentially exceeded) license.

Returns:

Groups associated with all the ApplicationRoles that have a backing (but potentially exceeded) license.

removeGroupFromRoles

void removeGroupFromRoles(@Nonnull
                          com.atlassian.crowd.embedded.api.Group group)

Removes any/all associations of the given group from all ApplicationRoles (irrespective of whether the ApplicationRoles is backed by a license).

Parameters:

group - the group to remove.

isRoleInstalledAndLicensed

boolean isRoleInstalledAndLicensed(@Nonnull
                                   com.atlassian.application.api.ApplicationKey key)

Determines whether an application identified by the given ApplicationKey is installed and running in this JIRA instance AND has a backing license key.

Parameters:

key - the key that identifies the ApplicationRole backed by a (potentially exceeded) license.

Returns:

true when the ApplicationRole backed by a (potentially exceeded) license has an associated application installed and running in this JIRA instance.

setRole

@Nonnull
ApplicationRole setRole(@Nonnull
                                 ApplicationRole role)

Save the passed ApplicationRole information to the database. This method will only accept the passed role if:

1. The role is backed by a (potentially exceeded) license.
2. The role only contains currently valid groups.
3. The default group are not a subset of the groups in the role.

Parameters:

role - the role to save.

Returns:

the role as persisted to the database.

Throws:

IllegalArgumentException - if passed role does not contain valid groups, valid default groups or if the role does not have a backing license.

getUserCount

int getUserCount(@Nonnull
                 com.atlassian.application.api.ApplicationKey key)

Retrieve the number of active users for the given ApplicationRole. It will uniquely count all users who are found in the groups associated with the application. The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use getUserCountAsync(ApplicationKey) async version of the method}

Parameters:

key - the key that identifies the ApplicationRole.

Returns:

the number of active users for the given ApplicationRole, or zero if the ApplicationRole does not exist.

getUserCountAsync

int getUserCountAsync(@Nonnull
                      com.atlassian.application.api.ApplicationKey key)

Async version of getUserCount(ApplicationKey). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Retrieve the number of active users for the given ApplicationRole. It will uniquely count all users who are found in the groups associated with the application.

Parameters:

key - the key that identifies the ApplicationRole.

Returns:

the number of active users for the given ApplicationRole, or zero if the ApplicationRole does not exist.

getRemainingSeats

int getRemainingSeats(@Nonnull
                      com.atlassian.application.api.ApplicationKey key)

Retrieve the number of available (unoccupied) user seats for the ApplicationRole backed by a (potentially exceeded) license. The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use getRemainingSeatsAsync(ApplicationKey) async version of the method}

Parameters:

key - the key that identifies the licensed ApplicationRole.

Returns:

the number of remaining users seats. Will return zero when there are more users than seats licensed, the ApplicationRole is not valid or there are as many active users as seats in the license. When the license is unlimited, it will return minus one (-1)

See Also:

for finding occupied user seats.

getRemainingSeatsAsync

int getRemainingSeatsAsync(@Nonnull
                           com.atlassian.application.api.ApplicationKey key)

Async version of getRemainingSeats(ApplicationKey). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Retrieve the number of available (unoccupied) user seats for the ApplicationRole backed by a (potentially exceeded) license.

Parameters:

key - the key that identifies the licensed ApplicationRole.

Returns:

the number of remaining users seats. Will return zero when there are more users than seats licensed, the ApplicationRole is not valid or there are as many active users as seats in the license. When the license is unlimited, it will return minus one (-1)

See Also:

for finding occupied user seats.

hasSeatsAvailable

boolean hasSeatsAvailable(@Nonnull
                          com.atlassian.application.api.ApplicationKey key,
                          int seatCount)

Determines whether the ApplicationRole backed by a license has the requested number of user seats available. The method is known to be slow in some circumstances, and to block Jira instance. It's strongly recommended to use hasSeatsAvailableAsync(ApplicationKey, int) async version of the method}

Parameters:

key - the key that identifies the ApplicationRole.

seatCount - the number of user seats that this ApplicationRole should have capacity for.

Returns:

true if the ApplicationRole for the provided ApplicationKey has the number of user seats available. false if the there are not enough seats available.

hasSeatsAvailableAsync

boolean hasSeatsAvailableAsync(@Nonnull
                               com.atlassian.application.api.ApplicationKey key,
                               int seatCount)

Async version of hasSeatsAvailable(ApplicationKey, int). The method returns the last know value without waiting for the current changes to be propagated. This implementation is safer and offers a better performance. Determines whether the ApplicationRole backed by a license has the requested number of user seats available.

Parameters:

key - the key that identifies the ApplicationRole.

seatCount - the number of user seats that this ApplicationRole should have capacity for.

Returns:

true if the ApplicationRole for the provided ApplicationKey has the number of user seats available. false if the there are not enough seats available.

getDefaultGroups

@Nonnull
Set<com.atlassian.crowd.embedded.api.Group> getDefaultGroups(@Nonnull
                                                                      com.atlassian.application.api.ApplicationKey key)

Get the default Groups associated with the ApplicationRole backed by a (potentially exceeded) license.

Parameters:

key - the key that identifies the ApplicationRole.

Returns:

the Set of default groups associated with the ApplicationRole.

rolesEnabled

@Internal
 @Deprecated
default boolean rolesEnabled()

Deprecated. since 7.0.1 as this always returns true in JIRA 7

Determines whether ApplicationRoles are enabled.

Returns:

true when ApplicationRole are enabled, false otherwise.