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

Class BackupStore

java.lang.Object

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

All Implemented Interfaces:

IBackupStore

public class BackupStore
extends java.lang.Object
implements IBackupStore

Stores files by copying them to a uniquely named temporary directory. The BackupStore 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".

Constructor Summary

Constructors

Constructor and Description
BackupStore() Generates a BackupStore with a default prefix of ".p2bu" for backup directory and probe file.
BackupStore(java.io.File buParentDirectory, 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 moving it to the backup store (for later (optional) restore) but 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.
protected void	finalize() Since a socket port is used to create a unique number, the socket must be closed if this instance is garbage collected and the user of the instance has not either restored or discarded.
java.lang.String	getBackupName() Returns the unique backup name (this is the name of generated backup directories).
java.io.File	getBackupRoot()
protected java.lang.String	getTimeStamp()
protected void	moveToBackup(java.io.File file, java.io.File buFile) Move/rename file to a backup file.
protected boolean	moveToBackupStore(java.io.File file, java.io.File buFile)
protected void	renameInPlace(java.io.File file)
void	restore() Restores all backup files from backup store.

Methods inherited from class java.lang.Object

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

Constructor Detail

BackupStore

public BackupStore()

Generates a BackupStore with a default prefix of ".p2bu" for backup directory and probe file. The full id of the store is on the format "prefix_hextime_hexIPport" - see genUnique() for more info.

BackupStore

public BackupStore(java.io.File buParentDirectory,
                   java.lang.String prefix)

Generates a BackupStore with a specified prefix for backup directories and probe file. The full id of the store is on the format "prefix_hextime_hexipport" - see genUnique() for more info.

Parameters:

buParentDirectory - - name of directory where the backup directory should be created - if null, java.io.tmpdir is used

prefix - - prefix used for human identification of backup directories

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable

Since a socket port is used to create a unique number, the socket must be closed if this instance is garbage collected and the user of the instance has not either restored or discarded.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

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()

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

moveToBackup

protected void moveToBackup(java.io.File file,
                            java.io.File buFile)
                     throws java.io.IOException

Move/rename file to a backup file. Callers of the method must have ensured that the source file exists and the backup file has not been created yet.

Parameters:

file - source file to move; should already exist and must not be directory

buFile - destination backup file to move to; should not exist and must be a directory

Throws:

java.io.IOException - if the backup operation fails

moveToBackupStore

protected boolean moveToBackupStore(java.io.File file,
                                    java.io.File buFile)

renameInPlace

protected void renameInPlace(java.io.File file)

getTimeStamp

protected java.lang.String getTimeStamp()

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

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

backupCopy

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

Backup the file by moving it to the backup store (for later (optional) restore) but 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

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

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