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

Interface StructureListener

@PublicSpi public interface StructureListener

StructureListener allows you to listen to changes to the static content in structures.

Each structure is associated with an ForestSource, which represents its contents visible to the user. The contents consist of static and dynamic rows. Dynamic rows are all rows inserted or removed by generators. Static rows are the rest: the generators themselves and the items that were added manually or by synchronizers. A successful update made via ForestSource.apply(ForestAction, Map) may result in changes to either static content, dynamic content, neither (if it doesn't change the contents) or both. A StructureListener gets notified only of changes to static content.

This interface is closely related to the structure history: basically, you'll get notified about new history entries. The notification can be batched if one logical update results in several history entries.

Examples:

  1. Any change to the structure that doesn't contain generators will be reported.
  2. If you move an issue from one group to another in a structure with Grouper generator, this might only result in a change to an issue - a change to the dynamic content. This change is not reported.
  3. If you add an issue in the domain of the Structure inserter, this may constitute both a change to dynamic content (with regard to the structure where the change is made) and a change to static content (with regard to the inserted structure). Only the latter will be reported.

The listener is called after changes has been persisted.

JIRA Data Center note: only changes happened on the local node are reported.

The listener is called in the same thread that has made the change. When the listener is called no global lock is held by Structure. The listener implementation should be as fast as reasonably possible and not perform any blocking activity (take locks, wait, do I/O).

The order of calls is not guaranteed, that is, if there are two changes - A, and then B, your listener may be notified about B first, and then about A.

Author:
Igor Sereda
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    onStructuresChanged(LongObjMap<HistoryEntry> structureChanges)
    Called after a related group of changes has been written to the database.

  • Method Details

    • onStructuresChanged

      void onStructuresChanged(LongObjMap<HistoryEntry> structureChanges)

      Called after a related group of changes has been written to the database.

      This method is called in the same thread where the changes were made, after the changes were made. If you need to perform blocking activity (take locks, wait, do I/O), it is recommended to offload these tasks to another thread (for example, via StructureJobManager).

      Parameters:
      structureChanges - a map from structure ID into the HistoryEntry describing the changes