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

Class AbstractSynchronizer

Object
AbstractSynchronizer
All Implemented Interfaces:
StructureSynchronizer
@PublicSpi public abstract class AbstractSynchronizer extends Object implements StructureSynchronizer

AbstractSynchronizer is an abstract base class for the synchronizers that provides basic implementation for some of the StructureSynchronizer methods and offers some utility methods for the synchronizers.

The type of the parameters used by this synchronizer is Map<String, Object>. The basic implementation of the storeParameters(java.lang.Object) and restoreParameters(java.lang.String) methods use Jackson, expecting that map values are either basic Java types or are properly annotated (see, for example, XmlRootElement). todo mention other kinds of annotation?

This class also supports reading and writing some standard properties, such as:

  • The "source of truth" as a SyncDirection todo implement & explain
todo describe audit log and createAuditLogEntryDescription()
Author:
Igor Sereda

  • Field Details

  • Constructor Details

    • AbstractSynchronizer

      protected AbstractSynchronizer(StructureComponents structureComponents)
      Constructs an instance of the synchronizer.
      Parameters:
      structureComponents - services directory

  • Method Details

    • init

      public void init(SynchronizerDescriptor descriptor)
      Called by the module descriptor on initialization.
      Parameters:
      descriptor - descriptor for this module

    • getDescriptor

      @NotNull public SynchronizerDescriptor getDescriptor()
      Specified by:
      getDescriptor in interface StructureSynchronizer
      Returns:
      module descriptor, which can be used to retrieve configuration for this synchronizer from the atlassian-plugin.xml

    • getText

      @NotNull protected String getText(@NotNull String key, Object... parameters)
      Looks up i18n text using the i18n bean from the module's plugin and the current user's locale.
      Parameters:
      key - text key
      parameters - optional parameters
      Returns:
      the text or the key, if not found

    • addDefaultFormParameters

      public void addDefaultFormParameters(@NotNull Map<String,Object> params)
      Description copied from interface: StructureSynchronizer
      Adds to the map the default values for the parameters in the synchronizer parameters form. The default values then will be available for the synchronizer's <form> the first time it's loaded.
      Specified by:
      addDefaultFormParameters in interface StructureSynchronizer
      Parameters:
      params - the map of parameters that the synchronizer can add to

    • storeParameters

      public String storeParameters(Object parameters) throws IOException
      Description copied from interface: StructureSynchronizer

      Serializes parameters into a string (for example, JSON) for storing in the database. The result of using StructureSynchronizer.restoreParameters(String) on the resulting string should reconstruct the same parameters object.

      Empty String ("") returned from this method is treated in the same way as null by Structure. It is recommended to return null instead of empty String.

      Specified by:
      storeParameters in interface StructureSynchronizer
      Parameters:
      parameters - sync parameters
      Returns:
      string representing serialized parameters, e.g., a JSON string
      Throws:
      IOException - if parameters cannot be stored

    • restoreParameters

      public Map<String,Object> restoreParameters(String data) throws IOException
      Description copied from interface: StructureSynchronizer
      Deserializes a string previously created StructureSynchronizer.storeParameters(Object) into this synchronizer's parameters object.
      Specified by:
      restoreParameters in interface StructureSynchronizer
      Parameters:
      data - string with serialized parameters; never an empty String
      Returns:
      the parameters object
      Throws:
      IOException - if there's a problem reading parameters

    • castParameters

      protected Map<String,Object> castParameters(Object p)

    • parametersAsMapObject

      protected MapObject parametersAsMapObject(Object p)
      Returns a MapObject wrapper around the parameters map. MapObject can be useful for reading values.

    • parametersAsNNMapObject

      @NotNull protected MapObject parametersAsNNMapObject(Object p)

    • verifyStructureEditPermissions

      protected boolean verifyStructureEditPermissions(long structureId)
      Checks that the user has at least PermissionLevel.EDIT permission on the specified structure.
      Parameters:
      structureId - the ID of the structure
      Returns:
      true if the current user is allowed to modify the structure

    • verifyStructureEditPermissions

      protected boolean verifyStructureEditPermissions(long structureId, SyncLogger log)
      Checks that the user has at least PermissionLevel.EDIT permission on the specified structure.
      Parameters:
      structureId - the ID of the structure
      log - logging helper that will be used to log warning in case the structure does not exist or is not accessible; in case you don't need synchronizer information in the logs, you can use verifyStructureEditPermissions(long)
      Returns:
      true if the current user is allowed to modify the structure

    • getIssue

      @Nullable protected Issue getIssue(long issueId)
      Retrieves an instance of Issue.
      Parameters:
      issueId - the ID of the issue
      Returns:
      the issue, or null if the issue cannot be found or there is an exception getting it

    • getIssue

      @Nullable protected Issue getIssue(@NotNull String key)
      Retrieves an instance of issue by issue key.
      Parameters:
      key - issue key
      Returns:
      the issue, or null if the issue cannot be found or there is an exception getting it

    • getIssueManager

      @NotNull protected IssueManager getIssueManager()

    • getIssueByRowId

      @Nullable protected Issue getIssueByRowId(long rowId)

    • getIssueIdByRowId

      protected final long getIssueIdByRowId(long rowId)

    • getIssueIdByRow

      public static long getIssueIdByRow(StructureRow structureRow)

    • sync

      public void sync(@NotNull SyncInstance instance, @NotNull IncrementalSyncData syncData, @NotNull ForestSource forestSource) throws StructureException
      Description copied from interface: StructureSynchronizer

      Perform incremental synchronization.

      This method is called when the synchronizer is installed and enabled, and sync manager detects changes in the structure or in any of the tracked items since the last run. The synchronizer can use the updates to check only those items that have been affected and also to choose the direction of the synchronization based on where the changes have occurred. The update is never empty - there is at least one JIRA or Structure change. The Structure changes are specified up to the version of the forest contained in the data.

      The process is decoupled from the changing thread; the synchronization is run as a separate background job with StructureJobManager shortly after the changes have taken place. In JIRA Data Center, the synchronizer might run on a different node from the one where the changes were made.

      Specified by:
      sync in interface StructureSynchronizer
      Parameters:
      instance - the configured instance of the synchronizer
      syncData - the changes since the last incremental synchronization or resync - in JIRA and in Structure
      forestSource - the source from which to retrieve Forest for
      Throws:
      StructureException

    • resync

      public void resync(@NotNull SyncInstance instance, @NotNull ForestSource forestSource) throws StructureException
      Description copied from interface: StructureSynchronizer

      Perform full resync.

      This method is called when the user request full resync or runs Import or Export.

      The implementation of this method should make structure and other aspect of an issue synchronized, inspecting and making changes to all issues that are subject for synchronization according to the synchronizer's configuration.

      The implementation should detect the resync direction on its own: if only one direction is supported, then this direction should be used; if both directions are supported, the direction should be specified in the parameters.

      Specified by:
      resync in interface StructureSynchronizer
      Parameters:
      instance - the configured instance of the synchronizer
      forestSource - the source from which to retrieve Forest for the synchronized structure and to which to apply Structure updates
      Throws:
      StructureException
      See Also:

    • doSync

      @NotNull protected abstract AbstractSynchronizer.SyncRunAuditEntry doSync(@NotNull SyncInstance instance, @NotNull IncrementalSyncData data, @NotNull ForestSource forestSource) throws StructureException
      Throws:
      StructureException

    • doResync

      @NotNull protected abstract AbstractSynchronizer.SyncRunAuditEntry doResync(@NotNull SyncInstance instance, @NotNull ForestSource forestSource) throws StructureException
      Throws:
      StructureException

    • success

      protected static AbstractSynchronizer.SyncRunAuditEntry success(List<MapObject> actions)

    • failure

      protected static AbstractSynchronizer.SyncRunAuditEntry failure(String reason)

    • failure

      protected static AbstractSynchronizer.SyncRunAuditEntry failure(Throwable throwable)

    • failure

      protected static AbstractSynchronizer.SyncRunAuditEntry failure(Throwable throwable, String reason)