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}