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

Interface RowRetriever

All Known Subinterfaces:

ItemForest, RowManager

All Known Implementing Classes:

ImmutableItemForest, ManagerBackedItemForest

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.

See Also:

• RowManager
• ItemForest

Field Summary

Fields

Modifier and Type	Field	Description
static final LongCollector	IGNORE_MISSING_ROWS	Use this to indicate that missing rows should not result in throwing MissingRowException.

Method Summary

Modifier and Type	Method	Description
default <C extends LongCollector> C	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> C	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, 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, 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, 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, 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, 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, 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	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	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, 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, 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.

Field Details

IGNORE_MISSING_ROWS

static final LongCollector IGNORE_MISSING_ROWS

Use this to indicate that missing rows should not result in throwing MissingRowException.

See Also:

• scanRows(LongIterable, boolean, LongCollector, Predicate)

Method Details

getRow

@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.

Parameters:

rowId - row ID

Returns:

row information

Throws:

MissingRowException - if the specified row ID does not exist

getRow

@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.

Parameters:

rowId - row ID

access - defines how item object is going to be accessed

Returns:

row instance

Throws:

MissingRowException - if the specified row ID does not exist

See Also:

• ItemAccessMode

scanRows

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.

Item access mode

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.

Dealing with missing rows

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.

Super-root

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.

Implementation notes

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.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

access - indicates how the getItem() method of the provided StructureRow is going to be used and allows to skip the access checking

missingCollector - 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 returns

Throws:

MissingRowException - if a row was not found and missingCollector is null

See Also:

• RowManager
• ItemAccessMode

scanRows

default void scanRows(@Nullable
 LongIterable rows,
 boolean sorted,
 @Nullable
 LongCollector missingCollector,
 @NotNull
 Predicate<StructureRow> iteratee)
               throws MissingRowException

A convenience method that calls scanRows(LongIterable, boolean, ItemAccessMode, LongCollector, Predicate) with the normal access mode.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

missingCollector - 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 returns

Throws:

MissingRowException - if a row was not found and missingCollector is null

scanRows

default void scanRows(@Nullable
 LongIterable rows,
 @Nullable
 LongCollector missingCollector,
 @NotNull
 Predicate<StructureRow> iteratee)
               throws MissingRowException

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.

Parameters:

rows - row IDs of the rows to scan

missingCollector - 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 returns

Throws:

MissingRowException - if a row was not found and missingCollector is null

scanRows

default void scanRows(@Nullable
 LongIterable rows,
 @NotNull
 Predicate<StructureRow> iteratee)
               throws MissingRowException

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. This method will throw MissingRowException if a non-existent row ID is encountered.

Parameters:

rows - row IDs of the rows to scan

iteratee - predicate to call for each resolved row; if it returns false, the iteration stops and the method returns

Throws:

MissingRowException - if a row was not found

scanAllRows

default void scanAllRows(@Nullable
 LongIterable rows,
 boolean sorted,
 @NotNull
 ItemAccessMode access,
 @Nullable
 LongCollector missingCollector,
 @NotNull
 Consumer<StructureRow> consumer)
                  throws MissingRowException

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. Unlike scanRows() methods, it accepts a Consumer callback.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

access - indicates how the getItem() method of the provided StructureRow is going to be used and allows to skip the access checking

missingCollector - a collector to receive non-existing row IDs, or null

consumer - a callback to call for every row

Throws:

MissingRowException - if a row was not found and missingCollector is null

scanAllRows

default void scanAllRows(@Nullable
 LongIterable rows,
 boolean sorted,
 @Nullable
 LongCollector missingCollector,
 @NotNull
 Consumer<StructureRow> consumer)
                  throws MissingRowException

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.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

missingCollector - a collector to receive non-existing row IDs, or null

consumer - a callback to call for every row

Throws:

MissingRowException - if a row was not found and missingCollector is null

scanAllRows

default void scanAllRows(@Nullable
 LongIterable rows,
 @Nullable
 LongCollector missingCollector,
 @NotNull
 Consumer<StructureRow> consumer)
                  throws MissingRowException

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.

Parameters:

rows - row IDs of the rows to scan

missingCollector - a collector to receive non-existing row IDs, or null

consumer - a callback to call for every row

Throws:

MissingRowException - if a row was not found and missingCollector is null

scanAllRows

default void scanAllRows(@Nullable
 LongIterable rows,
 @NotNull
 Consumer<StructureRow> consumer)
                  throws MissingRowException

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. This method will throw MissingRowException if a non-existent row ID is encountered.

Parameters:

rows - row IDs of the rows to scan

consumer - a callback to call for every row

Throws:

MissingRowException - if a row was not found

scanAllExistingRows

default void scanAllExistingRows(@Nullable
 LongIterable rows,
 boolean sorted,
 @NotNull
 ItemAccessMode access,
 @NotNull
 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.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

access - indicates how the getItem() method of the provided StructureRow is going to be used and allows to skip the access checking

consumer - a callback to call for every row

scanAllExistingRows

default void scanAllExistingRows(@Nullable
 LongIterable rows,
 boolean sorted,
 @NotNull
 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.

Parameters:

rows - row IDs of the rows to scan

sorted - if true, then the caller guarantees the row IDs to be sorted - this can be used for optimization

consumer - a callback to call for every row

scanAllExistingRows

default void scanAllExistingRows(@Nullable
 LongIterable rows,
 @NotNull
 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.

Parameters:

rows - row IDs of the rows to scan

consumer - a callback to call for every row

reduceOverRows

@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.

Type Parameters:

T - result type

Parameters:

rows - row IDs of the rows to scan

startingValue - the initial value to start with

accumulator - a function that receives the next row and the accumulated value, and then produces the next accumulated value

Returns:

the last accumulated value, or startingValue if there was no iteration

Throws:

MissingRowException - if a row was not found

collectIssueIds

@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.

Type Parameters:

C - type of the collector

Parameters:

rows - a collection of rows

sorted - if true, then rows is sorted - can be used by the optimized code

issuesCollector - a collection to receive issue IDs

Returns:

the collector

collectIssueIds

@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.

Type Parameters:

C - type of the collector

Parameters:

rows - a collection of rows

issuesCollector - a collection to receive issue IDs

Returns:

the collector

collectItemIds

@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.

Parameters:

rows - a collection of rows

Returns:

a collection of item IDs found in the input rows