001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2015-2016 ForgeRock AS.
015 */
016package org.opends.server.api;
017
018import java.io.File;
019import java.nio.file.Path;
020import java.util.ListIterator;
021
022import org.opends.server.types.DirectoryException;
023
024/**
025 * Represents an entity (storage, backend) that can be backed up.
026 * <p>
027 * The files to backup must be located under a root directory given by
028 * {@link #getDirectory()} method. They can be located at any depth level
029 * in a sub-directory. For example, file1, file2 and file3 can be returned as
030 * files to backup:
031 * <pre>
032 * +--- rootDirectory
033 * |   \--- file1
034 * |   \--- subDirectory
035 * |      \--- file2
036 * |      \--- file3
037 * </pre>
038 * The {@code getDirectory()} method is also used to provide the root directory used for
039 * the restore of the backup. The actual restore directory depends on the strategy used for
040 * restore, which can be one of these two:
041 * <ul>
042 *  <li>Direct restore: the backup is restored directly in the directory provided by {@code getDirectory()} method.
043 *   It is the responsibility of the backupable entity to manage saving of current files before the restore, and
044 *   to discard them at the end of a successful restore.</li>
045 *  <li>Indirect restore: the backup is restored in a temporary directory, derived from the directory provided
046 *  by {@code getDirectory()} method (suffixed by "restore-[backupID]"). It is the responsibility of the backupable
047 *  entity to switch from the temporary directory to the final one.</li>
048 * </ul>
049 * <p>
050 * The restore strategy is given by {@code isDirectRestore()} method: if {@code true}, it is a direct restore,
051 * otherwise it is an indirect restore.
052 * <p>
053 * Actions taken before and after the restore should be handled in the {@code beforeRestore()} and
054 * {@link #afterRestore(Path, Path)} methods.
055 *
056 * @see org.opends.server.util.BackupManager
057 */
058public interface Backupable
059{
060  /**
061   * Returns the files to backup.
062   *
063   * @return an iterator of files to backup, which may be empty but never {@code null}
064   * @throws DirectoryException
065   *            If an error occurs.
066   */
067  ListIterator<Path> getFilesToBackup() throws DirectoryException;
068
069  /**
070   * Returns the directory which acts as the root of all files to backup and restore.
071   *
072   * @return the root directory
073   */
074  File getDirectory();
075
076  /**
077   * Indicates if restore is done directly in the restore directory.
078   *
079   * @return {@code true} if restore is done directly in the restore directory
080   *         provided by {@code getDirectory()} method, or {@code false} if restore
081   *         is done in a temporary directory.
082   */
083  boolean isDirectRestore();
084
085  /**
086   * Called before the restore operation begins.
087   * <p>
088   * In case of direct restore, the backupable entity should take any action
089   * to save a copy of existing data before restore operation. Saving includes
090   * removing the existing data and copying it in a save directory.
091   *
092   * @return the directory where current files are saved. It may be {@code null}
093   *         if not applicable.
094   * @throws DirectoryException
095   *            If an error occurs.
096   */
097  Path beforeRestore() throws DirectoryException;
098
099  /**
100   * Called after the restore operation has finished successfully.
101   * <p>
102   * For direct restore, the backupable entity can safely discard the saved copy.
103   * For indirect restore, the backupable entity should switch the restored directory
104   * to the final restore directory.
105   *
106   * @param restoreDirectory
107   *          The directory in which files have actually been restored. It is never
108   *          {@code null}.
109   * @param saveDirectory
110   *          The directory in which current files have been saved. It may be
111   *          {@code null} if {@code beforeRestore()} returned {@code null}.
112   * @throws DirectoryException
113   *           If an error occurs.
114   */
115  void afterRestore(Path restoreDirectory, Path saveDirectory) throws DirectoryException;
116
117}