com.almworks.jira.structure.api.item

Interface ItemTracker

All Superinterfaces:

VersionedDataSource<ItemVersionUpdate>

public interface ItemTracker
extends VersionedDataSource<ItemVersionUpdate>

ItemTracker service provides means to track and report changes to items.

Tracking

Item tracking is pull-based. Client can request which items have been updated since the last time it checked, using version information provided with the previous reply from ItemTracker.

The response may be an incremental update, which lists specific items that were changed, or it may be a full update, which means that possibly any items could have changed. Full update means that the client code needs to recalculate everything that is based on any items, while incremental update allows the client code to recalculate only the parts that are invalidated by the changes.

The version is tracked with two integers - signature and version. Version is a number that is incremented for every reported item. Signature defines the "id space" for versions - versions under different signatures are not comparable and require full update. Signature is needed because the lifespan of the client may exceed the lifespan of the ItemTracker (for example, a remote client), and version number is not persisted - so in the next incarnation, the ItemTracker will have versions starting from 1 again.

Note that it is not guaranteed that signature stays the same during lifespan of a single instance of ItemTracker, however, it may be so depending on the implementation.

Reporting

To report changes, simply call recordChanges(java.lang.Iterable<com.almworks.jira.structure.api.item.ItemIdentity>) method with the changed item IDs.

Note that this component is passive. It does not listen to anything nor does it track the changes to issues or other items. In order to be useful, there should be some other components that listen to changes and report them to the ItemTracker.

Structure contains an active component that captures most of the events that happen to issues and routes them into the ItemTracker. However, you can report updates to issues or to other items at any time if you have anything calculated for those items (whether attributes or dynamic forest) that needs to be recalculated.

When especially large set of changes is reported, ItemTracker may dismiss the detailed changes and force a full update for all clients instead.

Cluster-Wide Service

On JIRA Data Center, this service works across the cluster - changes reported on one node will eventually be seen by the clients pulling updates on all nodes.

It is not guaranteed that the order of the changed items will be the same on all nodes.

NB: The signatures of ItemTracker instances on different nodes will be different, so the efficiency of using ItemTracker very much depends on the session affinity: if the same client is redirected to another node for updates, it will result in a full update and a change of signature.

See Also:

ItemVersionUpdate

Method Summary

Modifier and Type	Method and Description
ItemVersionUpdate	getUpdate(DataVersion fromVersion) Provides an update on the tracked items, based on the previously seen signature and version.
void	recordChange(ItemIdentity id) Convenience method for calling recordChanges(java.lang.Iterable<com.almworks.jira.structure.api.item.ItemIdentity>) for a single item.
void	recordChanges(Iterable<ItemIdentity> ids) Records changes of the specified items.
void	reset() Resets ItemTracker.

Methods inherited from interface VersionedDataSource

getCurrentVersion

Method Detail

getUpdate

@NotNull
ItemVersionUpdate getUpdate(@NotNull
                                     DataVersion fromVersion)

Provides an update on the tracked items, based on the previously seen signature and version.

The response may be an empty update (no changes), full update (unknown changes - you need to recalculate everything), or incremental update (specific items have changed).

To make the first call, use DataVersion.ZERO. That will result in a full update.

Specified by:

getUpdate in interface VersionedDataSource<ItemVersionUpdate>

Parameters:

fromVersion - last seen version with signature

Returns:

empty, full or incremental update to the current version

See Also:

ItemVersionUpdate

recordChange

void recordChange(ItemIdentity id)

Convenience method for calling recordChanges(java.lang.Iterable<com.almworks.jira.structure.api.item.ItemIdentity>) for a single item.

Parameters:

id - item ID

recordChanges

void recordChanges(Iterable<ItemIdentity> ids)

Records changes of the specified items. All clients calling getUpdate(com.almworks.jira.structure.api.pull.DataVersion) afterwards will either receive an incremental update with these ids, or a full update.

Parameters:

ids - changed items IDs

reset

void reset()

Resets ItemTracker. All clients calling getUpdate(com.almworks.jira.structure.api.pull.DataVersion) afterwards will receive full update.