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