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

Interface RowManager

All Superinterfaces:
RowRetriever
@PublicApi public interface RowManager extends RowRetriever

RowManager is responsible for maintaining row database and row properties.

Rows are a core concept in Structure architecture. A forest contains rows, not items. Rows are inserted and moved around in the structure. However, rows are a technical concept -- the user deals with items. The main responsibility of this component is to maintain mapping between rows and items they contain.

Rows are identified by their long ID. Anywhere where you need to store rows, you need to store its row ID -- you can later retrieve item ID from the RowManager.

Rows are immutable. Once created, row information cannot be changed. Unused rows may be forgotten and later reused or removed from the database by Row Manager.

Permanent and Transient Rows

Rows can be permanent and transient. Transient rows are used by the generators for the dynamic content. As the content gets recalculated, new rows may be created, or the old ones may be reused.

Transient rows live only in the JIRA instance's memory and not stored in the database. When JIRA restarts, all transient rows are lost.

On JIRA Data Center, transient row only lives on the node where it was created. Another node will have its own version of that row, likely with a different row ID, as all generators will work on that node separately.

Transient rows can also be created not by generators but by manual action when they need to be inserted into a transient forest source, such as a clipboard.

Permanent rows are created for static structure content that is stored in the database. They are never deleted and not reused. In the coming version of Structure we will implement a "garbage collector" for the unused permanent rows.

Temporary Rows

Note: there may be negative row IDs that are used for temporary rows when building forest fragments — see ItemForestBuilder. Usage of these row ID must be confined to the builder they came from. Trying to retrieve rows with negative ID from RowManager would result in MissingRowException.

See Also:

  • Method Details

    • createRow

      long createRow(@NotNull ItemIdentity itemId, long semantics)
      Creates a new persistent row for the given item ID and semantics.
      Parameters:
      itemId - item ID
      semantics - semantics code. Semantics is still work in progress, and passing any value other than 0 may result in undefined behavior.
      Returns:
      row ID of the new row

    • findRows

      @NotNull default LongIterator findRows(@Nullable ItemIdentity itemId)

      Returns all rows created for the specified item.

      Note: although this method returns transient rows as well, it cannot be relied upon to find which dynamic structures contain a specific item, because a structure needs to be generated first.

      This method should be sufficiently fast, implementations should do indexing.

      This method will iterate through all the rows it finds before returning. If you want to stop scanning early, please use findRows(ItemIdentity, LongPredicate) instead.

      Parameters:
      itemId - item ID
      Returns:
      an iterator that provides row IDs of permanent and transient rows that contain this item

    • findRows

      default void findRows(@Nullable ItemIdentity itemId, @NotNull LongConsumer consumer)

      Iterates through all rows created for the specified item.

      Note: although this method returns transient rows as well, it cannot be relied upon to find which dynamic structures contain a specific item, because a structure needs to be generated first.

      The consumer is called under a read lock, so it should be fast and take no locks.

      This method should be sufficiently fast, implementations should do indexing.

      Parameters:
      itemId - item ID
      consumer - a consumer for found row IDs

    • findRows

      void findRows(@Nullable ItemIdentity itemId, @NotNull LongPredicate consumer)

      Iterates through all rows created for the specified item.

      Note: although this method returns transient rows as well, it cannot be relied upon to find which dynamic structures contain a specific item, because a structure needs to be generated first.

      The consumer is called under a read lock, so it should be fast and take no locks.

      This method should be sufficiently fast, implementations should do indexing.

      Parameters:
      itemId - item ID
      consumer - a consumer for found row IDs; must return true to continue iteration, false to stop

    • createMapper

      @Internal @NotNull RowMapper createMapper(@NotNull Forest forest)

      Creates a mapper. RowMapper is needed when, for one or more rows, you need to find the very original row IDs.

      Parameters:
      forest - forest that contains candidate rows and generators
      Returns:
      a mapper
      See Also:

    • collectItemIds

      @NotNull default Set<ItemIdentity> collectItemIds(@Nullable LongIterable rows)
      Description copied from interface: RowRetriever

      Convenience method that collects item IDs from row IDs. Ignores missing rows.

      The returned collection is owned by the caller and may be further modified.

      Specified by:
      collectItemIds in interface RowRetriever
      Parameters:
      rows - a collection of rows
      Returns:
      a collection of item IDs found in the input rows