@PublicApi
public interface Structure
This interface lets you inspect and change properties of a structure.
Structures are named hierarchical lists of issues and other items; they are the main entities in the Structure add-on.
But Structure
interface does not provide access to the hierarchy itself — that can be done via ForestService
.
You typically get an instance of Structure
by calling
one of the StructureManager
methods. There are get...
methods
to retrieve the existing structures, and StructureManager.createStructure()
method to create a new structure.
To change properties of a structure, you need to get the instance of
Structure
, call some of the set...
methods and then
call saveChanges()
. Until you call saveChanges()
the modifications
are made only to the copy of the structure in memory.
To create a new structure, call StructureManager.createStructure()
to get
an empty Structure
instance, call set...
methods to set
properties (at least structure name must be set) and then call saveChanges()
.
When saveChanges
is completed, the new Structure has been created and
you can use getId()
to get the new structure's ID.
Note that the maximum length of a structure name is 190 (see Limits.MAX_NAME_LENGTH
).
Longer names will be truncated.
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 Structure
instance. Moreover, every time you need an
instance of Structure
, you should get it from the StructureManager
because the properties might have changed or the structure might have been deleted.
StructureManager
,
ForestService
Modifier and Type | Method and Description |
---|---|
String |
getDescription()
Returns the description of the structure, or empty string if the description has not been set.
|
PermissionLevel |
getEffectivePermission()
Calculates permission level for this structure based on the current user.
|
long |
getId()
Returns the ID of the structure, or
0 if the structure has no ID (when it's
new and hasn't been saved yet). |
String |
getName()
Returns the name of the structure or empty string if the name has not been yet set.
|
default ApplicationUser |
getOwner()
Returns the owner of the structure.
|
String |
getOwnerUserKey()
Returns the user key of the owner of the structure.
|
List<PermissionRule> |
getPermissions()
Returns a list of permissions for this structure.
|
boolean |
isArchived()
Returns true if structure is archived.
|
boolean |
isEditRequiresParentIssuePermission()
Returns true if modification of the forest requires that the user has Edit Issue permission to the parent
issue of the items being moved, added or deleted.
|
Structure |
saveChanges()
Call this method to save the changes made with
set... methods and update the database. |
Structure |
setArchived(boolean archived)
Changes the archived flag.
|
Structure |
setDescription(String description)
Sets the description of the structure.
|
Structure |
setEditRequiresParentIssuePermission(boolean flag)
Changes the security flag that requires the user to have Edit Issue permission on parent
issues of the issues being moved, added or deleted from structure.
|
Structure |
setName(String name)
Sets the name of the structure.
|
default Structure |
setOwner(ApplicationUser owner)
Sets the owner of the structure.
|
Structure |
setOwnerUserKey(String ownerUserKey)
Sets the owner of the structure.
|
Structure |
setPermissions(Collection<? extends PermissionRule> permissions)
Sets the permission rules for this structure.
|
long getId()
0
if the structure has no ID (when it's
new and hasn't been saved yet).@NotNull String getName()
@NotNull String getDescription()
@Nullable default ApplicationUser getOwner()
null
is returned if there's no owner, or if the owner has been
removed from JIRA.@Nullable String getOwnerUserKey()
null
is returned if there's no owner.
Note that the user is not guaranteed to exist. Use getOwner()
to retrieve only an existing user.@NotNull List<PermissionRule> getPermissions()
boolean isEditRequiresParentIssuePermission()
Returns true if modification of the forest requires that the user has Edit Issue permission to the parent issue of the items being moved, added or deleted.
Note: currently this flag works only with parent issues. In the future, it may be extended to work with any item types that support edit permission checking.
Only the immediate parent issue is checked, higher-level ancestors are not considered.
boolean isArchived()
@NotNull Structure setName(@Nullable String name)
Sets the name of the structure. 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()
.
Structure name cannot be longer than 190 characters.
name
- structure name@NotNull Structure setDescription(@Nullable String description)
Sets the description of the structure.
To store the changed information in the database, use saveChanges()
.
description
- structure description@NotNull default Structure setOwner(@Nullable ApplicationUser owner)
Sets the owner of the structure.
To store the changed information in the database, use saveChanges()
.
owner
- new owner@NotNull Structure setOwnerUserKey(@Nullable String ownerUserKey)
Sets the owner of the structure.
To store the changed information in the database, use saveChanges()
.
ownerUserKey
- new owner's user key@NotNull Structure setPermissions(@Nullable Collection<? extends PermissionRule> permissions)
Sets the permission rules for this structure. Permission rules are evaluated in the specified order and the last matching rule defines the access level to the structure for the given user.
Structure owner and JIRA administrators always have PermissionLevel.ADMIN
access level.
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 fails to validate.
permissions
- a collection of permissions, null means empty list@NotNull Structure setEditRequiresParentIssuePermission(boolean flag)
Changes the security flag that requires the user to have Edit Issue permission on parent issues of the issues being moved, added or deleted from structure.
To store the changed information in the database, use saveChanges()
.
flag
- if true, Edit Issue permission is required@NotNull Structure setArchived(boolean archived)
Changes the archived flag.
archived
- if true, the structure is archived@NotNull Structure 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 Structure and have no other effect. After this method has successfully executed, the changes are stored in the database and applied.
The changes are done under the current user. Current user can be changed with StructureAuth.sudo(com.atlassian.jira.user.ApplicationUser, boolean, com.almworks.jira.structure.api.util.CallableE<R, E>)
.
The updater must have
PermissionLevel.ADMIN
access level to the structure, and be allowed to use Structure plugin in
StructureConfiguration
. Additionally, if this is a new structure being saved, the user must have
permissions to create new structures.
All security checks are bypassed if overrideSecurity
flag is set via StructureAuth
.
Permission rules (set through setPermissions(java.util.Collection)
or existing if this method was not used) are validated before changing the database.
If any of the rules is not valid, StructureException is thrown.
StructureException
- if there's a permissions problem, if required fields (name) are not set, or if there
are other problems@NotNull PermissionLevel getEffectivePermission()
overrideSecurity
flag is set, this method returns ADMIN
.
For instances representing new structures (not yet saved in the database), this method returns NONE
.Copyright © 2024 Tempo Software. All Rights Reserved.