com.almworks.jira.structure.api.sync
Interface StructureSyncManager

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

SyncInstance	getInstalledSynchronizer(Long instanceId) Retrieves an instance of installed synchronier.
List<SyncInstance>	getInstalledSynchronizersForStructure(Long structureId) Retrieves all synchronizer instances installed for the given structure.
SyncInstance	installSynchronizer(StructureSynchronizer synchronizer, Long structureId, Object params, com.atlassian.crowd.embedded.api.User user) Installs a new synchronizer for a structure.
long	installSynchronizerOffline(String moduleKey, byte[] parameters, Long structureId, String userName, boolean autosyncEnabled) Installs synchronizer based on the serialized data.
boolean	isAutosyncEnabled(Long instanceId) Checks if incremental synchronization is enabled for the specified synchronizer
long	resync(Long instanceId, SyncDirection direction, boolean andEnable) Starts full synchronization in the specified direction.
long	resyncOnce(StructureSynchronizer synchronizer, Object params, Long structureId, com.atlassian.crowd.embedded.api.User user, SyncDirection direction) 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.

Method Detail

getInstalledSynchronizer

@Nullable
SyncInstance getInstalledSynchronizer(@Nullable
                                               Long instanceId)

Retrieves an instance of installed synchronier.

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
                                         com.atlassian.crowd.embedded.api.User 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, com.almworks.jira.structure.api.sync.SyncDirection, boolean).

Parameters:

synchronizer - 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 means anonymous

Returns:

the new instance of the synchronizer

Throws:

StructureSynchronizerException - if the synchronizer cannot be installed

installSynchronizerOffline

long installSynchronizerOffline(@NotNull
                                String moduleKey,
                                @Nullable
                                byte[] parameters,
                                @NotNull
                                Long structureId,
                                @Nullable
                                String userName,
                                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.crowd.embedded.api.User), 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))

structureId - the ID of the structure

userName - the name of the user who'll run the synchronizer

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(@NotNull
                        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

long resync(Long instanceId,
            SyncDirection direction,
            boolean andEnable)
            throws StructureSynchronizerException

Starts full synchronization in the specified direction.

The method returns job ID, which can then be used to get job feedback from StructureJobManager.

Parameters:

instanceId - the ID of the installed synchronizer

direction - the direction of the resync

andEnable - if true, incremental synchronization will be enabled right after the resync job is scheduled, making sure that no changes will be missed

Returns:

the ID of the asynchronous job that runs the resync

Throws:

StructureSynchronizerException - if resync could not be started

See Also:

StructureJobManager

resyncOnce

long resyncOnce(StructureSynchronizer synchronizer,
                Object params,
                Long structureId,
                com.atlassian.crowd.embedded.api.User user,
                SyncDirection direction)
                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, com.atlassian.jira.web.action.JiraWebActionSupport) or can be created by the custom code which is aware of the class of the synchronizer 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

direction - the direction of the synchronization

Returns:

the ID of the synchronous job that runs the resync

Throws:

StructureSynchronizerException - if the synchronization could not be started