Package 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: