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 Summary

Modifier and Type	Method and Description
BackupOperation	backup() Performs the backup synchronously.
BackupOperation	backupToStream(OutputStream out) Performs the backup synchronously, writing the data to the supplied OutputStream instead of a file.
File	getFinalFile()
BackupOperation	setBackupAppConfiguration(boolean backupAppConfiguration) Controls whether Structure's app-level configuration and settings are backed up.
BackupOperation	setBackupExtensions(Set<String> extensionKeys) Sets the extension keys to back up.
BackupOperation	setBackupFavorites(boolean backupFavorites) Controls whether users' favorite structures are backed up.
BackupOperation	setBackupGenericItemHistory(boolean backupGenericItemHistory) Sets the backupGenericItemHistory flag.
BackupOperation	setBackupHistory(boolean backupHistory) Sets the backupHistory flag.
BackupOperation	setBackupPerspectives(boolean backupPerspectives) Controls whether perspectives are backed up.
BackupOperation	setBackupSavedColumns(boolean backupSavedColumns) Controls whether saved columns are backed up.
BackupOperation	setBackupStructureIds(LongIterable structureIds) Sets the structure IDs to back up.
BackupOperation	setBackupViewIds(LongIterable viewIds) Sets the view IDs to back up.
BackupOperation	setFile(File file) Sets the target file for the backup.
BackupOperation	setUseZip(boolean useZip) Sets the useZip flag.

Method Detail

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