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

Interface Structure

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

Author:
Igor Sereda
See Also:

  • Method Details

    • 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

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

    • getOwner

      @Nullable default ApplicationUser getOwner()
      Returns the owner of the structure. null is returned if there's no owner, or if the owner has been removed from JIRA.

    • getOwnerUserKey

      @Nullable String getOwnerUserKey()
      Returns the user key of the owner of the structure. 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.

    • 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:

    • isEditRequiresParentIssuePermission

      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.

      See Also:

    • isArchived

      boolean isArchived()
      Returns true if structure is archived.

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

      Structure name cannot be longer than 190 characters.

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

      Parameters:
      description - structure description
      Returns:
      this structure

    • setOwner

      @NotNull default Structure setOwner(@Nullable ApplicationUser owner)

      Sets the owner of the structure.

      To store the changed information in the database, use saveChanges().

      Parameters:
      owner - new owner
      Returns:
      this structure

    • setOwnerUserKey

      @NotNull Structure setOwnerUserKey(@Nullable String ownerUserKey)

      Sets the owner of the structure.

      To store the changed information in the database, use saveChanges().

      Parameters:
      ownerUserKey - new owner's user key
      Returns:
      this structure

    • 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(). 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:

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

      Parameters:
      flag - if true, Edit Issue permission is required
      Returns:
      this structure
      See Also:

    • setArchived

      @NotNull Structure setArchived(boolean archived)

      Changes the archived flag.

      Parameters:
      archived - if true, the structure is archived
      Returns:
      this structure

    • saveChanges

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

      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()
      Calculates permission level for this structure based on the current user. When overrideSecurity flag is set, this method returns ADMIN. For instances representing new structures (not yet saved in the database), this method returns NONE.
      Returns:
      effective permission