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

Interface StructureSyncManager

@PublicApi public interface StructureSyncManager

StructureSyncManager manages the whole synchronization engine.

There are several synchronizers in the system, provided by <structure-synchronizer> modules, and each synchronizer may have several instances, represented by SyncInstance. Synchronizer instance is a configured synchronizer, installed onto a specific structure. Synchronizer instances are addressed via unique ID.

This class does not check permissions of the caller. If the calling code works on behalf of a user, it must check whether the user has PermissionLevel.ADMIN permission level on the subject structure.

Author:
Igor Sereda

  • Method Details

    • getInstalledSynchronizer

      @Nullable SyncInstance getInstalledSynchronizer(@Nullable Long instanceId)
      Retrieves an instance of installed synchronizer.
      Parameters:
      instanceId - the ID of the instance
      Returns:
      synchronizer instance, or null if there's no instance with such ID

    • getInstalledSynchronizersForStructure

      @NotNull List<SyncInstance> getInstalledSynchronizersForStructure(@Nullable Long structureId)
      Retrieves all synchronizer instances installed for the given structure.
      Parameters:
      structureId - the ID of the structure
      Returns:
      a list of installed synchronizer instances

    • installSynchronizer

      @NotNull SyncInstance installSynchronizer(@NotNull StructureSynchronizer synchronizer, @NotNull Long structureId, @Nullable Object params, @Nullable ApplicationUser user) throws StructureSynchronizerException
      Installs a new synchronizer for a structure. Synchronizer configuration is persisted - it will be there after JIRA restart - but the synchronizer is not yet enabled for incremental synchronization. To enable the synchronizer, use setAutosyncEnabled(java.lang.Long, boolean) or resync(java.lang.Long, boolean, java.lang.Long).
      Parameters:
      synchronizer - the type of the synchronizer to be installed
      structureId - the ID of the structure
      params - synchronization parameters, of the type accepted by the synchronizer
      user - the user account, under which the synchronization will run. null (anonymous) is not allowed
      Returns:
      the new instance of the synchronizer
      Throws:
      StructureSynchronizerException - if the synchronizer cannot be installed

    • installSynchronizerOffline

      long installSynchronizerOffline(@NotNull String moduleKey, @Nullable String parameters, @NotNull Long structureId, @Nullable String ownerKey, boolean autosyncEnabled) throws StructureSynchronizerException

      Installs synchronizer based on the serialized data. The effect is the same as with installSynchronizer(com.almworks.jira.structure.api.sync.StructureSynchronizer, java.lang.Long, java.lang.Object, com.atlassian.jira.user.ApplicationUser), but the parameters allow to define synchronizer without resolving data into the classes required by the installSynchronizer method.

      This method also allows installing a synchronizer that is currently not present in the system - for example, if a plugin that provides it is disabled. The synchronizer will be installed but SyncInstance will not be created until the synchronizer module is available.

      Parameters:
      moduleKey - the full module key of the synchronizer module
      parameters - serialized parameters (as previously returned by StructureSynchronizer.storeParameters(Object)). Note that empty String is treated the same way as null.
      structureId - the ID of the structure
      ownerKey - user key of the synchronizer owner
      autosyncEnabled - if true, the autosync should be initially enabled for this structure
      Returns:
      the ID of the installed synchronizer instance
      Throws:
      StructureSynchronizerException - if the synchronizer cannot be installed

    • uninstallSynchronizer

      void uninstallSynchronizer(@Nullable Long instanceId)
      Disables and uninstalls synchronizer with the specified ID. If the synchronization is running, it may finish.
      Parameters:
      instanceId - the ID of the synchronizer

    • uninstallAllSynchronizers

      void uninstallAllSynchronizers()
      Disables and uninstalls all synchronizers for all structures.

    • uninstallSynchronizersForStructure

      void uninstallSynchronizersForStructure(@Nullable Long structureId)
      Convenience method that disables and uninstalls all synchronizers for the specified structure.
      Parameters:
      structureId - the ID of the structure

    • isAutosyncEnabled

      boolean isAutosyncEnabled(@Nullable Long instanceId)
      Checks if incremental synchronization is enabled for the specified synchronizer
      Parameters:
      instanceId - the ID of the synchronizer instance
      Returns:
      true if the synchronizer is present and has autosync enabled

    • setAutosyncEnabled

      void setAutosyncEnabled(@Nullable Long instanceId, boolean enabled) throws StructureSynchronizerException
      Enables or disables the incremental synchronization for the specified synchronizer.
      Parameters:
      instanceId - the ID of the synchronizer instance
      enabled - if true, the autosync is enabled
      Throws:
      StructureSynchronizerException - if the incremental synchronization for this synchronizer cannot be enabled

    • resync

      void resync(@Nullable Long instanceId, boolean andEnable, @Nullable Long processId) throws StructureSynchronizerException

      Starts full synchronization in the specified direction.

      Parameters:
      instanceId - the ID of the installed synchronizer
      andEnable - if true, incremental synchronization will be enabled right after the resync job is scheduled, making sure that no changes will be missed
      processId - if not null, resync progress will be reported via this ID
      Throws:
      StructureSynchronizerException - if resync could not be started

    • resyncOnce

      void resyncOnce(@NotNull StructureSynchronizer synchronizer, @Nullable Object params, @NotNull Long structureId, @Nullable ApplicationUser user, @Nullable Long processId) throws StructureSynchronizerException

      Runs full resync without installing the synchronizer. (For example, this is used by Export and Import features.)

      Parameters of the appropriate type are required to run the synchronizer. Those are typically collected from the user via synchronizer module form and created with StructureSynchronizer.buildParametersFromForm(java.util.Map<java.lang.String, ?>, com.atlassian.jira.web.action.JiraWebActionSupport) or can be created by the custom code which is aware of the class of the synchronizer parameters. Note that if StructureSynchronizer.storeParameters(Object) returns an empty String for params, then the synchronizer will be called with null parameters.

      Parameters:
      synchronizer - the synchronizer to run
      params - synchronizer parameters
      structureId - the ID of the structure
      user - the user account under which the synchronization should run
      processId - if not null, resync progress will be reported via this ID
      Throws:
      StructureSynchronizerException - if the synchronization could not be started

    • updateSynchronizer

      @NotNull SyncInstance updateSynchronizer(@Nullable Long instanceId, @Nullable Object params, @Nullable ApplicationUser user) throws StructureSynchronizerException
      Updates the parameters and/or the owner of an installed synchronizer. Incremental synchronization must be disabled when calling this method.
      Parameters:
      instanceId - the ID of the installed synchronizer
      params - new synchronization parameters, of the type accepted by the synchronizer. If null or if StructureSynchronizer.storeParameters(Object) returns null or an empty String for the specified object, the synchronizer will keep using its current parameters.
      user - the user account under which this synchronizer will run after the update. If null, the synchronizer will keep running under its current account
      Returns:
      the new instance of the synchronizer if user is not null or params are not null, otherwise the existing instance
      Throws:
      StructureSynchronizerException - if the synchronizer could not be updated