@PublicApi
public interface StructureView
StructureView
represents a view - a named collection of parameters (such as grid columns) that are used
to configure how Structure widget displays a structure.
The main property of a StructureView
is view specification, which defines the visual configuration.
Other properties - id, name, description, permissions and owner - help manage the views.
You typically get an instance of StructureView
by calling get...
methods of StructureViewManager
.
Like Structure
, an instance of StructureView
is mutable — you can change its properties, but to
have changes take effect you need to save them using saveChanges()
.
To create a new view, call StructureViewManager.createView()
to get
an empty StructureView
instance, call set...
methods to set the properties (at least, view name and view specification must be set)
and then call saveChanges()
.
When saveChanges
has completed, the new View has been created and you can use getId()
to get the
new view's ID.
Like structures, views also have an owner and a set of permission rules. The similar access level calculation
algorithm applies for the views, except that PermissionRule.ApplyStructure
rules are ignored.
Access level applied to view has the following meaning:
PermissionLevel.NONE
- the view is not accessible for the user.PermissionLevel.VIEW
- the user can apply this view when viewing any structure. The user can adjust the
visual configuration in the browser by, say, adding columns, but they won't be able to save the changes as the new view specification.PermissionLevel.EDIT
- the user can use the view and also change its specification (save the adjustments they made in browser).
The user won't be able to change other properties of the view, like name or permissions.PermissionLevel.ADMIN
- the user can make any change of the view or delete it.Instances of classes implementing this interface have reference equality: their equals()
and hashCode()
behave in the same way as Object
's.
The implementations of this interface are not thread-safe. Every thread must obtain their
own copy of the StructureView
instance. Moreover, every time you need an
instance of StructureView
, you should get it from the StructureViewManager
because the properties might have changed or the view might have been deleted.
StructureViewManager
Modifier and Type | Method and Description |
---|---|
String |
getDescription()
Returns the description of the view or an empty string if description was not set
|
PermissionLevel |
getEffectivePermission(ApplicationUser user)
Calculates access level to this view for the specified user.
|
long |
getId()
Returns the ID of the view, or
0 if the view has no ID (when it's new and hasn't been saved yet). |
String |
getName()
Returns the name of the view or an empty string if the view name has not been set yet
|
ApplicationUser |
getOwner()
Returns the owner of the view, or
null if the view has no owner. |
List<PermissionRule> |
getPermissions()
Used to get permissions rules that are used to calculate user's access level.
|
ViewSpecification |
getSpecification()
Returns the view specification, which defines the visual configuration of the widget
|
boolean |
isPublic()
Checks if the view is "public", that is, everyone has at least
VIEW access to it. |
boolean |
isShared()
Checks if the view is "shared", that is, the permission rules give at least
VIEW access to someone. |
StructureView |
makePublic()
Convenience method that modifies the view's permission rules, making it viewable by anyone.
|
StructureView |
saveChanges()
Call this method to save the changes made with
set... methods and update the database. |
StructureView |
setDescription(String description)
Sets the description of the view.
|
StructureView |
setName(String name)
Sets the name of the view.
|
StructureView |
setOwner(ApplicationUser owner)
Sets the owner of the view.
|
StructureView |
setPermissions(Collection<? extends PermissionRule> permissions)
Sets the permission rules for this view.
|
StructureView |
setSpecification(ViewSpecification.Builder specification)
Sets the specification of the view, which defines the visual configuration of the gadget.
|
StructureView |
setSpecification(ViewSpecification specification)
Sets the specification of the view, which defines the visual configuration of the gadget.
|
StructureView |
update(StructureViewBean.Builder builder)
Updates the properties that have been set (have non-null value) in the passed builder.
|
long getId()
0
if the view has no ID (when it's new and hasn't been saved yet).@NotNull String getName()
@NotNull String getDescription()
@NotNull ViewSpecification getSpecification()
ViewSpecification
@Nullable ApplicationUser getOwner()
null
if the view has no owner. In the latter case, it is manageable
by JIRA administrators, or whoever has PermissionLevel.ADMIN
access to it.@NotNull List<PermissionRule> getPermissions()
Structure
, the last matching rule defines the access level.@NotNull PermissionLevel getEffectivePermission(@Nullable ApplicationUser user)
Calculates access level to this view for the specified user. If the user is not allowed to use Structure plugin,
the result will always be PermissionLevel.NONE
.
This method does not take into account pending changes to the permissions list made through setPermissions(java.util.Collection<? extends com.almworks.jira.structure.api.permissions.PermissionRule>)
method call, until they are committed to the database with saveChanges()
.
This method does not take into account authentication context
.
user
- the user, null means anonymousStructureViewManager.getViewPermission(java.lang.Long, com.atlassian.jira.user.ApplicationUser)
boolean isShared()
Checks if the view is "shared", that is, the permission rules give at least VIEW
access to someone.
If the view is not shared, only the owner and JIRA administrators have access to it.
Note that a redundant rule, such as assigning the owner a permission level (although the owner always has
ADMIN
access) will make this view "shared", although technically it still will be "private".
This method takes into account the pending changes to permissions made through setPermissions(java.util.Collection<? extends com.almworks.jira.structure.api.permissions.PermissionRule>)
.
boolean isPublic()
VIEW
access to it.
This method takes into account the pending changes to permissions made through setPermissions(java.util.Collection<? extends com.almworks.jira.structure.api.permissions.PermissionRule>)
.
@NotNull StructureView setName(@Nullable String name)
Sets the name of the view. Although it is possible to set name to null, it is an invalid value
and saveChanges
will throw an error when called, unless a non-null name is set.
To store the changed information in the database, use saveChanges()
.
name
- view name; null
is interpreted as "don't change"@NotNull StructureView setDescription(@Nullable String description)
Sets the description of the view.
To store the changed information in the database, use saveChanges()
.
description
- view description; null
is interpreted as "don't change"@NotNull StructureView setOwner(@Nullable ApplicationUser owner)
Sets the owner of the view.
To store the changed information in the database, use saveChanges()
.
owner
- new owner. null
is interpreted as "don't change".@NotNull StructureView setPermissions(@Nullable Collection<? extends PermissionRule> permissions)
Sets the permission rules for this view. Like with Structure
, permission rules are evaluated in the specified order
and the last matching rule defines the access level to the view for the given user.
View owner and JIRA administrators always have PermissionLevel.ADMIN
access level.
Currently only PermissionRule.SetLevel
rules are allowed for views.
To store the changed information in the database, use saveChanges()
. At this point, the specified rules are validated, and
StructureException
is thrown if any of them is found invalid.
permissions
- a collection of permissions. null
is interpreted as "don't change"@NotNull StructureView setSpecification(@Nullable ViewSpecification specification)
Sets the specification of the view, which defines the visual configuration of the gadget.
This method is intended for cases where you already have a ready specification that needs to be
saved in a view. If you are building a specification, consider using setSpecification(ViewSpecification.Builder)
}.
To store the changed information in the database, use saveChanges()
.
specification
- view specification. null
is interpreted as "don't change"@NotNull StructureView setSpecification(@Nullable ViewSpecification.Builder specification)
Sets the specification of the view, which defines the visual configuration of the gadget.
This method is intended for cases where you build a new specification or adjust an existing specification via
ViewSpecification.Builder
. If you already have a ready instance of ViewSpecification
, you can
set it with setSpecification(ViewSpecification)
.
To store the changed information in the database, use saveChanges()
.
specification
- view specification. null
is interpreted as "don't change"@NotNull StructureView update(@Nullable StructureViewBean.Builder builder)
StructureViewBean
for details on the builder.
To store the changed information in the database, use saveChanges()
.
builder
- the builder with view properties@NotNull StructureView makePublic()
Convenience method that modifies the view's permission rules, making it viewable by anyone.
If permission list contains rules that give higher than PermissionLevel.VIEW
To store the changed information in the database, use saveChanges()
.
@NotNull StructureView saveChanges() throws StructureException
Call this method to save the changes made with set...
methods and update the database.
Before this method is called, all changes are only stored in this instance of StructureView
and have no other
effect. After this method has successfully executed, the changes are stored in the database and applied.
The updater - the current user
- must have
PermissionLevel.ADMIN
access level to the view and be allowed to use Structure plugin in
StructureConfiguration
.
Anyone, except anonymous, can create new views.
To share a view with someone else, the user needs to have "Create Shared Objects" global permission.
All security checks can be disabled
for the current context.
For detailed description of the permission rules validation, see Structure.saveChanges()
.
StructureException
- if there's a permissions problem, if required fields (name, specification) are not set, or if there
are other problemsStructure.saveChanges()
Copyright © 2024 Tempo Software. All Rights Reserved.