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

Interface StructureSynchronizer

All Known Subinterfaces:
Structure2xBackwardCompatibleSynchronizer, UndoingSynchronizer
All Known Implementing Classes:
AbstractSynchronizer
@PublicSpi public interface StructureSynchronizer

A StructureSynchronizer is a pluggable Structure extension that allows you to sync structure with any other aspect of issues, be it links, subtasks or anything else. By implementing this interface and registering it with <structure-synchronizer> module, you define a new type of the synchronizer, which can be accessed from the Structure's synchronization features.

To get started with synchronizers, read section about Synchronization in the Structure user documentation.

You typically implement a synchronizer by extending AbstractSynchronizer.

Two main methods - resync(com.almworks.jira.structure.api.sync.SyncInstance, com.almworks.jira.structure.api.forest.ForestSource) and sync(com.almworks.jira.structure.api.sync.SyncInstance, com.almworks.jira.structure.api.sync.IncrementalSyncData, com.almworks.jira.structure.api.forest.ForestSource) - do the main synchronization job, while other methods are used to create synchronizer configuration and provide necessary information for the Structure plugin.

The instance of StructureSynchronizer represents a type of synchronization and is instantiated only once. The synchronizer instances that the users install into a structure are represented by SyncInstance interface.

Synchronizer is configured with some kind of parameters, which are serialized via storeParameters(Object) and restoreParameters(String) and stored in the database. The type of parameters is up to the synchronizer, whenever parameters are passed they have type Object, so the synchronizer needs to cast them to its parameters type.

Author:
Igor Sereda

  • Method Details

    • isAvailable

      boolean isAvailable()

      Checks if this type of synchronizer is currently available. A synchronizer may not be available if, for example, some feature is turned off; for example, subtasks synchronizer would be unavailable if sub-tasks are turned off in JIRA.

      Returns:
      true if the synchronizer can be used

    • isAutosyncSupported

      boolean isAutosyncSupported()

      Checks if synchronizer supports automatic incremental synchronization.

      If autosync is supported, the synchronizer may be installed and enabled for a structure. If it's not supported, the synchronizer may only be used to run resync (or import/export).

      Returns:
      true if the synchronizer supports autosync with sync(com.almworks.jira.structure.api.sync.SyncInstance, com.almworks.jira.structure.api.sync.IncrementalSyncData, com.almworks.jira.structure.api.forest.ForestSource) method

    • getConfigDescription

      @Nullable String getConfigDescription(@Nullable Object parameters)

      Creates a short one-line description of the configuration parameters, shown in a few places in the Structure interface, such as on the Manage Structure page.

      Parameters:
      parameters - sync parameters
      Returns:
      a string describing the configuration, or null

    • getConfigDescriptionDetails

      @Nullable List<String> getConfigDescriptionDetails(@Nullable Object parameters)
      Creates a list of strings that fully describe the synchronizer's configuration. Used on some pages such as Synchronization Settings.
      Parameters:
      parameters - sync parameters
      Returns:
      a list of lines, describing the configuration, or null

    • getPossibleResyncEffects

      @Nullable List<String> getPossibleResyncEffects(@Nullable Object parameters)
      Creates a list of strings that describe possible changes that might happen during resync
      Parameters:
      parameters - sync parameters
      Returns:
      a list of lines, describing possible changes, or null for no changes

    • storeParameters

      @Nullable String storeParameters(@Nullable Object parameters) throws IOException

      Serializes parameters into a string (for example, JSON) for storing in the database. The result of using 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.

      Parameters:
      parameters - sync parameters
      Returns:
      string representing serialized parameters, e.g., a JSON string
      Throws:
      IOException - if parameters cannot be stored

    • restoreParameters

      @Nullable Object restoreParameters(@Nullable String data) throws IOException
      Deserializes a string previously created storeParameters(Object) into this synchronizer's parameters object.
      Parameters:
      data - string with serialized parameters; never an empty String
      Returns:
      the parameters object
      Throws:
      IOException - if there's a problem reading parameters

    • getDescriptor

      @NotNull SynchronizerDescriptor getDescriptor()
      Returns:
      module descriptor, which is used to get configuration properties from the plugin XML descriptor

    • buildParametersFromForm

      @Nullable Object buildParametersFromForm(@NotNull Map<String,?> formParameters, @NotNull JiraWebActionSupport action)

      Creates an instance of synchronizer parameters. If parameters cannot be created, the method should return null and add errors to the action.

      To read the parameters, you can use StructureUtil.getSingleParameter(java.util.Map, java.lang.String) method and others like it.

      Parameters:
      formParameters - the map from String to values that is constructed from the HTML form parameters sent by the browser
      action - the action executing the update - use it to report errors
      Returns:
      the created parameters, or null if they cannot be created
      See Also:

    • addDefaultFormParameters

      void addDefaultFormParameters(@NotNull Map<String,Object> params)
      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.
      Parameters:
      params - the map of parameters that the synchronizer can add to

    • addFormParameters

      void addFormParameters(@Nullable Object syncParams, @NotNull Map<String,Object> formParams)
      Converts an instance's parameters object to a parameter map for the "Edit Synchronizer' form. This is the inverse of buildParametersFromForm(java.util.Map<java.lang.String, ?>, com.atlassian.jira.web.action.JiraWebActionSupport), which is always called after this method to validate the resulting form and collect error messages.
      Parameters:
      syncParams - synchronizer parameters object
      formParams - writable map to put form parameters into

    • resync

      void resync(@NotNull SyncInstance instance, @NotNull ForestSource forestSource) throws StructureException

      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.

      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:

    • sync

      void sync(@NotNull SyncInstance instance, @NotNull IncrementalSyncData data, @NotNull ForestSource forestSource) throws StructureException

      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.

      Parameters:
      instance - the configured instance of the synchronizer
      data - 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