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

Interface StructureView

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

Since:
7.2.0 (Structure 2.0)
Author:
Igor Sereda
See Also:

  • Method Details

    • getId

      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).
      Returns:
      the ID of the view, or 0 if it doesn't yet have an ID

    • getName

      @NotNull String getName()
      Returns the name of the view or an empty string if the view name has not been set yet

    • getDescription

      @NotNull String getDescription()
      Returns the description of the view or an empty string if description was not set

    • getSpecification

      @NotNull ViewSpecification getSpecification()
      Returns the view specification, which defines the visual configuration of the widget
      See Also:

    • getOwner

      @Nullable ApplicationUser getOwner()
      Returns the owner of the view, or 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.

    • getPermissions

      @NotNull List<PermissionRule> getPermissions()
      Used to get permissions rules that are used to calculate user's access level. As with the permission rules for Structure, the last matching rule defines the access level.
      Returns:
      permission rules used to calculate the user's access level to this view

    • getEffectivePermission

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

      Parameters:
      user - the user, null means anonymous
      Returns:
      the permissions level
      See Also:

    • isShared

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

      Returns:
      true if the view is shared

    • isPublic

      boolean isPublic()
      Checks if the view is "public", that is, everyone has at least 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>).

      Returns:
      true if the view is public

    • setName

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

      Parameters:
      name - view name; null is interpreted as "don't change"
      Returns:
      this view

    • setDescription

      @NotNull StructureView setDescription(@Nullable String description)

      Sets the description of the view.

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

      Parameters:
      description - view description; null is interpreted as "don't change"
      Returns:
      this view

    • setOwner

      @NotNull StructureView setOwner(@Nullable ApplicationUser owner)

      Sets the owner of the view.

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

      Parameters:
      owner - new owner. null is interpreted as "don't change".
      Returns:
      this view

    • setPermissions

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

      Parameters:
      permissions - a collection of permissions. null is interpreted as "don't change"
      Returns:
      this view

    • setSpecification

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

      Parameters:
      specification - view specification. null is interpreted as "don't change"
      Returns:
      this view

    • setSpecification

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

      Parameters:
      specification - view specification. null is interpreted as "don't change"
      Returns:
      this view

    • update

      @NotNull StructureView update(@Nullable StructureViewBean.Builder builder)
      Updates the properties that have been set (have non-null value) in the passed builder. See StructureViewBean for details on the builder.

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

      Parameters:
      builder - the builder with view properties
      Returns:
      this view

    • makePublic

      @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

      permission to someone, those rules are retained. Other rules are removed.

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

      Returns:
      this view.

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

      Returns:
      this view
      Throws:
      StructureException - if there's a permissions problem, if required fields (name, specification) are not set, or if there are other problems
      See Also: