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 finishes
000000004.jdb 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 DbBackupHelper 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 lastFileCopiedInPrevBackup = ...
// Start backup, find out what needs to be copied.
backupHelper.startBackup();
try {
String[] filesForBackup =
backupHelper.getLogFilesInBackupSet(lastFileCopiedInPrevBackup);
// Copy the files to archival storage.
myApplicationCopyMethod(filesForBackup)
// Update our knowlege of the last file saved in the backup set,
// so we can copy less on the next backup
lastFileCopiedInPrevBackup = backupHelper.getLastFileInBackupSet();
myApplicationSaveLastFile(lastFileCopiedInBackupSet);
} finally {
// Remember to exit backup mode, or all log files won't be cleaned
// and disk usage will bloat.
backupHelper.endBackup();
}
|