@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.
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.
|
void |
addFormParameters(Object syncParams,
Map<String,Object> formParams)
Converts an instance's parameters object to a parameter map for the "Edit Synchronizer' form.
|
Object |
buildParametersFromForm(Map<String,?> formParameters,
JiraWebActionSupport action)
Creates an instance of synchronizer parameters.
|
String |
getConfigDescription(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.
|
List<String> |
getConfigDescriptionDetails(Object parameters)
Creates a list of strings that fully describe the synchronizer's configuration.
|
SynchronizerDescriptor |
getDescriptor() |
List<String> |
getPossibleResyncEffects(Object parameters)
Creates a list of strings that describe possible changes that might happen during resync
|
boolean |
isAutosyncSupported()
Checks if synchronizer supports automatic incremental synchronization.
|
boolean |
isAvailable()
Checks if this type of synchronizer is currently available.
|
Object |
restoreParameters(String data)
Deserializes a string previously created
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.
|
void |
sync(SyncInstance instance,
IncrementalSyncData data,
ForestSource forestSource)
Perform incremental synchronization.
|
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.
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).
sync(com.almworks.jira.structure.api.sync.SyncInstance, com.almworks.jira.structure.api.sync.IncrementalSyncData, com.almworks.jira.structure.api.forest.ForestSource)
method@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
- sync parameters@Nullable List<String> getConfigDescriptionDetails(@Nullable Object parameters)
parameters
- sync parameters@Nullable List<String> getPossibleResyncEffects(@Nullable Object parameters)
parameters
- sync parameters@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
- sync parametersIOException
- if parameters cannot be stored@Nullable Object restoreParameters(@Nullable String data) throws IOException
storeParameters(Object)
into this synchronizer's
parameters object.data
- string with serialized parameters; never an empty StringIOException
- if there's a problem reading parameters@NotNull SynchronizerDescriptor getDescriptor()
@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.
formParameters
- the map from String
to values that is constructed from the HTML form
parameters sent by the browseraction
- the action executing the update - use it to report errorsJiraWebActionSupport.addError(java.lang.String, java.lang.String, com.atlassian.jira.util.ErrorCollection.Reason)
,
JiraWebActionSupport.addErrorMessage(java.lang.String, com.atlassian.jira.util.ErrorCollection.Reason)
,
StructureUtil.getSingleParameter(java.util.Map, java.lang.String)
,
StructureUtil.getSingleParameterLong(java.util.Map, java.lang.String)
,
StructureUtil.getSingleParameterBoolean(java.util.Map, java.lang.String)
void addDefaultFormParameters(@NotNull Map<String,Object> params)
params
- the map of parameters that the synchronizer can add tovoid addFormParameters(@Nullable Object syncParams, @NotNull Map<String,Object> formParams)
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.syncParams
- synchronizer parameters objectformParams
- writable map to put form parameters intovoid 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.
instance
- the configured instance of the synchronizerforestSource
- the source from which to retrieve Forest
for
the synchronized structure and to which to apply Structure updatesStructureException
StructureSyncManager.resync(java.lang.Long, boolean, java.lang.Long)
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.
instance
- the configured instance of the synchronizerdata
- the changes since the last incremental synchronization or resync - in JIRA and in StructureforestSource
- the source from which to retrieve Forest
forStructureException
Copyright © 2024 Tempo Software. All Rights Reserved.