• Home
• com.almworks.jira.structure
• structure-api
• 17.25.1
• source code
• StructureRow.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.almworks.jira.structure.api.row.StructureRow Maven / Gradle / Ivy

package com.almworks.jira.structure.api.row;

import com.almworks.jira.structure.api.forest.raw.Forest;
import com.almworks.jira.structure.api.item.ItemIdentity;
import com.atlassian.annotations.PublicApi;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

/**
 * 
{@code StructureRow} instances represent rows, main building blocks of a forest.
 *
 * 
Structures and query results emit forests. {@link Forest} content is expressed as a sequence of row IDs.
 * To get more information about the row, you need to get {@code StructureRow} instance from {@link RowManager}.
 *
 * 
A row has the following properties:
 *
 * 

 *   
{@code rowID} is the unique ID of the row.
 *   
{@code itemID} is the ID of the item that is displayed in this row.
 *   
{@code semantics} is the semantic code of the relationship between the row and its parent. Currently, semantics are
 *   not supported and are zero most of the times.
 *   
{@code originalId} and {@code creatorId} are additional properties, specified only for transient rows
 *   — see {@link RowManager}.
 * 
 *
 * 
Note that a single forest may contain the same item in multiple places, but all rows will be unique.
 *
 * 
Rows are immutable. Persistent rows get stored in the database and are never updated nor deleted.
 * Temporary rows get cleared when JIRA instance restarts. Garbage collection for rows is planned for the future.
 *
 * 
Important: {@code StructureRow} is a temporary object and must not be cached or leaked outside the current request, because it
 * stores the result of access check to the item for the current user.
 *
 */
@PublicApi
public interface StructureRow {
  StructureRow ROW_ZERO = new ZeroRow();

  /**
   * Returns row ID, a positive number.
   */
  long getRowId();

  /**
   * Returns item ID for the item shown in this row.
   */
  @NotNull
  ItemIdentity getItemId();

  /**
   * Returns row's semantics.
   */
  long getSemantics();

  /**
   * 
Tries to resolve the item based on its ID, that is, get an object that represents this item.
   * Resolution includes checking the current user's access to that item, unless the row is created with an additional
   * flag indicating that the access check should be skipped.
   *
   * 
This method may return {@code null} in many different cases:
   * 

   *   
The item does not exist.
   *   
The item is not accessible by the current user.
   *   
The instance of {@code StructureRow} was created with the {@link ItemAccessMode#ITEM_NOT_NEEDED} flag.
   *   
The plugin module that is responsible for this type of items is disabled or missing.
   *   
Item's object type is not reducible to {@code itemClass}.
   * 
   *
   * @param itemClass expected class of the item's object
   * @param  type of item's objects
   * @return the item's object, or {@code null}
   */
  @Nullable
   I getItem(@NotNull Class itemClass);


  final class ZeroRow implements StructureRow {
    @Override
    public long getRowId() {
      return 0;
    }

    @NotNull
    @Override
    public ItemIdentity getItemId() {
      return ItemIdentity.ITEM_ZERO;
    }

    @Nullable
    @Override
    public  I getItem(@NotNull Class itemClass) {
      return null;
    }

    @Override
    public long getSemantics() {
      return 0;
    }

    @Override
    public String toString() {
      return getRowId() + ":" + getItemId();
    }
  }
}