Package com.almworks.jira.structure.api

Interface StructurePluginHelper

@Internal public interface StructurePluginHelper

StructurePluginHelper is a helper component that provides a lot of helpful methods and which is extensively used by Structure plugin itself and by Structure extensions.

As a consumer of Structure API, you can also benefit from using these methods, however, since this class is marked @Internal, you may need to retest or recompile your code with every new minor or micro release of the Structure API.

The methods in this class form several groups:

  • Quick access to components,
  • Permission and access checks,
  • Web resource utilities for building pages that include Structure widget,
  • Searching and filtering utilities,
  • I18n tools,
  • Caching and lifecycle tools,
  • Miscellaneous helper methods.

  • Method Details

    • getIssueError

      @Nullable StructureError getIssueError(@Nullable Long issue, boolean checkEdit, @Nullable ApplicationUser user)
      Checks user access to the issue for viewing or editing. Edit check includes verifying that issue editing is not prohibited by workflow.
      Parameters:
      issue - issue ID
      checkEdit - if true, edit permissions are required.
      user - user to check for
      Returns:
      specific error or null if everything is ok

    • getIssueError

      @Nullable default StructureError getIssueError(@Nullable Long issue, boolean checkEdit)
      Convenience method to check issue access for the current user.
      Parameters:
      issue - issue ID
      checkEdit - if true, edit permissions are required.
      Returns:
      specific error or null if everything is ok
      See Also:

    • getIssueError

      @Contract("null, _, _, _ -> !null") @Nullable StructureError getIssueError(@Nullable Issue issue, boolean checkEdit, boolean checkProjectEnabledForStructure, @Nullable ApplicationUser user)
      Checks user access to the issue for viewing or editing. Edit check includes verifying that issue editing is not prohibited by workflow. Also can check if the project that the issue belongs to is enabled for Structure.
      Parameters:
      issue - issue
      checkEdit - if true, edit permissions are required
      checkProjectEnabledForStructure - if true, issue's project must be enabled for Structure
      user - user to check for
      Returns:
      specific error or null if everything is ok

    • getIssueError

      @Contract("null, _ -> !null") @Nullable default StructureError getIssueError(@Nullable Issue issue, boolean checkEdit)
      Convenience method to check issue access for the current user.
      Parameters:
      issue - issue
      checkEdit - if true, edit permissions are required
      Returns:
      specific error or null if everything is ok
      See Also:

    • getIssueError

      @Contract("null, _, _ -> !null") @Nullable default StructureError getIssueError(@Nullable Issue issue, boolean checkEdit, boolean checkProjectEnabledForStructure)
      Convenience method to check issue access for the current user.
      Parameters:
      issue - issue
      checkEdit - if true, edit permissions are required
      checkProjectEnabledForStructure - if true, issue's project must be enabled for Structure
      Returns:
      specific error or null if everything is ok
      See Also:

    • isProjectStructuredForCurrentUser

      boolean isProjectStructuredForCurrentUser(@Nullable Project project)
      Checks if the project is enabled for Structure and the current user can see it.
      Parameters:
      project - the project
      Returns:
      true if the project is "structured" and visible to the current user

    • isStructureAvailableToUser

      default boolean isStructureAvailableToUser(@Nullable ApplicationUser user)
      Checks if the given user is allowed to work with Structure add-on.
      Returns:
      true if the given user can work with Structure

    • isStructureAvailableToCurrentUser

      default boolean isStructureAvailableToCurrentUser()
      Checks if the current user is allowed to work with Structure add-on.
      Returns:
      true if the current user can work with Structure

    • isCreateStructureAllowed

      default boolean isCreateStructureAllowed(@Nullable ApplicationUser user)
      Checks if the given user is allowed to create new structures.

    • isSynchronizationAllowed

      default boolean isSynchronizationAllowed(@Nullable ApplicationUser user)
      Checks if the given user is allowed to create and run synchronizers.

    • isAutomationAccessAllowed

      default boolean isAutomationAccessAllowed(@Nullable ApplicationUser user)
      Checks if the given user is allowed to create and run generators.

    • isManageGlobalSavedColumnsAllowed

      default boolean isManageGlobalSavedColumnsAllowed(@Nullable ApplicationUser user)
      Checks if the given user is allowed to manage global saved columns.

    • isAllowed

      boolean isAllowed(@NotNull StructureAppPermission permission, @Nullable ApplicationUser user)
      Checks if the given user allowed to perform the action guarded by the given permission.
      See Also:

    • isAuthenticated

      default boolean isAuthenticated()
      Checks if the current user has authenticated in the system.
      Returns:
      true if the current user is not anonymous

    • isAdmin

      boolean isAdmin(@Nullable ApplicationUser user)
      Checks if the given user is a Jira administrator (but not necessarily "System Administrator"!).
      Returns:
      true if the given user is an admin.

    • isAdmin

      default boolean isAdmin()
      Checks if the current user is a Jira administrator (but not necessarily "System Administrator"!).
      Returns:
      true if the current user is an admin.

    • isSystemAdmin

      boolean isSystemAdmin(@Nullable ApplicationUser user)
      Checks if the given user is a Jira system administrator.
      Parameters:
      user - the user to check
      Returns:
      true if the given user is not null and a Jira system administrator.

    • isSystemAdmin

      default boolean isSystemAdmin()
      Checks if the current user is a Jira system administrator.
      Returns:
      true if the current user is a Jira system administrator.

    • isViewCreationAllowed

      boolean isViewCreationAllowed(@Nullable ApplicationUser user)
      Checks if the given user can create new views.

    • isViewSharingAllowed

      boolean isViewSharingAllowed(@Nullable ApplicationUser user)
      Checks if the given user can share views.

    • isIssueEditable

      boolean isIssueEditable(@Nullable Issue issue, @Nullable ApplicationUser user)
      Checks if the issue can be edited by the given user. Besides permissions, the issue may be non-editable because of workflow.
      Parameters:
      issue - issue in question
      user - user to make the edit
      Returns:
      true if the user can now edit the issue

    • hasPermission

      boolean hasPermission(@NotNull GlobalPermissionKey permission, @Nullable ApplicationUser user)
      Checks if the given user has the given global permission.
      Parameters:
      permission - global permission
      user - user in question
      Returns:
      true if permission is granted

    • hasPermission

      boolean hasPermission(@NotNull ProjectPermissionKey permission, @Nullable Issue issue, @Nullable ApplicationUser user)
      Checks if the given user has the given project-level permission on an issue's project.
      Parameters:
      permission - project permission from ProjectPermissions
      issue - an issue
      user - user in question
      Returns:
      true if permission is granted

    • hasPermission

      boolean hasPermission(@NotNull ProjectPermissionKey permission, @Nullable Project project, @Nullable ApplicationUser user)
      Checks if the given user has the given project-level permission on a project.
      Parameters:
      permission - project permission from ProjectPermissions
      project - a project
      user - user in question
      Returns:
      true if permission is granted

    • getUser

      @Nullable ApplicationUser getUser()
      Retrieves the current user.
      Returns:
      current user
      See Also:

    • getAvailableGroups

      @NotNull List<Group> getAvailableGroups(@Nullable ApplicationUser user)
      Retrieves the security groups that the user is allowed to see. JIRA admin is allowed to see all groups. All non-admin users are allowed to see the groups they are in.
      Parameters:
      user - user
      Returns:
      groups that the user is allowed to see

    • getAvailableGroupsForCurrentUser

      @NotNull default List<Group> getAvailableGroupsForCurrentUser()
      Retrieves the security groups that the current user is allowed to see. JIRA admin is allowed to see all groups. All non-admin users are allowed to see the groups they are in.
      Returns:
      groups that the current user is allowed to see

    • getAvailableRoles

      @NotNull List<ProjectRole> getAvailableRoles()
      Retrieves the roles that exist in the system. The returned list is owned by the caller and may be modified.

    • getStructureProjectsForCurrentUser

      @NotNull List<Project> getStructureProjectsForCurrentUser()
      Retrieves the list of projects that are enabled for structure and visible to the current user. The returned list is owned by the caller and may be modified.

    • getProjectsForCurrentUser

      @NotNull List<Project> getProjectsForCurrentUser()
      Retrieves the list of projects that are visible to the current user. The returned list is owned by the caller and may be modified. The returned projects may not be enabled for structure.

    • getAuthenticationContext

      @NotNull JiraAuthenticationContext getAuthenticationContext()

    • getIssueManager

      @NotNull IssueManager getIssueManager()

    • getPermissionManager

      @NotNull PermissionManager getPermissionManager()

    • getPluginAccessor

      @NotNull PluginAccessor getPluginAccessor()

    • getEventManager

      @NotNull PluginEventManager getEventManager()

    • getProjectManager

      @NotNull ProjectManager getProjectManager()

    • getProjectRoleManager

      @NotNull ProjectRoleManager getProjectRoleManager()

    • getUserManager

      @NotNull UserManager getUserManager()

    • getJqlStringSupport

      @NotNull JqlStringSupport getJqlStringSupport()

    • getJqlQueryParser

      @NotNull JqlQueryParser getJqlQueryParser()

    • getSearchService

      @NotNull SearchService getSearchService()

    • getJqlOperandResolver

      @NotNull JqlOperandResolver getJqlOperandResolver()

    • getSearchRequestManager

      @NotNull SearchRequestManager getSearchRequestManager()

    • getGlobalPermissionManager

      @NotNull GlobalPermissionManager getGlobalPermissionManager()

    • getTimeTrackingConfiguration

      @NotNull TimeTrackingConfiguration getTimeTrackingConfiguration()

    • getUserPreferencesManager

      @NotNull UserPreferencesManager getUserPreferencesManager()

    • getCustomFieldManager

      @NotNull CustomFieldManager getCustomFieldManager()

    • requireWidgetResource

      void requireWidgetResource()
      Requires all resources needed to render Structure Widget.

    • requireLocalizedResource

      void requireLocalizedResource(@NotNull String resourceKey)

      Requires a resource that may be localized. A localized version of the resource will have _locale suffix in its key - for example, com.almworks.jira.structure:my-resource_de

      The locale of current user is used to load the resource. If such resource is missing, nothing happens.

      Parameters:
      resourceKey - base resource key

    • requireResource

      void requireResource(@NotNull String resourceKey)
      Marks resource as needed for loading. Must be called before a page starts being rendered. If resource is missing, JIRA logs a warning but rendering continues.
      Parameters:
      resourceKey - resource key

    • requireResourceIfPresent

      void requireResourceIfPresent(String resourceKey)
      Marks resource as needed for loading, if the resource exists. If the resource is missing, nothing happens. Must be called before a page starts being rendered.
      Parameters:
      resourceKey - resource key
      See Also:

    • requireIssueDetailsResources

      void requireIssueDetailsResources()
      Loads resources needed for the issue details layout.

    • requireResourcesForContext

      void requireResourcesForContext(String context)
      Loads resources associated with a context
      Parameters:
      context - context name

    • requireQuickEditResources

      void requireQuickEditResources()
      Loads resources needed for "quick edit" code to work (dialog with editing / creating an issue).

    • requireIssueShortcuts

      void requireIssueShortcuts()
      Loads resources needed for standard JIRA keyboard shortcuts.

    • getStaticResourcePrefix

      String getStaticResourcePrefix()
      Returns a URL prefix for 'system' static resources.

    • filterInvisibleProjects

      void filterInvisibleProjects(@Nullable LongSizedIterable projects, @Nullable ApplicationUser user, boolean overrideSecurity, @NotNull LongCollector invisibleCollector)
      Used to figure out which projects are not visible to the user. The list of project IDs may contain non-existent IDs - they will also be reported as invisible.
      Parameters:
      projects - list of project IDs
      user - the user
      overrideSecurity - if true, permissions don't matter, only project existence is checked
      invisibleCollector - a collector to get the IDs of invisible projects

    • searchQuery

      @NotNull LongArray searchQuery(@Nullable String query) throws SearchException, JqlParseException
      Runs JQL search.
      Parameters:
      query - JQL (empty or null string will result in empty result)
      Returns:
      IDs of matching issues
      Throws:
      SearchException - if search problem happened
      JqlParseException - if JQL is invalid

    • searchQuery

      @NotNull LongArray searchQuery(@Nullable Query query) throws SearchException
      Runs search.
      Parameters:
      query - query
      Returns:
      IDs of matching issues
      Throws:
      SearchException - if search problem happened

    • searchAndSortQuery

      @NotNull LongArray searchAndSortQuery(@Nullable String query) throws SearchException, JqlParseException
      Runs JQL search with sorting.
      Parameters:
      query - JQL (empty or null string will result in empty result)
      Returns:
      IDs of matching issues
      Throws:
      SearchException - if search problem happened
      JqlParseException - if JQL is invalid

    • searchAndSortQuery

      @NotNull LongArray searchAndSortQuery(@Nullable Query query) throws SearchException
      Runs search with sorting.
      Parameters:
      query - query
      Returns:
      IDs of matching issues
      Throws:
      SearchException - if search problem happened

    • searchAndSortQuery

      @NotNull LongArray searchAndSortQuery(@Nullable Query query, int limit) throws SearchException
      Runs search with sorting and result count limit.
      Parameters:
      query - query
      limit - maximum number of issues in the result
      Returns:
      IDs of matching issues
      Throws:
      SearchException - if search problem happened

    • matchIssues

      void matchIssues(@Nullable LongList issues, @Nullable Query query, boolean collectMatching, @NotNull LongCollector collector) throws SearchException

      Passes the issues through JIRA search engine and lets the caller collect either all matching or non-matching issues.

      The implementation sorts issues and splits them up into chunks (of 100+ ids each) and creates a JQL query for each. This has proven to be a quick method of checking. However, if the number of issues is likely to be the same order of magnitude as the full result of the query, it's better to run the full query and compare result with the list.

      The issues are checked to be accessible for the current user - so no need to run additional BROWSE permission checks. You can quickly check which issues among the list are visible to the user by running matchIssues() with null query.

      If it is certain that the issue list is sorted, it's more efficient to call matchIssuesSorted(com.almworks.integers.LongList, com.atlassian.query.Query, boolean, com.almworks.integers.LongCollector).

      If you need to skip checking for the user access or check access for non-current user, use {@link com.almworks.jira.structure.api.auth.StructureAuth#sudo)}.

      Parameters:
      query - query to check against. If null, the issues are only checked to be visible to the user and to the Structure plugin
      issues - issue IDs
      collectMatching - if true, collector will receive the issues that match query and visible to the user; if false, collector will receive non-matching issues
      collector - an instance for receiving the results. Chunks are processed in order, for each chunk the (non-)matching issues are added. No guarantees are made for the order of the results inside the same chunk.
      Throws:
      SearchException - if a bad thing happens

    • matchIssuesSorted

      void matchIssuesSorted(@Nullable LongList issuesSorted, @Nullable Query query, boolean collectMatching, LongCollector collector) throws SearchException

      Passes the issues, sorted by their IDs, through JIRA search engine to collect matching or non-matching issues.

      This is more efficient method than matchIssues(com.almworks.integers.LongList, com.atlassian.query.Query, boolean, com.almworks.integers.LongCollector) if you already have IDs sorted.

      Parameters:
      issuesSorted - issues list
      query - additional query
      collectMatching - if true, collector receives matching issues, if false, collector receives non-matching issues.
      collector - the collector
      Throws:
      SearchException - if a bad thing happens
      See Also:

    • matchIssuesSorted

      void matchIssuesSorted(@Nullable LongList issuesSorted, @Nullable Query query, boolean collectMatching, @Nullable ApplicationUser user, boolean overrideSecurity, LongCollector collector) throws SearchException
      A variation of matchIssuesSorted(LongList, Query, boolean, LongCollector) that lets you specify the user and override security checks.
      Parameters:
      issuesSorted - issues list
      query - additional query
      collectMatching - if true, collector receives matching issues, if false, collector receives non-matching issues.
      user - the user that will be used to check access
      overrideSecurity - if true, user access will not be checked
      collector - the collector
      Throws:
      SearchException - if a bad thing happens
      See Also:

    • validateQuery

      @NotNull MessageSet validateQuery(ApplicationUser user, Query query)
      Checks if the query is valid and that the user has access to all the things mentioned in the query.
      Parameters:
      user - user
      query - query
      Returns:
      a collection of error messages

    • getConfigurationScopeQuery

      @Nullable default Query getConfigurationScopeQuery()
      Retrieves a query that limits scope to the projects enabled for Structure. You can use that query to combine with whatever business logic query you have.
      Returns:
      configuration query ("project in ...") or null if Structure is allowed for all projects
      See Also:

    • getI18n

      @NotNull I18nHelper getI18n(@Nullable ApplicationUser user)
      Retrieves i18n helper for a concrete user.
      Parameters:
      user - the user
      Returns:
      i18n helper

    • getI18n

      @NotNull default I18nHelper getI18n()
      Retrieves i18n helper for the current user.

    • getStructureComparator

      @NotNull Comparator<Structure> getStructureComparator(@Nullable ApplicationUser user)
      Returns comparator for sorting structures by name, according to the given user's locale.
      Parameters:
      user - the user to take locale from
      Returns:
      a comparator that can be used to sort structures

    • getCollator

      @NotNull Collator getCollator(@Nullable ApplicationUser user)
      Returns a collator for strings in the user's locale.
      Parameters:
      user - the user
      Returns:
      collator

    • getLocale

      @NotNull Locale getLocale()
      Returns the current user's locale.

    • getCacheHelper

      StructureCacheHelper getCacheHelper()

    • isStructureLocked

      boolean isStructureLocked()
      Returns true when Structure cannot be used because it is locked, either for full restore or for system startup.

    • getIssue

      @Nullable Issue getIssue(long issueId)
      Retrieves an instance of Issue.
      Parameters:
      issueId - the ID of the issue
      Returns:
      the issue, or null if the issue cannot be found or there is an exception getting it

    • getIssue

      @Nullable Issue getIssue(String key)
      Retrieves an instance of issue by issue key.
      Parameters:
      key - issue key
      Returns:
      the issue, or null if the issue cannot be found or there is an exception getting it

    • getConfiguration

      @NotNull StructureConfiguration getConfiguration()
      Retrieves StructureConfiguration

    • instantiate

      <T> T instantiate(@NotNull Class<T> clazz)
      Creates a new instance of the given class, injecting all dependencies into the constructor. Those dependencies may include other Structure's services or system services.
      Type Parameters:
      T - type parameter
      Parameters:
      clazz - class to be instantiated
      Returns:
      created instance