Backupable.java revision 75fceea66e311b3de58d76a4c993af0fec13dd3d
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at legal-notices/CDDLv1_0.txt.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
* Copyright 2015 ForgeRock AS
*/
/**
* Represents an entity (storage, backend) that can be backed up.
* <p>
* The files to backup must be located under a root directory given by
* {@code getDirectory()} method. They can be located at any depth level
* in a sub-directory. For example, file1, file2 and file3 can be returned as
* files to backup:
* <pre>
* +--- rootDirectory
* | \--- file1
* | \--- subDirectory
* | \--- file2
* | \--- file3
* </pre>
* The {@code getDirectory()} method is also used to provide the root directory used for
* the restore of the backup. The actual restore directory depends on the strategy used for
* restore, which can be one of these two:
* <ul>
* <li>Direct restore: the backup is restored directly in the directory provided by {@code getDirectory()} method.
* It is the responsibility of the backupable entity to manage saving of current files before the restore, and
* to discard them at the end of a successful restore.</li>
* <li>Indirect restore: the backup is restored in a temporary directory, derived from the directory provided
* by {@code getDirectory()} method (suffixed by "restore-[backupID]"). It is the responsibility of the backupable
* entity to switch from the temporary directory to the final one.</li>
* </ul>
* <p>
* The restore strategy is given by {@code isDirectRestore()} method: if {@code true}, it is a direct restore,
* otherwise it is an indirect restore.
* <p>
* Actions taken before and after the restore should be handled in the {@code beforeRestore()} and
* {@code afterRestore()} methods.
*
* @see {@link BackupManager}
*/
public interface Backupable
{
/**
* Returns the files to backup.
*
* @return an iterator of files to backup, which may be empty but never {@code null}
* @throws DirectoryException
* If an error occurs.
*/
/**
* Returns the directory which acts as the root of all files to backup and restore.
*
* @return the root directory
*/
File getDirectory();
/**
* Indicates if restore is done directly in the restore directory.
*
* @return {@code true} if restore is done directly in the restore directory
* provided by {@code getDirectory()} method, or {@code false} if restore
* is done in a temporary directory.
*/
boolean isDirectRestore();
/**
* Called before the restore operation begins.
* <p>
* In case of direct restore, the backupable entity should take any action
* to save a copy of existing data before restore operation. Saving includes
* removing the existing data and copying it in a save directory.
*
* @return the directory where current files are saved. It may be {@code null}
* if not applicable.
* @throws DirectoryException
* If an error occurs.
*/
/**
* Called after the restore operation has finished successfully.
* <p>
* For direct restore, the backupable entity can safely discard the saved copy.
* For indirect restore, the backupable entity should switch the restored directory
* to the final restore directory.
*
* @param restoreDirectory
* The directory in which files have actually been restored. It is never
* {@code null}.
* @param saveDirectory
* The directory in which current files have been saved. It may be
* {@code null} if {@code beforeRestore()} returned {@code null}.
* @throws DirectoryException
* If an error occurs.
*/
}