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