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 Summary

Modifier and Type	Method and Description
SyncInstance	getInstalledSynchronizer(Long instanceId) Retrieves an instance of installed synchronizer.
List<SyncInstance>	getInstalledSynchronizersForStructure(Long structureId) Retrieves all synchronizer instances installed for the given structure.
SyncInstance	installSynchronizer(StructureSynchronizer synchronizer, Long structureId, Object params, ApplicationUser user) Installs a new synchronizer for a structure.
long	installSynchronizerOffline(String moduleKey, String parameters, Long structureId, String ownerKey, boolean autosyncEnabled) Installs synchronizer based on the serialized data.
boolean	isAutosyncEnabled(Long instanceId) Checks if incremental synchronization is enabled for the specified synchronizer
void	resync(Long instanceId, boolean andEnable, Long processId) Starts full synchronization in the specified direction.
void	resyncOnce(StructureSynchronizer synchronizer, Object params, Long structureId, ApplicationUser user, Long processId) Runs full resync without installing the synchronizer.
void	setAutosyncEnabled(Long instanceId, boolean enabled) Enables or disables the incremental synchronization for the specified synchronizer.
void	uninstallAllSynchronizers() Disables and uninstalls all synchronizers for all structures.
void	uninstallSynchronizer(Long instanceId) Disables and uninstalls synchronizer with the specified ID.
void	uninstallSynchronizersForStructure(Long structureId) Convenience method that disables and uninstalls all synchronizers for the specified structure.
SyncInstance	updateSynchronizer(Long instanceId, Object params, ApplicationUser user) Updates the parameters and/or the owner of an installed synchronizer.

Method Detail

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