com.almworks.jira.structure.api.backup.BackupOperation 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
There is a newer version: 17.25.3
package com.almworks.jira.structure.api.backup;

import com.almworks.integers.LongIterable;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.io.File;
import java.io.OutputStream;
import java.util.Set;

/**
 * Backup operation allows to set backup parameters and run the backup.
 *
 * Note that for security reasons, if the file name is entered by the user, you must
 * check that it is located under the JIRA home directory, or force the file to be under that
 * directory. This operation trusts the caller and doesn't do any checking.
 *
 * If the specified backup file already exists, it will be overwritten.
 */
public interface BackupOperation {
  /**
   * Sets the target file for the backup. If the filename does not have extension,
   * ".xml" or ".zip" will be appended automatically, depending on the useZip flag.
   *
   * The file must be an absolute path.
   *
   * @param file backup file
   * @return this operation
   * @throws IllegalArgumentException if the file is not a valid path
   */
  @NotNull
  BackupOperation setFile(@NotNull File file);

  /**
   * Sets the useZip flag. When the flag is set, the target file will be a zipped
   * XML file, otherwise it will be a plain XML file.
   *
   * 
The default is {@code false}.
   *
   * @param useZip true if the file content should be compressed
   * @return this operation
   */
  @NotNull
  BackupOperation setUseZip(boolean useZip);

  /**
   * 
Sets the structure IDs to back up. If set to {@code null}, all structures
   * will be backed up. If set to an empty collection, no structures will be backed up.
   *
   * 
The default is {@code null} (all structures).
   *
   * @param structureIds the collection of structure IDs; {@code null} means all structures
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupStructureIds(@Nullable LongIterable structureIds);

  /**
   * 
Sets the view IDs to back up. If set to {@code null}, all views
   * will be backed up. If set to an empty collection, no views will be backed up.
   *
   * 
The default is {@code null} (all views).
   *
   * @param viewIds the collection of view IDs; {@code null} means all views
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupViewIds(@Nullable LongIterable viewIds);

  /**
   * 
Controls whether Structure's app-level configuration and settings are
   * backed up. This includes:
   * 

   *   the list of projects enabled for Structure;
   *   
Structure app permissions (who can use the app, create new structures, etc.);
   *   
attribute sensitivity settings;
   *   
scheduled maintenance settings;
   *   
dark features, and several other settings.
   * 
   *
   * The default is {@code true}.
   *
   * @param backupAppConfiguration {@code true} to back up Structure app configuration
   * and global permissions; {@code false} to skip them
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupAppConfiguration(boolean backupAppConfiguration);

  /**
   * 
Controls whether perspectives are backed up.
   *
   * 
The default is {@code true}.
   *
   * @param backupPerspectives {@code true} to back up perspectives, {@code false} to skip them
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupPerspectives(boolean backupPerspectives);

  /**
   * 
Controls whether users' favorite structures are backed up.
   *
   * 
The default is {@code true}.
   *
   * @param backupFavorites {@code true} to back up favorites, {@code false} to skip them
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupFavorites(boolean backupFavorites);

  /**
   * 
Sets the backupHistory flag. When the flag is set, full structure history
   * will be backed up, otherwise the target file will only contain the current state
   * of the structures.
   *
   * 
The default is {@code false}.
   *
   * @param backupHistory true if structure history should be backed up
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupHistory(boolean backupHistory);

  /**
   * 
Sets the extension keys to back up. If set to {@code null}, all supported extensions
   * will be backed up. If set to an empty set, no extensions will be backed up.
   *
   * 
The default is {@code null} (all supported extensions).
   *
   * @param extensionKeys the set of extension keys; {@code null} means all supported extensions
   * @return this operation
   */
  @NotNull
  BackupOperation setBackupExtensions(@Nullable Set extensionKeys);

  /**
   * Performs the backup synchronously.
   *
   * @return this operation
   * @throws Exception if file cannot be written or any other problem happens
   */
  @NotNull
  BackupOperation backup() throws Exception;

  /**
   * 
Performs the backup synchronously, writing the data to the supplied
   * {@link OutputStream} instead of a file. Does not close the stream.
   *
   * 
If the {@link #setUseZip(boolean) useZip} flag was set, the data will be zipped,
   * otherwise it will be plain XML.
   *
   * When backing up to a stream, the file path supplied to {@link #setFile(File)}
   * is ignored, and {@link #getFinalFile()} will always throw an {@link IllegalStateException}.
   *
   * @param out the output stream
   * @return this operation
   * @throws Exception if data cannot be written or any other problem happens
   */
  @NotNull
  BackupOperation backupToStream(@NotNull OutputStream out) throws Exception;

  /**
   * @return the file name that will be used for backup - that was set with {@link #setFile} method, but probably
   * with added extension.
   *
   * @throws IllegalStateException if the file has not been set
   */
  @NotNull
  File getFinalFile();
}