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