org.eclipse.equinox.internal.p2.touchpoint.natives

Class SimpleBackupStore

java.lang.Object

org.eclipse.equinox.internal.p2.touchpoint.natives.SimpleBackupStore

All Implemented Interfaces:

IBackupStore

public class SimpleBackupStore
extends java.lang.Object
implements IBackupStore

Stores files by moving them to a uniquely named temporary directory. TheBackupStore remembers filenames and can recreate them in their original location.

Usage

The user of this class should instantiate the BackupStore with some prefix that is meaningful to a human. Uniqueness is obtained without the prefix - the prefix is used to be able to differentiate between different backup directories by a human (in case of crashes etc). If instantiated with a directory this directory will be used to store the backup root directory. If this directory is null, the users home directory is used by default. Once instantiated, use the backup(File) and backupDirectory(File) methods to move files to backup instead of deleting them. A file that is backed up should not be deleted - it is simply moved out of the way. Use backupCopy(File) to move the file out of harms way, but keep a copy of it in the original location. The methods backupAll(File) and backupCopyAll(File) backs up an entire structure. When backup is finished - the user should either call restore() to put all of the files back, or call discard() to remove all of the backed up "copies". If restore() or discard() is not called the backup files will never be deleted. The backup store does not synchronize directories - actions that write new files are responsible for removing them. Overwriting existing files should be done by first backing up the file, and then creating a new file. Modifying a file, should be done by using backupCopy(File) or first making a copy, then backing up the original, and then renaming the copy.

Read Only and Permissions

Directories that are read only (to current user) can not be backed up. Backup is performed using File.renameTo(File) and handling of permissions is operating system dependent. It is expected that a Un*x type system retains the permissions as a file is moved to the backup store and later gets restored. Backup directories are created as they are needed and will (at least on Un*x) inherit the permissions from its parent directory. If a rename can not be performed, the backup store will make a copy and delete the original file. This makes it possible to backup and restore across volume boundaries. When restoring directories they will be created with permissions in a platform specific way (on UN*IX they will inherit the permissions of the parent directory).

Checkpointing

Checkpointing (i.e. to be able to rollback to a particular point) can be implemented by using multiple instances of BackupStore. The client code will need to remember the individual order among the backup stores.

Restartability

Not implemented - it is possible to obtain the name of the backup directories, so manual restore is possible after a crash. An idea is to add persistence to a file, and be able to read it back in again.

A note about exceptions

