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

Go to download
Show more of this group Show more artifacts with this name
Show all versions of structure-api Show documentation
Public API for the Structure Plugin for JIRA
There is a newer version: 17.25.3
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();
    }
  }
}