Package 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:

  • Method Details

    • 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.

    • 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.

    • 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:

    • 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:

    • 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.