public interface RowRetriever
RowRetriever
is an abstraction of an object that can provide an instance of StructureRow
by its numeric ID.
In addition, it has bulk access methods that may provide multiple StructureRow
instances more efficiently.
There's a number of bulk scanning methods that are provided for convenience. The following naming convention is used:
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
– basic scanning method with a Predicate
callback, which allows breaking the iteration cycle.scanAllRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Consumer<com.almworks.jira.structure.api.row.StructureRow>)
– "all" means that all passed rows will be scanned, and the callback is a Consumer
.scanAllExistingRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, java.util.function.Consumer<com.almworks.jira.structure.api.row.StructureRow>)
– "existing" means that IGNORE_MISSING_ROWS
will be passed as the missing row collector,
which guarantees that the method will not throw MissingRowException
.RowManager
,
ItemForest
Modifier and Type | Field and Description |
---|---|
static LongCollector |
IGNORE_MISSING_ROWS
Use this to indicate that missing rows should not result in throwing
MissingRowException . |
Modifier and Type | Method and Description |
---|---|
default <C extends LongCollector> |
collectIssueIds(LongIterable rows,
boolean sorted,
C issuesCollector)
Convenience method that can be used to collect all issue IDs from given row IDs.
|
default <C extends LongCollector> |
collectIssueIds(LongIterable rows,
C issuesCollector)
Convenience method that can be used to collect all issue IDs from given row IDs.
|
Set<ItemIdentity> |
collectItemIds(LongIterable rows)
Convenience method that collects item IDs from row IDs.
|
default StructureRow |
getRow(long rowId)
Retrieves information about a structure row by its ID.
|
StructureRow |
getRow(long rowId,
ItemAccessMode access)
Retrieves
StructureRow with additional information about how the calling code is going to use
method StructureRow.getItem(java.lang.Class<I>) . |
default <T> T |
reduceOverRows(LongIterable rows,
T startingValue,
BiFunction<StructureRow,T,T> accumulator)
Performs a reduction over a collection of rows, identified by their IDs.
|
default void |
scanAllExistingRows(LongIterable rows,
boolean sorted,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs with a normal access mode and ignores any missing rows. |
default void |
scanAllExistingRows(LongIterable rows,
boolean sorted,
ItemAccessMode access,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs and ignores any missing rows. |
default void |
scanAllExistingRows(LongIterable rows,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs with a normal access mode, ignores any missing rows,
and assumes that the row ID stream may be not sorted. |
default void |
scanAllRows(LongIterable rows,
boolean sorted,
ItemAccessMode access,
LongCollector missingCollector,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs. |
default void |
scanAllRows(LongIterable rows,
boolean sorted,
LongCollector missingCollector,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs with a normal access mode. |
default void |
scanAllRows(LongIterable rows,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs, uses normal access mode, assumes that
row ID stream may be not sorted, and does not provide a missing collector. |
default void |
scanAllRows(LongIterable rows,
LongCollector missingCollector,
Consumer<StructureRow> consumer)
A convenience variation of
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>) that always goes through all of the row IDs, uses normal access mode, and assumes that
row ID stream may be not sorted. |
default void |
scanRows(LongIterable rows,
boolean sorted,
ItemAccessMode access,
LongCollector missingCollector,
Predicate<StructureRow> iteratee)
Loads multiple rows by their IDs and calls
iteratee with a StructureRow for each row ID in the input. |
default void |
scanRows(LongIterable rows,
boolean sorted,
LongCollector missingCollector,
Predicate<StructureRow> iteratee)
A convenience method that calls
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate) with
the normal access mode. |
default void |
scanRows(LongIterable rows,
LongCollector missingCollector,
Predicate<StructureRow> iteratee)
A convenience method that calls
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate) with
the normal access mode, and when the rows stream is not guaranteed to be sorted. |
default void |
scanRows(LongIterable rows,
Predicate<StructureRow> iteratee)
A convenience method that calls
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate) with
the normal access mode, when the rows stream is not guaranteed to be sorted, and without a missing row collector. |
static final LongCollector IGNORE_MISSING_ROWS
MissingRowException
.@NotNull default 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 StructureRow getRow(long rowId, @NotNull ItemAccessMode access) throws MissingRowException
Retrieves StructureRow
with additional information about how the calling code is going to use
method StructureRow.getItem(java.lang.Class<I>)
. The implementation may be optimized according to the access
parameter.
If row's item is invisible or does not exist, StructureRow
is returned anyway, but StructureRow.getItem(java.lang.Class<I>)
return null
.
rowId
- row IDaccess
- defines how item object is going to be accessedMissingRowException
- if the specified row ID does not existItemAccessMode
default void scanRows(@Nullable LongIterable rows, boolean sorted, @NotNull ItemAccessMode access, @Nullable LongCollector missingCollector, @NotNull Predicate<StructureRow> iteratee) throws MissingRowException
Loads multiple rows by their IDs and calls iteratee
with a StructureRow
for each row ID in the input.
Use this method whenever you need to read a potentially large amount of rows and the order of retrieval is not important.
For example, use scanRows
to iterate through the whole forest to see if it has a generator row,
or to process user input that has an array of row IDs.
The order in which iteratee
is called is not guaranteed to be the same as the iteration order of rows
.
Likewise, missingCollector
may receive row IDs out of order.
The implementation of iteratee
must be reasonably fast and avoid taking locks or accessing long-running services.
It's possible to call other RowRetriever
methods inside iteratee
.
It's possible to pass LongIterator
as LongIterable
- the iterator() method is guaranteed to be called only once.
You can choose an appropriate value for the access parameter based on what you're going to do with rows in the iteratee
.
This allows the provider of StructureRow
instances to optimize how StructureRow.getItem(java.lang.Class<I>)
method works.
If a row ID in the input stream does not correspond to an existing row, the behavior depends on whether the missingCollector
parameter is set. If it's null
, then the method will immediately throw a MissingRowException
. If it's not null, the
collector will be called with the missing row ID.
To simply ignore the missing rows, you can use IGNORE_MISSING_ROWS
collector or use one of the scanAllExistingRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, java.util.function.Consumer<com.almworks.jira.structure.api.row.StructureRow>)
methods.
Note that if the current user does not have access to a row, but the row itself exists, it's not considered missing.
Note that normally a row retriever does not handle SuperRootRow
in any special way, so it will be a case of a missing row. Some
implementations may, however, support accessing the super-root.
The default implementation is based on calling getRow(long)
. Specific implementations should optimize this method for retrieving
multiple rows at once.
Do not override other bulk scanning methods, unless that allows for additional optimization.
rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationaccess
- indicates how the getItem()
method of the provided StructureRow
is going to be used and allows to skip the access checkingmissingCollector
- a collector to receive non-existing row IDs, or null
iteratee
- predicate to call for each resolved row; if it returns false
, the iteration stops and the method returnsMissingRowException
- if a row was not found and missingCollector
is nullRowManager
,
ItemAccessMode
default void scanRows(@Nullable LongIterable rows, boolean sorted, @Nullable LongCollector missingCollector, @NotNull Predicate<StructureRow> iteratee) throws MissingRowException
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate)
with
the normal access mode.rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationmissingCollector
- a collector to receive non-existing row IDs, or null
iteratee
- predicate to call for each resolved row; if it returns false
, the iteration stops and the method returnsMissingRowException
- if a row was not found and missingCollector
is nulldefault void scanRows(@Nullable LongIterable rows, @Nullable LongCollector missingCollector, @NotNull Predicate<StructureRow> iteratee) throws MissingRowException
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate)
with
the normal access mode, and when the rows stream is not guaranteed to be sorted.rows
- row IDs of the rows to scanmissingCollector
- a collector to receive non-existing row IDs, or null
iteratee
- predicate to call for each resolved row; if it returns false
, the iteration stops and the method returnsMissingRowException
- if a row was not found and missingCollector
is nulldefault void scanRows(@Nullable LongIterable rows, @NotNull Predicate<StructureRow> iteratee) throws MissingRowException
scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate)
with
the normal access mode, when the rows stream is not guaranteed to be sorted, and without a missing row collector. This method
will throw MissingRowException
if a non-existent row ID is encountered.rows
- row IDs of the rows to scaniteratee
- predicate to call for each resolved row; if it returns false
, the iteration stops and the method returnsMissingRowException
- if a row was not founddefault void scanAllRows(@Nullable LongIterable rows, boolean sorted, @NotNull ItemAccessMode access, @Nullable LongCollector missingCollector, @NotNull Consumer<StructureRow> consumer) throws MissingRowException
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs.
Unlike scanRows()
methods, it accepts a Consumer
callback.rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationaccess
- indicates how the getItem()
method of the provided StructureRow
is going to be used and allows to skip the access checkingmissingCollector
- a collector to receive non-existing row IDs, or null
consumer
- a callback to call for every rowMissingRowException
- if a row was not found and missingCollector
is nulldefault void scanAllRows(@Nullable LongIterable rows, boolean sorted, @Nullable LongCollector missingCollector, @NotNull Consumer<StructureRow> consumer) throws MissingRowException
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs with a normal access mode.rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationmissingCollector
- a collector to receive non-existing row IDs, or null
consumer
- a callback to call for every rowMissingRowException
- if a row was not found and missingCollector
is nulldefault void scanAllRows(@Nullable LongIterable rows, @Nullable LongCollector missingCollector, @NotNull Consumer<StructureRow> consumer) throws MissingRowException
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs, uses normal access mode, and assumes that
row ID stream may be not sorted.rows
- row IDs of the rows to scanmissingCollector
- a collector to receive non-existing row IDs, or null
consumer
- a callback to call for every rowMissingRowException
- if a row was not found and missingCollector
is nulldefault void scanAllRows(@Nullable LongIterable rows, @NotNull Consumer<StructureRow> consumer) throws MissingRowException
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs, uses normal access mode, assumes that
row ID stream may be not sorted, and does not provide a missing collector. This method will throw MissingRowException
if a non-existent row ID is encountered.rows
- row IDs of the rows to scanconsumer
- a callback to call for every rowMissingRowException
- if a row was not founddefault void scanAllExistingRows(@Nullable LongIterable rows, boolean sorted, @NotNull ItemAccessMode access, @NotNull Consumer<StructureRow> consumer)
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs and ignores any missing rows.rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationaccess
- indicates how the getItem()
method of the provided StructureRow
is going to be used and allows to skip the access checkingconsumer
- a callback to call for every rowdefault void scanAllExistingRows(@Nullable LongIterable rows, boolean sorted, @NotNull Consumer<StructureRow> consumer)
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs with a normal access mode and ignores any missing rows.rows
- row IDs of the rows to scansorted
- if true, then the caller guarantees the row IDs to be sorted - this can be used for optimizationconsumer
- a callback to call for every rowdefault void scanAllExistingRows(@Nullable LongIterable rows, @NotNull Consumer<StructureRow> consumer)
scanRows(com.almworks.integers.LongIterable, boolean, com.almworks.jira.structure.api.row.ItemAccessMode, com.almworks.integers.LongCollector, java.util.function.Predicate<com.almworks.jira.structure.api.row.StructureRow>)
that always goes through all of the row IDs with a normal access mode, ignores any missing rows,
and assumes that the row ID stream may be not sorted.rows
- row IDs of the rows to scanconsumer
- a callback to call for every row@Nullable default <T> T reduceOverRows(@Nullable LongIterable rows, @Nullable T startingValue, @NotNull BiFunction<StructureRow,T,T> accumulator) throws MissingRowException
Performs a reduction over a collection of rows, identified by their IDs.
The reducer function must be associative and commutative, because it may be called in a random order, not corresponding to the
iteration order of rows
.
T
- result typerows
- row IDs of the rows to scanstartingValue
- the initial value to start withaccumulator
- a function that receives the next row and the accumulated value, and then produces the next accumulated valuestartingValue
if there was no iterationMissingRowException
- if a row was not found@NotNull default <C extends LongCollector> C collectIssueIds(@Nullable 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 IDs@NotNull default <C extends LongCollector> C collectIssueIds(@Nullable LongIterable rows, @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 rowsissuesCollector
- a collection to receive issue IDs@NotNull Set<ItemIdentity> collectItemIds(@Nullable LongIterable rows)
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.
rows
- a collection of rowsCopyright © 2024 Tempo Software. All Rights Reserved.