@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.
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.
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
.
StructureRow
IGNORE_MISSING_ROWS
Modifier and Type | Method and Description |
---|---|
default Set<ItemIdentity> |
collectItemIds(LongIterable rows)
Convenience method that collects item IDs from row IDs.
|
RowMapper |
createMapper(Forest forest)
Creates a mapper.
|
long |
createRow(ItemIdentity itemId,
long semantics)
Creates a new persistent row for the given item ID and semantics.
|
default LongIterator |
findRows(ItemIdentity itemId)
Returns all rows created for the specified item.
|
default void |
findRows(ItemIdentity itemId,
LongConsumer consumer)
Iterates through all rows created for the specified item.
|
void |
findRows(ItemIdentity itemId,
LongPredicate consumer)
Iterates through all rows created for the specified item.
|
collectIssueIds, collectIssueIds, getRow, getRow, reduceOverRows, scanAllExistingRows, scanAllExistingRows, scanAllExistingRows, scanAllRows, scanAllRows, scanAllRows, scanAllRows, scanRows, scanRows, scanRows, scanRows
long createRow(@NotNull ItemIdentity itemId, long semantics)
itemId
- item IDsemantics
- semantics code. Semantics is still work in progress, and passing any value other
than 0 may result in undefined behavior.@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.
itemId
- item IDdefault 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.
itemId
- item IDconsumer
- a consumer for found row IDsvoid 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.
itemId
- item IDconsumer
- a consumer for found row IDs; must return true
to continue iteration, false
to stop@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.
forest
- forest that contains candidate rows and generatorsRowMapper
@NotNull default Set<ItemIdentity> collectItemIds(@Nullable LongIterable rows)
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.
collectItemIds
in interface RowRetriever
rows
- a collection of rowsCopyright © 2023 ALM Works. All Rights Reserved.