@PublicApi
public interface RowManager
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
Modifier and Type | Method and Description |
---|---|
default <C extends com.almworks.integers.LongCollector> |
collectIssueIds(com.almworks.integers.LongIterable rows,
boolean sorted,
C issuesCollector)
Convenience method that can be used to collect all issue IDs from given row IDs.
|
default <C extends com.almworks.integers.LongCollector> |
collectIssueIds(com.almworks.integers.LongIterable rows,
C issuesCollector)
Convenience method that can be used to collect all issue IDs from given 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 com.almworks.integers.LongIterator |
findRows(ItemIdentity itemId)
Returns all rows created for the specified item.
|
default void |
findRows(ItemIdentity itemId,
java.util.function.LongConsumer consumer)
Iterates through all rows created for the specified item.
|
void |
findRows(ItemIdentity itemId,
java.util.function.LongPredicate consumer)
Iterates through all rows created for the specified item.
|
StructureRow |
getRow(long rowId)
Retrieves information about a structure row by its ID.
|
StructureRow |
getRow(long rowId,
boolean itemVisible)
Retrieves
StructureRow given that the calling code has already checked the item for access by the user. |
void |
scanRows(com.almworks.integers.LongIterator rows,
boolean sorted,
com.almworks.integers.LongCollector missingCollector,
java.util.function.Predicate<StructureRow> iteratee)
Bulk rows reading.
|
@NotNull StructureRow getRow(long rowId) throws MissingRowException
Retrieves information about a structure row by its ID.
Note that it is a runtime error to request a non-existing row, because that should never happen in a correct code.
rowId
- row IDMissingRowException
- if the specified row ID does not exist@NotNull @Internal StructureRow getRow(long rowId, boolean itemVisible) throws MissingRowException
Retrieves StructureRow
given that the calling code has already checked the item for access by the user.
itemVisible
parameter specifies whether the item is visible or not.
This method is needed for optimization to avoid multiple access checks for an item.
rowId
- row IDitemVisible
- if true, the corresponding item is known to be visible to the current user; if false, the item
is known to be invisible to the current userStructureRow
is returned anyway, but StructureRow.getItem(java.lang.Class<I>)
will return null
.MissingRowException
- if the specified row ID does not existlong createRow(@NotNull ItemIdentity itemId, long semantics)
itemId
- item IDsemantics
- semantics (currently must be set to 0)@NotNull default com.almworks.integers.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 java.util.function.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.
This method should be sufficiently fast, implementations should do indexing.
itemId
- item IDconsumer
- a consumer for found row IDsvoid findRows(@Nullable ItemIdentity itemId, @NotNull java.util.function.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.
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 stopvoid scanRows(@Nullable com.almworks.integers.LongIterator rows, boolean sorted, @Nullable com.almworks.integers.LongCollector missingCollector, @NotNull java.util.function.Predicate<StructureRow> iteratee) throws MissingRowException
Bulk rows reading. Implementation should optimize this method for retrieving multiple rows at once. Use it whenever you need to read potentially massive amount of rows, for example, when scanning the whole forest.
The order in which iteratee is called is not guaranteed to be the same as rows. The same for missingCollector.
Iteratee must be reasonably fast and avoid taking locks or accessing long-running services.
It's possible to call other RowManager
methods from inside the iteratee
.
rows
- rows to readsorted
- if true, then rows is sorted - can be used by the optimized codemissingCollector
- if not null, all missing rows will be added to the collector; if null
, any missing
row will cause MissingRowExceptioniteratee
- predicate to call for each resolved row; if it returns false, the iteration stopsMissingRowException
- if a row was not found and missingCollector is null@NotNull default <C extends com.almworks.integers.LongCollector> C collectIssueIds(@Nullable com.almworks.integers.LongIterable rows, boolean sorted, @NotNull C issuesCollector)
Convenience method that can be used to collect all issue IDs from given row IDs. Ignores missing rows.
C
- type of the collectorrows
- a collection of rowssorted
- if true, then rows is sorted - can be used by the optimized codeissuesCollector
- a collection to receive issue IDsdefault <C extends com.almworks.integers.LongCollector> C collectIssueIds(@Nullable com.almworks.integers.LongIterable rows, C issuesCollector)
Convenience method that can be used to collect all issue IDs from given row IDs. Ignores missing rows.
C
- type of the collectorrows
- a collection of rowsissuesCollector
- a collection to receive issue IDsCopyright © 2017 ALM Works. All Rights Reserved.