com.almworks.jira.structure.api.backup.StructureBackupProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of structure-api Show documentation
Public API for the Structure Plugin for JIRA
The newest version!
package com.almworks.jira.structure.api.backup;

import com.almworks.integers.LongSet;
import com.atlassian.annotations.Internal;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.Map;

/**
 * This is an extension point for Structure backup/restore mechanism. You need to declare its implementation in
 * {@code structure-backup-provider} module in {@code atlassian-plugin.xml}
 *
 * 
Example:
 * {@code }
 *
 * 
You should declare only one {@code structure-backup-provider} module in your app. In case of multiple providers
 * only one of them will be used.
 */
@Internal
public interface StructureBackupProvider {
  /**
   * 
Called during Structure Backup procedure. Use {@code writer} to back up data in XML format.
   * Data is written to {@code extension} section. {@code extension} element has app key and version values as attributes.
   *
   * 
Data format:
   * 
   * <extensions>
   *   <extension key="com.acme.app" version="1.0">
   *     writer adds data here...
   *   </extension>
   *   ...
   * </extensions>
   * 
   *
   * @param writer backup data writer
   * @param structureIds the collection of structure IDs to back up; {@code null} means all structures
   */
  void backup(@NotNull BackupWriter writer, @Nullable LongSet structureIds);

  /**
   * Called during Structure Restore procedure. {@code reader} points to {@code extension} element related to your app.
   * You can get app version at the time of backup by reading "version" attribute of {@code extension} element.
   *
   * 
Attempts to read data outside the {@code extension} section will result in an exception.
   *
   * 
Use {@code errorsReporter} to warn about problems during restore. The errors will be shown on UI after
   * Structure Restore procedure.
   *
   * @param reader backup data reader
   * @param errorsReporter reporter for errors
   */
  void restore(@NotNull BackupReader reader, @NotNull ErrorsReporter errorsReporter);

  /**
   * 
Called during Migrate Structure procedure.
   *
   * 
Works the same way as {@link #restore(BackupReader, ErrorsReporter)} but must restore data only for
   * the provided structures.
   *
   * @param reader backup data reader
   * @param backupToStoredStructureIds keys of this map are IDs of structures to migrate as they occur in a backup;
   *                                   values - corresponding structure IDs in the system
   * @param errorsReporter reporter for migration errors
   * @see #restore(BackupReader, ErrorsReporter)
   * @deprecated since Structure 7.5
   */
  @Deprecated
  void migrate(@NotNull BackupReader reader,
    @NotNull Map backupToStoredStructureIds,
    @NotNull ErrorsReporter errorsReporter);

  /**
   * 
Called during Migrate Structure procedure.
   *
   * Works the same way as {@link #restore(BackupReader, ErrorsReporter)} but must restore data only for
   * the provided structures.
   *
   * @since Structure 7.5
   * @param reader backup data reader
   * @param mapping migrated structures and items ID mapping.
   * @param errorsReporter reporter for migration errors
   */
  default void migrate(@NotNull BackupReader reader,
    @NotNull MigrationMapping mapping,
    @NotNull ErrorsReporter errorsReporter)
  {
    migrate(reader, mapping.getStructureIds(), errorsReporter);
  }
}