com.almworks.jira.structure.api
Interface Structure

All Superinterfaces:

Comparable<Structure>

public interface Structure
extends Comparable<Structure>

A structure is a hierarchical list of issues. Structure interface lets you inspect and change properties of a structure, while Forest contains the hierarchy itself.

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 get the Forest associated with the structure, you can use getForest(com.atlassian.crowd.embedded.api.User, boolean) method from this class, but you don't have to get an instance of Structure to get the forest - methods StructureManager.getForest(java.lang.Long, com.atlassian.crowd.embedded.api.User, boolean) and StructureManager.getForestUpdate(java.lang.Long, java.lang.Long, java.lang.Long, com.atlassian.crowd.embedded.api.User, boolean) accept the structure ID.

To change properties of a structure, you need to get the instance of Structure, call some of the set... methods and then call saveChanges(com.atlassian.crowd.embedded.api.User, boolean). 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(com.atlassian.crowd.embedded.api.User, boolean). 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 255. 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.

Author:

Igor Sereda

See Also:

StructureManager, Forest

Method Summary

String	getDescription()
PermissionLevel	getEffectivePermission(com.atlassian.crowd.embedded.api.User user) Calculates access level to this structure for the specified user.
Forest	getForest(com.atlassian.crowd.embedded.api.User user, boolean overrideSecurity) This is a convenience method to get the forest of this structure.
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()
PermissionSubject	getOwner()
List<PermissionRule>	getPermissions()
boolean	isEditRequiresParentIssuePermission()
Structure	saveChanges(com.atlassian.crowd.embedded.api.User updater, boolean overrideSecurity) Call this method to save the changes made with set...
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	setId(long id) Sets the ID of the structure.
Structure	setName(String name) Sets the name of the structure.
Structure	setOwner(PermissionSubject owner) Sets the owner of the structure, usually an instance of PermissionSubject.JiraUser.
Structure	setPermissions(Collection<? extends PermissionRule> permissions) Sets the permission rules for this structure.

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getId

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).

Returns:

the ID of the structure, or 0 if it doesn't yet have an ID

getOwner

@Nullable
PermissionSubject getOwner()

Returns:

the owner of the structure or null if there's no owner

getName

@NotNull
String getName()

Returns:

the name of the structure or empty string if the name has not been yet set

getDescription

@NotNull
String getDescription()

Returns:

the description of the structure, or empty string if the description has not been set

isEditRequiresParentIssuePermission

boolean isEditRequiresParentIssuePermission()

Returns:

true if modification of the forest requires Edit Issue permission from the user on the parent issues of the issues being modified

See Also:

Structure Permissions (Structure Documentation)

getPermissions

@NotNull
List<PermissionRule> getPermissions()

Returns:

a list of permissions for this structure. User's access level is defined by applying those rules in the order they are returned from this method. The last matching rule has precedence.

See Also:

Structure Permissions (Structure Documentation)

setId

@NotNull
Structure setId(long id)

Sets the ID of the structure. You can only set the ID of a structure instance that's newly created with StructureManager.createStructure() method - this lets you create new structures with a predefined ID. Structure ID must be a positive number, additional limitations on the allowed predefined numbers may be imposed by the implementation.

Note that you do not have to call this method! You can create a new structure without ID and a next free ID will be assigned to it when you call saveChanges().

To store the changed information in the database, use saveChanges(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

id - the ID for the new structure

Returns:

this structure

Throws:

IllegalStateException - if this is not a new structure

IllegalArgumentException - if the ID is invalid

setOwner

@NotNull
Structure setOwner(@Nullable
                           PermissionSubject owner)

Sets the owner of the structure, usually an instance of PermissionSubject.JiraUser.

To store the changed information in the database, use saveChanges(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

owner - new owner

Returns:

this structure

setName

@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(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

name - structure name

Returns:

this structure

setDescription

@NotNull
Structure setDescription(@Nullable
                                 String description)

Sets the description of the structure.

To store the changed information in the database, use saveChanges(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

description - structure description

Returns:

this structure

setEditRequiresParentIssuePermission

@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(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

flag - if true, Edit Issue permission is required

Returns:

this structure

See Also:

Structure Permissions (Structure Documentation)

setPermissions

@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(com.atlassian.crowd.embedded.api.User, boolean). At this point, the specified rules are validated, and StructureException is thrown if any of them fails to validate.

Parameters:

permissions - a collection of permissions, null means empty list

Returns:

this structure

See Also:

Structure Permissions (Structure Documentation)

saveChanges

@NotNull
Structure saveChanges(@Nullable
                              com.atlassian.crowd.embedded.api.User updater,
                              boolean overrideSecurity)
                      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 calling user account is passed in the updater parameter. 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 is true.

Permission rules validation

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 with the following StructureError:

StructureError.STRUCTURE_NOT_EXISTS_OR_NOT_ACCESSIBLE	There is an "apply structure permission" rule that refers to a structure that does not exist or is inaccessible.	StructureException.getStructure() returns ID of the referred structure.
StructureError.PERMISSION_RULE_APPLICATION_FORMS_CYCLE	There is an "apply structure permission" rule that refers to a structure belonging to a permission dependency cycle. This rule or some other may be responsible for that cycle.	Throwable.getMessage() contains the structures in that cycle and the conflicting dependency. The message is not localized.
StructureError.GROUP_NOT_EXISTS_OR_INACCESSIBLE	There is a "set level" permission rule applied to a JIRA group that does not exist or is inaccessible (current user is not its member.)	Throwable.getMessage() contains group ID. The message is not localized.
StructureError.PROJECT_NOT_EXISTS_OR_INACCESSIBLE	There is a "set level" permission rule applied to a JIRA project role in a project that is not enabled for the Structure plugin, does not exist or is inaccessible (current user does not have Browse permission for it.)	Throwable.getMessage() contains project ID (numeric.) The message is not localized.
StructureError.PROJECT_ROLE_NOT_EXISTS_OR_INACCESSIBLE	There is a "set level" permission rule applied to a JIRA project role that does not exist or is not visible to the current user.	Throwable.getMessage() contains project role ID (numeric.) The message is not localized.

Parameters:

updater - the user who performs the update, null means anonymous

overrideSecurity - if true, no security checks are made. The user parameter may be used to record change history.

Returns:

this structure

Throws:

StructureException - if there's a permissions problem, if required fields (name) are not set, or if there are other problems

getEffectivePermission

@NotNull
PermissionLevel getEffectivePermission(@Nullable
                                               com.atlassian.crowd.embedded.api.User user)

Calculates access level to this structure 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) method call, until they are committed to the database with saveChanges(com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

user - the user, null means anonymous

Returns:

the permissions level

See Also:

StructureManager.getStructurePermission(java.lang.Long, com.atlassian.crowd.embedded.api.User)

getForest

@NotNull
Forest getForest(@Nullable
                         com.atlassian.crowd.embedded.api.User user,
                         boolean overrideSecurity)
                 throws StructureException

This is a convenience method to get the forest of this structure. More universal method is to use StructureManager.getForestUpdate(java.lang.Long, java.lang.Long, java.lang.Long, com.atlassian.crowd.embedded.api.User, boolean).

Parameters:

user - the user requesting the forest

overrideSecurity - if true, no security checks are performed (however, issues are still verified to exist and belong to a project enabled for Structure)

Returns:

the writable copy of the Forest for this structure

Throws:

StructureException - if there are any problems (permissions problem, no such structure, and others)