|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sleepycat.je.util.DbBackup
public class DbBackup
DbBackup is a helper class for stopping and restarting JE background activity in an open environment in order to simplify backup operations. It also lets the application create a backup which can support restoring the environment to a specific point in time.
Backing up without DbBackup: Because JE has an append only log file architecture, it is always possible to do a hot backup without the use of DbBackup by copying all log files (.jdb files) to your archival location. As long as the log files are copied in alphabetical order, (numerical in effect) and all log files are copied, the environment can be successfully backed up without any need to stop database operations or background activity. This means that your backup operation must do a loop to check for the creation of new log files before deciding that the backup is finished. For example:
time files in activity environment t0 000000001.jdb Backup starts copying file 1 000000003.jdb 000000004.jdb t1 000000001.jdb JE log cleaner migrates portion of file 3 to newly 000000004.jdb created file 5 and deletes file 3. Backup finishes 000000005.jdb file 1, starts copying file 4. Backup MUST include file 5 for a consistent backup! t2 000000001.jdb Backup finishes copying file 4, starts and 000000004.jdb finishes file 5, has caught up. Backup ends. 000000005.jdb
In the example above, the backup operation must be sure to copy file 5, which came into existence after the backup had started. If the backup stopped operations at file 4, the backup set would include only file 1 and 4, omitting file 3, which would be an inconsistent set.
Also note that log file 5 may not have filled up before it was copied to archival storage. On the next backup, there might be a newer, larger version of file 5, and that newer version should replace the older file 5 in archive storage.
Backup up with DbBackup
DbBackup helps simplify application backup by defining the set of files that must be copied for each backup operation. If the environment directory has read/write protection, the application must pass DbBackup an open, read/write environment handle.
When entering backup mode, JE determines the set of log files needed for a consistent backup, and freezes all changes to those files. The application can copy that defined set of files and finish operation without checking for the ongoing creation of new files. Also, there will be no need to check for a newer version of the last file on the next backup.
In the example above, if DbBackup was used at t0, the application would only have to copy files 1, 3 and 4 to back up. On a subsequent backup, the application could start its copying at file 5. There would be no need to check for a newer version of file 4.
An example usage:
Environment env = new Environment(...); DbBackup backupHelper = new DbBackup(env); // Find the file number of the last file in the previous backup // persistently, by either checking the backup archive, or saving // state in a persistent file. long lastFileInPrevBackup = ... // Start backup, find out what needs to be copied. backupHelper.startBackup(); try { String[] filesForBackup = backupHelper.getLogFilesInBackupSet(lastFileInPrevBackup); // Copy the files to archival storage. myApplicationCopyMethod(filesForBackup) // Update our knowledge of the last file saved in the backup set, // so we can copy less on the next backup lastFileInPrevBackup = backupHelper.getLastFileInBackupSet(); myApplicationSaveLastFile(lastFileInPrevBackup); } finally { // Remember to exit backup mode, or all log files won't be cleaned // and disk usage will bloat. backupHelper.endBackup(); }
Constructor Summary | |
---|---|
DbBackup(Environment env)
Creates a DbBackup helper for a full backup. |
|
DbBackup(EnvironmentImpl envImpl)
|
|
DbBackup(Environment env,
long lastFileInPrevBackup)
Creates a DbBackup helper for an incremental backup. |
Method Summary | |
---|---|
boolean |
backupIsOpen()
|
void |
endBackup()
End backup mode, thereby re-enabling normal deletion of log files by the JE log cleaner. |
long |
getLastFileInBackupSet()
Can only be called in backup mode, after startBackup() has been called. |
String[] |
getLogFilesInBackupSet()
Get the list of all files that are needed for the environment at the point of time when backup mode started. |
String[] |
getLogFilesInBackupSet(long lastFileInPrevBackup)
Deprecated. replaced by getLogFilesInBackupSet() ; pass
lastFileInPrevBackup to the DbBackup(Environment,long)
constructor. |
void |
invalidate(long fileNumber)
|
void |
setTestHook(TestHook testHook)
|
void |
startBackup()
Start backup mode in order to determine the definitive backup set needed at this point in time. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public DbBackup(Environment env) throws DatabaseException
This is equivalent to using DbBackup(Environment,long)
and
passing -1
for the lastFileInPrevBackup
parameter.
env
- with an open, valid environment handle. If the environment
directory has read/write permissions, the environment handle must be
configured for read/write.
IllegalArgumentException
- if the environment directory has
read/write permissions, but the environment handle is not configured for
read/write.
DatabaseException
public DbBackup(Environment env, long lastFileInPrevBackup) throws DatabaseException
env
- with an open, valid environment handle. If the environment
directory has read/write permissions, the environment handle must be
configured for read/write.lastFileInPrevBackup
- the last file in the previous backup set
when performing an incremental backup, or -1
to perform a full
backup. The first file in this backup set will be the file following
lastFileInPrevBackup
.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.
IllegalArgumentException
- if the environment directory has
read/write permissions, but the environment handle is not configured for
read/write.
DatabaseException
public DbBackup(EnvironmentImpl envImpl) throws DatabaseException
DatabaseException
Method Detail |
---|
public void startBackup() throws DatabaseException
This method determines the last file in the backup set, which is the last log file in the environment at this point in time. Following this method call, all new data will be written to other, new log files. In other words, the last file in the backup set will not be modified after this method returns.
WARNING: After calling this method, deletion of log files in
the backup set by the JE log cleaner will be disabled until endBackup()
is called. To prevent unbounded growth of disk usage, be
sure to call endBackup()
to re-enable log file deletion.
LogOverwriteException
- if a replication
operation is overwriting log files. The backup can not proceed because
files may be invalid. The backup may be attempted at a later time.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.
IllegalStateException
- if a backup is already in progress
DatabaseException
public void endBackup()
LogOverwriteException
- if a replication
operation has overwritten log files. Any copied files should be
considered invalid and discarded. The backup may be attempted at a
later time.
EnvironmentFailureException
- if an unexpected,
internal or environment-wide failure occurs.
IllegalStateException
- if a backup has not been started.public long getLastFileInBackupSet()
IllegalStateException
- if a backup has not been started.public String[] getLogFilesInBackupSet()
The file numbers returned are in the range from the constructor
parameter lastFileInPrevBackup + 1
to the last log file at the
time that startBackup()
was called.
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.
IllegalStateException
- if a backup has not been started.public String[] getLogFilesInBackupSet(long lastFileInPrevBackup)
getLogFilesInBackupSet()
; pass
lastFileInPrevBackup to the DbBackup(Environment,long)
constructor.
lastFileInPrevBackup
- file number of last file copied in the last
backup session, obtained from getLastFileInBackupSet().
EnvironmentFailureException
- if an unexpected, internal or
environment-wide failure occurs.
IllegalStateException
- if a backup has not been started.public boolean backupIsOpen()
public void invalidate(long fileNumber)
public void setTestHook(TestHook testHook)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |