@PublicApi public interface AttributeSubscription extends VersionedDataSource<AttributeSubscriptionUpdate>
AttributeSubscription
represents an interest of the client code in a particular set of attribute values, allowing
for background loading. It acts as a buffer, collecting the loaded values and serving it to the client as a VersionedDataSource
.
To indicate interest in a particular set of values, you need to set the forest spec, row set and attribute set via
changeSubscription(java.util.function.Consumer<com.almworks.jira.structure.api.attribute.subscription.AttributeSubscriptionPatch>)
method. You can later update the subscription by changing either of these parameters. The buffer
will be cleared and adjusted accordingly. Any background loading that is no longer required will be automatically canceled.
Note that if you have interest in multiple sets (for example, in different forests, or different attributes for different rows), you need to create different subscriptions, rather than constantly adjusting a single subscription.
The subscription uses the public methods of StructureAttributeService
to load values. All values will be loaded
according to the user's permissions and attribute sensitivity settings.
There's no way to create a subscription that overloads security.
Note that the values will only be loaded when you call loadValues()
. When to call this method is up to you, and you
can call it any time. There's no reason to throttle the calls to loadValues()
, it will happen on its own inside the
subscription.
If you never call loadValues()
, you will never receive any data!
Modifier and Type | Method and Description |
---|---|
void |
changeSubscription(Consumer<AttributeSubscriptionPatch> changer)
Updates the current subscription.
|
Collection<AttributeErrorInfo> |
drainAttributeErrors()
Retrieves accumulated information about attribute loader errors.
|
Collection<AttributeSpec<?>> |
getAttributes()
Returns the attributes that are currently subscribed for.
|
ForestSpec |
getForest()
Returns the forest spec currently set in this subscription.
|
RowValues |
getFullUpdate()
A convenience method that loads all the values, waiting for them for an unspecified amount of time.
|
RowValues |
getFullUpdate(long timeout,
TimeUnit unit)
A convenience method that calls
loadValues() , waits for the specified amount of time for the loading to complete,
and then provides the loaded value. |
LongSet |
getInaccessibleRows()
Returns the last known list of rows that are not accessible by the owner of the subscription.
|
LongList |
getRows()
Returns the rows that are currently subscribed for.
|
long |
getSubscriptionId()
Returns the ID of the subscription.
|
AttributeSubscriptionUpdate |
getUpdate(DataVersion fromVersion)
A quick, non-blocking retrieval of the updated values.
|
boolean |
isLoadingValues()
This method can be used to check if the attribute loading is currently taking place for this subscription.
|
CompletableFuture<DataVersion> |
loadValues()
Requests that the subscription performs attribute loading.
|
getCurrentVersion
long getSubscriptionId()
AttributeSubscriptionService.getSubscription(Long)
void changeSubscription(@NotNull Consumer<AttributeSubscriptionPatch> changer)
changer
- the code that will update the subscription@NotNull ForestSpec getForest()
@NotNull Collection<AttributeSpec<?>> getAttributes()
@NotNull LongList getRows()
@NotNull AttributeSubscriptionUpdate getUpdate(@NotNull DataVersion fromVersion)
A quick, non-blocking retrieval of the updated values. Calling this method is guaranteed to return quickly, but there's no guarantee that all values will be up to date. Calling this method will not be blocked by attribute loading or generating the corresponding forest.
Retrieving values from AttributeSubscription
follows the Pull Architecture paradigm (see VersionedDataSource
).
The subscription acts as a buffer to contain the values loaded in the background. Once a value is loaded that is different from
the one that was loaded for that attribute and row before, the version of this data source is promoted and the value is stored
in a buffer. Requesting the values based on the previous version of the value update allows you to retrieve the values that
were updated since the last call.
When calling this method for the first time, use DataVersion.ZERO
as the version.
getUpdate
in interface VersionedDataSource<AttributeSubscriptionUpdate>
fromVersion
- previous version of the data, received with a previous update@NotNull CompletableFuture<DataVersion> loadValues()
Requests that the subscription performs attribute loading.
This will cause the subscription to start a background attribute loading process, based on the currently selected
forest, rows and attributes. The method will return immediately, providing the caller with a Future
. This
Future
may be waited upon to continue getting values via getUpdate(com.almworks.jira.structure.api.pull.DataVersion)
once the loading is done.
The implementation may limit how many processes can be started by a single subscription. If a call to loadValues()
does not start a new background process, it will return the future
from one of the already running processes.
The returned future will be completed either with an updated version of the value update stream, or with an exception if there was a problem.
The future may be canceled, which will cause the loading to cancel. However, the subscription will still be usable and
any consequent calls to loadValues()
will work.
boolean isLoadingValues()
This method can be used to check if the attribute loading is currently taking place for this subscription.
@NotNull RowValues getFullUpdate(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException
A convenience method that calls loadValues()
, waits for the specified amount of time for the loading to complete,
and then provides the loaded value.
Calling this method is similar to calling StructureAttributeService.getAttributeValues(com.almworks.jira.structure.api.forest.ForestSpec, boolean, com.almworks.integers.LongList, java.util.Collection<? extends com.almworks.jira.structure.api.attribute.AttributeSpec<?>>, java.util.function.Consumer<com.almworks.jira.structure.api.attribute.ValuesMeta>)
with a timeout.
timeout
- timeout valueunit
- timeout value unitsInterruptedException
- if this thread was interruptedTimeoutException
- if the values haven't finished loading in the specified time@NotNull RowValues getFullUpdate()
A convenience method that loads all the values, waiting for them for an unspecified amount of time.
Use with care! When writing code that backs a user interface, always use
getFullUpdate(long, TimeUnit)
with a short timeout and come back for updates later using getUpdate(DataVersion)
.
@NotNull LongSet getInaccessibleRows()
Returns the last known list of rows that are not accessible by the owner of the subscription.
The rows may relate to a previous window (rows and forest), so it's not correct to make an assumption that all other rows are accessible. However, if there's data for a row, the row must have been accessible when the value was loaded.
@NotNull Collection<AttributeErrorInfo> drainAttributeErrors()
Retrieves accumulated information about attribute loader errors. Provides only new errors that happened after the last drain. Depending on the implementation strategy, may only return one error per attribute during the lifetime of the subscription.
The accumulated list of errors is cleared when this method is called.
Copyright © 2024 Tempo Software. All Rights Reserved.