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:

StructureView, ViewSettings

Method Summary

Modifier and Type	Method and Description
StructureView	createView() Creates an empty new view.
void	deleteView(Long viewId) Deletes a view.
List<Structure>	getAssociatedStructures(Long viewId) Retrieves all structures that are "associated" with the specified view, i.e.
ViewSettings	getDefaultViewSettings() Retrieves the global default view settings, which apply to all structure that don't have view settings overridden.
List<StructureViewMenuItem>	getMenuItems(Long structureId, StructurePage page) This method retrieves a list of entries for the "Views" drop-down menu on the specified page, for the specified structure.
StructureView	getView(Long viewId, PermissionLevel requiredLevel) Retrieves a view specified by the numeric view ID and checks if the current user has the specified access level for that view.
PermissionLevel	getViewPermission(Long viewId, ApplicationUser user) Calculates the access level that the specified user has to the specified view.
List<StructureView>	getViews(PermissionLevel requiredLevel) Retrieves a list of all views that the current user has the specified access level to.
ViewSettings	getViewSettings(Long structureId) Retrieves view settings for the specified structure.
boolean	isAccessible(Long viewId, PermissionLevel level) Checks if the specified view exists and the current user has the given access level to it.
void	makeDefaultForStructure(Long viewId, Long structureId, StructurePage page) Makes the specified view default for the given structure on the given page
void	setDefaultViewSettings(ViewSettings settings) Updates the global default view settings, which apply to all structure that don't have view settings overridden.
void	setViewSettings(Long structureId, ViewSettings settings) Updates view settings for the specified structure.

Method Detail

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:

StructureView.saveChanges()

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:

• StructurePage.STRUCTURE_BOARD
• StructurePage.PROJECT_TAB, StructurePage.VERSION_TAB and StructurePage.COMPONENT_TAB (have the same settings)
• StructurePage.ISSUE_VIEW
• StructurePage.GADGET

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