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 *
024 *       Copyright 2008 Sun Microsystems, Inc.
025 *       Portions Copyright 2013-2014 ForgeRock AS.
026 */
027package org.forgerock.opendj.server.core;
028
029import org.forgerock.opendj.ldap.LdapPromise;
030import org.forgerock.opendj.ldap.LdapResultHandler;
031
032/**
033 * A data provider which supports backup and restore functionality.
034 * <p>
035 * TODO: do we need supportsRestore?
036 * <p>
037 * TODO: do we need removeBackup?
038 * <p>
039 * TODO: is there any boiler plate code that abstracted in order to make
040 * implementation simpler? E.g. initialization, crypto.
041 * <p>
042 * FIXME: the async APIs used below are a bad fit. We do not want to return an
043 * {@link LdapException}. We really need a more generic promises API.
044 */
045public interface ArchivableDataProvider {
046
047    /**
048     * Creates a backup of the contents of this data provider in a form that may
049     * be restored at a later date if necessary. This method should only be
050     * called if {@code supportsBackup} returns {@code true}.
051     * <p>
052     * Note that the server will not explicitly initialize this data provider
053     * before calling this method.
054     *
055     * @param backupConfig
056     *            The configuration to use when performing the backup.
057     * @param handler
058     *            A handler which will be notified when the backup completes.
059     * @return A promise representing the completion of the backup.
060     */
061    LdapPromise<Void> createBackup(BackupConfig backupConfig, LdapResultHandler<Void> handler);
062
063    /**
064     * Returns the ID of this data provider.
065     *
066     * @return The ID of this data provider.
067     */
068    DataProviderID getDataProviderID();
069
070    /**
071     * Restores a backup of the contents of this data provider.
072     * <p>
073     * Note that the server will not explicitly initialize this data provider
074     * before calling this method.
075     *
076     * @param restoreConfig
077     *            The configuration to use when performing the restore.
078     * @param handler
079     *            A handler which will be notified when the restore completes.
080     * @return A promise representing the completion of the restore.
081     */
082    LdapPromise<Void> restoreBackup(RestoreConfig restoreConfig, LdapResultHandler<Void> handler);
083
084    /**
085     * Indicates whether this data provider provides a mechanism to perform a
086     * backup of its contents in a form that can be restored later, based on the
087     * provided configuration.
088     *
089     * @param backupConfig
090     *            The configuration of the backup for which to make the
091     *            determination.
092     * @param unsupportedReason
093     *            A buffer to which a message can be appended explaining why the
094     *            requested backup is not supported.
095     * @return {@code true} if this data provider provides a mechanism for
096     *         performing backups with the provided configuration, or
097     *         {@code false} if not.
098     */
099    boolean supportsBackup(BackupConfig backupConfig, StringBuilder unsupportedReason);
100}