In general IllegalArgumentException is thrown when attempting an operation that is considered "wrong use", and an IllegalStateException or subclass thereof is thrown on an overall wrong use of BackupStore (i.e. attempt to backup when store has been restored). Some cases of "wrong use" can not be differentiated from I/O errors (like a "file not found" as this could be caused by an entire disk disappearing - in these case an IOException is thrown.

Implementation Note

The backup root directory will contain folders that reflects file system roots. These are encoded using "_" for the UNI*X root directory, "__" for a Windows network mounted directory, and single "drive letter" folders corresponding to Windows drive letters. Typically, on UN*X there will only be a "_" directory in the backup root, and on windows there will typically be a single directory called "C".

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BACKUP_FILE_EXTENSION
static java.lang.String	DIR_PLACEHOLDER

Constructor Summary

Constructors

Constructor and Description
SimpleBackupStore() Generates a BackupStore with a default prefix of ".p2bu" for backup directory and probe file.
SimpleBackupStore(java.io.File buStoreParent, java.lang.String prefix) Generates a BackupStore with a specified prefix for backup directories and probe file.

Method Summary

Modifier and Type	Method and Description
boolean	backup(java.io.File file) Backup the file by moving it to the backup store (for later (optional) restore).
void	backupAll(java.io.File file) Backs up a file, or everything under a directory.
boolean	backupCopy(java.io.File file) Backup the file by leaving a copy of the contents in the original location.
void	backupCopyAll(java.io.File file) Backs up a file, or everything under a directory.
boolean	backupDirectory(java.io.File file) Performs backup of an empty directory.
void	discard() Discards and closes this BackupStore.
java.lang.String	getBackupName() Returns the unique backup name (this is the name of generated backup directories).
java.io.File	getBackupRoot()
protected void	move(java.nio.file.Path source, java.nio.file.Path target) A generic file operation that attempts to move a file.
void	restore() Restores all backup files from backup store.
protected java.nio.file.Path	toBackupPath(java.nio.file.Path path) Converts a source path to a backup path.
protected java.nio.file.Path	toInPlaceBackupPath(java.nio.file.Path path) Converts a path to an in-place backup path.
protected java.nio.file.Path	toInPlaceSourcePath(java.nio.file.Path buPath) Converts a in-place backup path to the original source path.
protected java.nio.file.Path	toSourcePath(java.nio.file.Path buPath) Converts a backup file to the original source file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BACKUP_FILE_EXTENSION

public static final java.lang.String BACKUP_FILE_EXTENSION

See Also:

Constant Field Values

DIR_PLACEHOLDER

public static final java.lang.String DIR_PLACEHOLDER

See Also:

Constant Field Values

Constructor Detail

SimpleBackupStore

public SimpleBackupStore()

Generates a BackupStore with a default prefix of ".p2bu" for backup directory and probe file.

SimpleBackupStore

public SimpleBackupStore(java.io.File buStoreParent,
                         java.lang.String prefix)

Generates a BackupStore with a specified prefix for backup directories and probe file.

Parameters:

buStoreParent - Parent under which the backup store will be created. If null, java.io.tmpdir is used

prefix - Prefix used for human identification of backup stores.

Method Detail

getBackupName

public java.lang.String getBackupName()

Returns the unique backup name (this is the name of generated backup directories).

Specified by:

getBackupName in interface IBackupStore

Returns:

the backup name.

getBackupRoot

public java.io.File getBackupRoot()

Returns:

the parent dire under which backups are created

backup

public boolean backup(java.io.File file)
               throws java.io.IOException

Backup the file by moving it to the backup store (for later (optional) restore). Calling this method with a file that represents a directory is equivalent to calling backupDirectory(File). A file (path) can only be backed up once per BackupStore instance. When the file is backed up, it is moved to a directory under this BackupStore instance's directory with a relative path corresponding to the original relative path from the backup root e.g. the file /A/B/C/foo.txt could be moved to /A/.p2bu_ffffff_ffffff/B/C/foo.txt when /A is the backup root. If a directory is first backed up, and later replaced by a regular file, and this file is backed up (or vice versa) - an IllegalArgumentException is thrown A backup can not be performed on a closed BackupStore.

Specified by:

backup in interface IBackupStore

Parameters:

file - - the file (or directory) to backup

Returns:

true if the file was backed up, false if this file (path) has already been backed up (the file is not moved to the store).

Throws:

java.io.IOException - - if the backup operation fails, or the file does not exist

ClosedBackupStoreException - - if the BackupStore has been closed

java.lang.IllegalArgumentException - - on type mismatch (file vs. directory) of earlier backup, or if file does not exist

backupDirectory

public boolean backupDirectory(java.io.File file)
                        throws java.io.IOException

Performs backup of an empty directory. The directory must be empty before it can be backed up (i.e. similar to a delete of a directory). The called must backup the files of the directory first. A call to backup a directory is really only needed for empty directories as a restore of a file will also restore all of its parent directories.

Specified by:

backupDirectory in interface IBackupStore

Parameters:

file - - the (empty) directory to back up

Returns:

true if the directory was moved to backup. false if the directory was already backed up.

Throws:

java.lang.IllegalArgumentException - if file is not a directory, or is not empty.

java.io.IOException - if directory can not be moved to the backup store, or if the directory is not writeable

backupAll

public void backupAll(java.io.File file)
               throws java.io.IOException

Backs up a file, or everything under a directory.

Specified by:

backupAll in interface IBackupStore

Parameters:

file - - file to backup or directory

Throws:

java.io.IOException - if backup operation failed

backupCopy

public boolean backupCopy(java.io.File file)
                   throws java.io.IOException

Backup the file by leaving a copy of the contents in the original location. Calling this method with a file that represents a directory throws an IllegalArgumentException. A file (path) can only be backed up once per BackupStore instance. When the file is backed up, it is moved to a directory under this BackupStore instance's directory with a relative path corresponding to the original relative path from the backup root e.g. the file /A/B/C/foo.txt could be moved to /A/.p2bu_ffffff_ffffff/B/C/foo.txt when /A is the backup root. If a directory is first backed up, and later replaced by a regular file, and this file is backed up (or vice versa) - an IllegalArgumentException is thrown A backup can not be performed on a closed BackupStore.

Specified by:

backupCopy in interface IBackupStore

Parameters:

file - - the file (or directory) to backup

Returns:

true if the file was backed up, false if this file (path) has already been backed up (the file is not moved to the store).

Throws:

java.io.IOException - if the backup operation fails, or the file does not exist

ClosedBackupStoreException - if the BackupStore has been closed

java.lang.IllegalArgumentException - on type mismatch (file vs. directory) of earlier backup, or if file is a Directory

backupCopyAll

public void backupCopyAll(java.io.File file)
                   throws java.io.IOException

Backs up a file, or everything under a directory. A copy of the backup is left in the original place.

Specified by:

backupCopyAll in interface IBackupStore

Parameters:

file -

Throws:

java.io.IOException

restore

public void restore()
             throws java.io.IOException

Restores all backup files from backup store. Note that restore of a (non directory) file deletes an existing file or directory found in the restore location. When the backup has been restored this BackupStore instance is closed and can not be used for further backup or restore. If there are unrestorable items (non writable directories, or general IO exceptions) these items are written to the log, and the backup copies remain in the file system and can be manually restored (using a simple zip of the backup directory, and an unzip to the buRoot once the problem has been corrected).

Specified by:

restore in interface IBackupStore

Throws:

java.io.IOException - if the backup was not fully restored - unrestored items have been logged.

ClosedBackupStoreException - if the backup is already closed.

discard

public void discard()

Discards and closes this BackupStore. Does nothing if this store is already restored or discarded.

Specified by:

discard in interface IBackupStore

toBackupPath

protected java.nio.file.Path toBackupPath(java.nio.file.Path path)
                                   throws java.io.IOException

Converts a source path to a backup path. Exposed for testing purposes. A leading "root" is transformed to the ROOTCHAR character. On Windows, network mapped drives starts with two separators - and are encoded as two ROOTCHAR. E.g. \\Host\C$\file becomes __\Host\C$\file /users/test/file becomes _/users/test/file C:/file becomes C/file

Parameters:

file - a source file that needs to be backed up

Returns:

a file to which the original content can be backed up

Throws:

java.io.IOException

toSourcePath

protected java.nio.file.Path toSourcePath(java.nio.file.Path buPath)

Converts a backup file to the original source file. ///x/y/z -> ___x/y/z \\x\y\z c:\x\y\z -> c\x\y\z

Parameters:

buPath - an absolute file under buStoreRoot to which some content is backed up.

Returns:

the original source file to which the content can be restored.

toInPlaceBackupPath

protected java.nio.file.Path toInPlaceBackupPath(java.nio.file.Path path)

Converts a path to an in-place backup path. Exposed for testing purposes.

Parameters:

path -

Returns:

a path next to the original where the original will be moved, rather than will be moved

toInPlaceSourcePath

protected java.nio.file.Path toInPlaceSourcePath(java.nio.file.Path buPath)

Converts a in-place backup path to the original source path. Exposed for testing purposes.

Parameters:

path -

Returns:

a source path

move

protected void move(java.nio.file.Path source,
                    java.nio.file.Path target)
             throws java.io.IOException

A generic file operation that attempts to move a file. Exposed in a separate method for testing purposes.

Throws:

java.io.IOException