Package com.almworks.jira.structure.api.view

Interface StructureViewManager

@PublicApi public interface StructureViewManager

StructureViewManager is a component that manages Structure views.

A view is a collection of visual configuration parameters that define how Structure grid looks like. (Initially, a view defines only the columns used in the grid, but we intend to expand the notion of view in the future versions.)

Managing views and structures have a lot in common. This service provides methods for retrieving and updating views, like StructureManager does for structures. StructureView, the interface that represents a view, is very similar to the Structure interface.

Besides views, this service also manages view settings for individual structures, as well as global view settings. View settings define which views are offered in the drop-down menus on different pages with Structure grid, and which views are used by default.

Unless otherwise stated, all methods are thread-safe. Note that the methods of the StructureView interface are not thread-safe - you need to retrieve an instance of StructureView, do the work with it in one thread, and forget it.

All methods can accept null arguments for convenience. null structure ID or view ID means the same as an ID of a missing structure or view.

All methods operate in the authentication context as defined by StructureAuth. By default, this context coincides with the JIRA authentication context.

Author:
Igor Sereda
See Also:

  • Method Details

    • getView

      @NotNull StructureView getView(@Nullable Long viewId, @Nullable PermissionLevel requiredLevel) throws StructureException

      Retrieves a view specified by the numeric view ID and checks if the current user has the specified access level for that view.

      Unless security checks are disabled, the user is also checked for being allowed to use Structure plugin at all.

      Parameters:
      viewId - the ID of the view
      requiredLevel - when checking for user's permission, require that the user has at least the specified access level. Passing null or PermissionLevel.NONE effectively disables view permissions check, but the user will be checked for being allowed to use Structure plugin.
      Returns:
      an instance of the view, not null
      Throws:
      StructureException - if the view is not found, or the user is not allowed to use Structure plugin, or the user does not have the required access level to this view, or if any other problem is encountered

    • getViews

      @NotNull List<StructureView> getViews(@Nullable PermissionLevel requiredLevel)

      Retrieves a list of all views that the current user has the specified access level to.

      This method never throws an exception, but it may return an empty list if the user does not have access to any view.

      Parameters:
      requiredLevel - when checking for user's permission, require that the user has at least the specified permission for every view in the returned list. Passing null or PermissionLevel.NONE effectively disables the view permissions check, but the user will be checked for being allowed to use Structure plugin.
      Returns:
      a list of views available to the user, not null

    • getViewPermission

      @NotNull PermissionLevel getViewPermission(@Nullable Long viewId, @Nullable ApplicationUser user)
      Calculates the access level that the specified user has to the specified view. Note that the authentication context doesn't influence this method.
      Parameters:
      viewId - the ID of the view
      user - the user, or null for anonymous
      Returns:
      the access level. If the view does not exist or viewId is null, the result is PermissionLevel.NONE

    • isAccessible

      boolean isAccessible(@Nullable Long viewId, @Nullable PermissionLevel level)

      Checks if the specified view exists and the current user has the given access level to it.

      If security checks are disabled, the method only checks that the specified view exists.

      Parameters:
      viewId - the ID of the view
      level - required access level. Passing null or PermissionLevel.NONE effectively disables the view permissions check, but the user will be checked for being allowed to use Structure plugin.
      Returns:
      true if the specified view is accessible

    • createView

      @NotNull StructureView createView()
      Creates an empty new view. The view returned is not yet persisted - you need to call the required setter methods and then call StructureView.saveChanges() to write the new view to the database.
      Returns:
      the instance of the new view, not persisted to the database
      See Also:

    • deleteView

      void deleteView(@Nullable Long viewId) throws StructureException

      Deletes a view.

      Note that when a view is deleted, it's not removed from the ViewSettings automatically, but that must not be a problem since every time the settings are used, the views must be filtered for accessibility by the user.

      the current user must have PermissionLevel.ADMIN access level to the view being deleted.

      Parameters:
      viewId - the ID of the view being removed
      Throws:
      StructureException - if deletion could not succeed

    • getViewSettings

      @NotNull ViewSettings getViewSettings(@Nullable Long structureId) throws StructureException

      Retrieves view settings for the specified structure. View settings define the associated views, which are offered to the users in the "Views" drop-down.

      Unless setViewSettings(java.lang.Long, com.almworks.jira.structure.api.view.ViewSettings) was previously called for a structure, the structure has default view settings. Use ViewSettings.isDefined() to check if view settings for the view has been adjusted from default.

      Unless security checks are disabled, the method checks that the current user has access to the specified structure. Note that everyone has access to the global default view settings.

      Note that retrieved ViewSettings may contain views that are not available for the user. Before serving the views, make sure the user has at least VIEW access to them. See also method getMenuItems(java.lang.Long, com.almworks.jira.structure.api.settings.StructurePage), which checks each view for accessibility.

      Parameters:
      structureId - the ID of the structure
      Returns:
      view settings
      Throws:
      StructureException - if the user does not have VIEW access to the structure or structure does not exist

    • setViewSettings

      void setViewSettings(@Nullable Long structureId, @Nullable ViewSettings settings) throws StructureException

      Updates view settings for the specified structure.

      Unless security checks are disabled, the current user must have ADMIN access level for the structure.

      If settings parameter is null, the settings for the structure are "cleared" and will inherit the global default settings.

      Note that ViewSettings may contain views that are not available for a user, or even deleted views. Before serving the views, make sure the user has at least VIEW access to them.

      Parameters:
      structureId - the ID of the structure
      settings - the settings or null to reset settings to default
      Throws:
      StructureException - if the user does not have the required permissions for this change

    • getDefaultViewSettings

      @NotNull ViewSettings getDefaultViewSettings()

      Retrieves the global default view settings, which apply to all structure that don't have view settings overridden.

      Everyone has read access to the global default view settings.

      Returns:
      global default view settings

    • setDefaultViewSettings

      void setDefaultViewSettings(@Nullable ViewSettings settings) throws StructureException

      Updates the global default view settings, which apply to all structure that don't have view settings overridden.

      Only JIRA administrators may make this change.

      If null is passed as settings, the default view settings will be cleared, that is, they won't contain any associated views.

      Parameters:
      settings - the new global view settings
      Throws:
      StructureException - if the user does not have the required permissions for this change

    • getMenuItems

      @NotNull List<StructureViewMenuItem> getMenuItems(@Nullable Long structureId, @Nullable StructurePage page)

      This method retrieves a list of entries for the "Views" drop-down menu on the specified page, for the specified structure. A menu item is basically a pair of StructureView and boolean, with the latter signifying that the view is the default.

      Note that due to the way default views are defined, there might be several default views in this "menu". The order of menu items matches the order of associated views in the corresponding ViewSettings but the first entry that has true StructureViewMenuItem.isPreferred() is moved at the beginning of the list so the calling method typically chooses this entry as default.

      The current user must have at least VIEW access to the specified structure, or the method will fail.

      At the moment, the following pages are supported:

      All other pages will default to StructurePage.STRUCTURE_BOARD.

      Parameters:
      structureId - the ID of the structure, for which the menu list is retrieved
      page - page type for which the menu is being built
      Returns:
      a list of menu items, may be empty

    • getAssociatedStructures

      @NotNull List<Structure> getAssociatedStructures(@Nullable Long viewId) throws StructureException

      Retrieves all structures that are "associated" with the specified view, i.e. structures that have overridden view settings that include the view.

      This method returns only structures that the current user can at least view.

      Breaking change

      Prior to Structure API 10.0, this method also returned all structures that have default view settings if the specified view was used in the default view settings. This is no longer the case, for performance reasons. If you absolutely need to get the old behaviour, you can simulate that by retrieving all structures that the user can view from StructureManager and checking if their view settings are defined.

      Parameters:
      viewId - the ID of the view
      Returns:
      a list of structures that are associated with the specified view, perhaps empty
      Throws:
      StructureException - if the user does not have access to the specified view

    • makeDefaultForStructure

      void makeDefaultForStructure(@Nullable Long viewId, @Nullable Long structureId, @Nullable StructurePage page) throws StructureException

      Makes the specified view default for the given structure on the given page

      If the given view is not associated with the structure it will be added to the associated views list at the first place and to the list of menu items for the given structure and the given page.

      The given page will be removed from the ViewSettings.AssociatedView.getDefaultPages() set for all associated views for the given structure

      Unless security checks are disabled, the current user must have ADMIN access level for the structure and at least VIEW access for the view.

      Parameters:
      viewId - the ID of the view. Nullable for convenience - if null, throws StructureException
      structureId - the ID of the structure. Nullable for convenience - if null, throws StructureException
      page - page type for making the specified view default. StructurePage.STRUCTURE_BOARD is used when page is not supported or is null
      Throws:
      StructureException - if the view is not found, or the user does not have access to the specified view or the structure