Package com.almworks.jira.structure.api.backup

Interface BackupOperation

public interface BackupOperation

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.

  • Method Details

    • setFile

      @NotNull BackupOperation setFile(@NotNull File file)

      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.

      Parameters:
      file - backup file
      Returns:
      this operation
      Throws:
      IllegalArgumentException - if the file is not a valid path

    • setUseZip

      @NotNull BackupOperation setUseZip(boolean useZip)

      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 false.

      Parameters:
      useZip - true if the file content should be compressed
      Returns:
      this operation

    • setBackupStructureIds

      @NotNull BackupOperation setBackupStructureIds(@Nullable LongIterable structureIds)

      Sets the structure IDs to back up. If set to null, all structures will be backed up. If set to an empty collection, no structures will be backed up.

      The default is null (all structures).

      Parameters:
      structureIds - the collection of structure IDs; null means all structures
      Returns:
      this operation

    • setBackupViewIds

      @NotNull BackupOperation setBackupViewIds(@Nullable LongIterable viewIds)

      Sets the view IDs to back up. If set to null, all views will be backed up. If set to an empty collection, no views will be backed up.

      The default is null (all views).

      Parameters:
      viewIds - the collection of view IDs; null means all views
      Returns:
      this operation

    • setBackupAppConfiguration

      @NotNull BackupOperation setBackupAppConfiguration(boolean backupAppConfiguration)

      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 true.

      Parameters:
      backupAppConfiguration - true to back up Structure app configuration and global permissions; false to skip them
      Returns:
      this operation

    • setBackupPerspectives

      @NotNull BackupOperation setBackupPerspectives(boolean backupPerspectives)

      Controls whether perspectives are backed up.

      The default is true.

      Parameters:
      backupPerspectives - true to back up perspectives, false to skip them
      Returns:
      this operation

    • setBackupFavorites

      @NotNull BackupOperation setBackupFavorites(boolean backupFavorites)

      Controls whether users' favorite structures are backed up.

      The default is true.

      Parameters:
      backupFavorites - true to back up favorites, false to skip them
      Returns:
      this operation

    • setBackupSavedColumns

      BackupOperation setBackupSavedColumns(boolean backupSavedColumns)

      Controls whether saved columns are backed up.

      The default is true.

      Parameters:
      backupSavedColumns - true to back up saved columns, false to skip them
      Returns:
      this operation

    • setBackupHistory

      @NotNull BackupOperation setBackupHistory(boolean backupHistory)

      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 false.

      Parameters:
      backupHistory - true if structure history should be backed up
      Returns:
      this operation

    • setBackupGenericItemHistory

      BackupOperation setBackupGenericItemHistory(boolean backupGenericItemHistory)

      Sets the backupGenericItemHistory flag. When the flag is set, full generic item history will be backed up/

      The default is true.

      Parameters:
      backupGenericItemHistory - true if generic item history should be backed up
      Returns:
      this operation

    • setBackupExtensions

      @NotNull BackupOperation setBackupExtensions(@Nullable Set<String> extensionKeys)

      Sets the extension keys to back up. If set to null, all supported extensions will be backed up. If set to an empty set, no extensions will be backed up.

      The default is null (all supported extensions).

      Parameters:
      extensionKeys - the set of extension keys; null means all supported extensions
      Returns:
      this operation

    • backup

      @NotNull BackupOperation backup() throws Exception
      Performs the backup synchronously.
      Returns:
      this operation
      Throws:
      Exception - if file cannot be written or any other problem happens

    • backupToStream

      @NotNull BackupOperation backupToStream(@NotNull OutputStream out) throws Exception

      Performs the backup synchronously, writing the data to the supplied OutputStream instead of a file. Does not close the stream.

      If the 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 setFile(File) is ignored, and getFinalFile() will always throw an IllegalStateException.

      Parameters:
      out - the output stream
      Returns:
      this operation
      Throws:
      Exception - if data cannot be written or any other problem happens

    • getFinalFile

      @NotNull File getFinalFile()
      Returns:
      the file name that will be used for backup - that was set with setFile(java.io.File) method, but probably with added extension.
      Throws:
      IllegalStateException - if the file has not been set