com.almworks.jira.structure.api.sync

Class AbstractSynchronizer

java.lang.Object

com.almworks.jira.structure.api.sync.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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static interface	AbstractSynchronizer.SyncRunAuditEntry

Field Summary

Fields

Modifier and Type	Field and Description
protected SyncAuditLog	myAuditLog
protected RowManager	myRowManager
protected StructureComponents	myStructureComponents
protected StructureManager	myStructureManager

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractSynchronizer(StructureComponents structureComponents) Constructs an instance of the synchronizer.

Method Summary

Modifier and Type	Method and Description
void	addDefaultFormParameters(Map<String,Object> params) Adds to the map the default values for the parameters in the synchronizer parameters form.
protected Map<String,Object>	castParameters(Object p)
protected abstract AbstractSynchronizer.SyncRunAuditEntry	doResync(SyncInstance instance, ForestSource forestSource)
protected abstract AbstractSynchronizer.SyncRunAuditEntry	doSync(SyncInstance instance, IncrementalSyncData data, ForestSource forestSource)
protected static AbstractSynchronizer.SyncRunAuditEntry	failure(String reason)
protected static AbstractSynchronizer.SyncRunAuditEntry	failure(Throwable throwable)
protected static AbstractSynchronizer.SyncRunAuditEntry	failure(Throwable throwable, String reason)
SynchronizerDescriptor	getDescriptor()
protected com.atlassian.jira.issue.Issue	getIssue(long issueId) Retrieves an instance of Issue.
protected com.atlassian.jira.issue.Issue	getIssue(String key) Retrieves an instance of issue by issue key.
protected com.atlassian.jira.issue.Issue	getIssueByRowId(long rowId)
static long	getIssueIdByRow(StructureRow structureRow)
protected long	getIssueIdByRowId(long rowId)
protected com.atlassian.jira.issue.IssueManager	getIssueManager()
protected String	getText(String key, Object... parameters) Looks up i18n text using the i18n bean from the module's plugin and the current user's locale.
void	init(SynchronizerDescriptor descriptor) Called by the module descriptor on initialization.
protected MapObject	parametersAsMapObject(Object p) Returns a MapObject wrapper around the parameters map.
protected MapObject	parametersAsNNMapObject(Object p)
Map<String,Object>	restoreParameters(String data) Deserializes a string previously created StructureSynchronizer.storeParameters(Object) into this synchronizer's parameters object.
void	resync(SyncInstance instance, ForestSource forestSource) Perform full resync.
String	storeParameters(Object parameters) Serializes parameters into a string (for example, JSON) for storing in the database.
protected static AbstractSynchronizer.SyncRunAuditEntry	success(List<MapObject> actions)
void	sync(SyncInstance instance, IncrementalSyncData syncData, ForestSource forestSource) Perform incremental synchronization.
protected boolean	verifyStructureEditPermissions(long structureId) Checks that the user has at least PermissionLevel.EDIT permission on the specified structure.
protected boolean	verifyStructureEditPermissions(long structureId, SyncLogger log) Checks that the user has at least PermissionLevel.EDIT permission on the specified structure.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.almworks.jira.structure.api.sync.StructureSynchronizer

addFormParameters, buildParametersFromForm, getConfigDescription, getConfigDescriptionDetails, getPossibleResyncEffects, isAutosyncSupported, isAvailable

Field Detail

myStructureComponents

protected final StructureComponents myStructureComponents

myStructureManager

protected final StructureManager myStructureManager

myRowManager

protected final RowManager myRowManager

myAuditLog

protected final SyncAuditLog myAuditLog

Constructor Detail

AbstractSynchronizer

protected AbstractSynchronizer(StructureComponents structureComponents)

Constructs an instance of the synchronizer.

Parameters:

structureComponents - services directory

Method Detail

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 com.atlassian.jira.issue.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 com.atlassian.jira.issue.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 com.atlassian.jira.issue.IssueManager getIssueManager()

getIssueByRowId

@Nullable
protected com.atlassian.jira.issue.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:

StructureSyncManager.resync(java.lang.Long, boolean, java.lang.Long)

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)