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 2014-2015 ForgeRock AS
025 */
026package org.opends.server.backends.pluggable.spi;
027
028import java.io.Closeable;
029import java.util.Set;
030
031import org.forgerock.opendj.config.server.ConfigException;
032import org.opends.server.types.BackupConfig;
033import org.opends.server.types.BackupDirectory;
034import org.opends.server.types.DirectoryException;
035import org.opends.server.types.RestoreConfig;
036
037/**
038 * This interface abstracts the underlying storage engine,
039 * isolating the pluggable backend generic code from a particular storage engine implementation.
040 */
041public interface Storage extends Closeable
042{
043
044  /**
045   * Starts the import operation.
046   * @return a new Importer object which must be closed to release all resources
047   * @throws ConfigException
048   *           if there is a problem with the configuration
049   * @throws StorageRuntimeException
050   *           if a problem occurs with the underlying storage engine
051   * @see #close() to release all resources once import is finished
052   */
053  Importer startImport() throws ConfigException, StorageRuntimeException;
054
055  /**
056   * Opens the storage engine to allow executing operations on it.
057   *
058   * @param accessMode
059   *           Specify the access mode to this storage.
060   * @throws NullPointerException
061   *           if accessMode is null.
062   * @throws Exception
063   *           if a problem occurs with the underlying storage engine
064   * @see #close() to release all resources once import is finished
065   */
066  void open(AccessMode accessMode) throws Exception;
067
068  /**
069   * Executes a read operation. In case of a read operation rollback, implementations must ensure
070   * the read operation is retried until it succeeds.
071   *
072   * @param <T>
073   *          type of the value returned
074   * @param readOperation
075   *          the read operation to execute
076   * @return the value read by the read operation
077   * @throws Exception
078   *           if a problem occurs with the underlying storage engine
079   */
080  <T> T read(ReadOperation<T> readOperation) throws Exception;
081
082  /**
083   * Executes a write operation. In case of a write operation rollback, implementations must ensure
084   * the write operation is retried until it succeeds.
085   *
086   * @param writeOperation
087   *          the write operation to execute
088   * @throws Exception
089   *           if a problem occurs with the underlying storage engine
090   */
091  void write(WriteOperation writeOperation) throws Exception;
092
093  /**
094   * Remove all files for a backend of this storage.
095   *
096   * @throws StorageRuntimeException if removal fails
097   */
098  void removeStorageFiles() throws StorageRuntimeException;
099
100  /**
101   * Returns the current status of the storage.
102   *
103   * @return the current status of the storage
104   */
105  StorageStatus getStorageStatus();
106
107  /**
108   * Returns {@code true} if this storage supports backup and restore.
109   *
110   * @return {@code true} if this storage supports backup and restore.
111   */
112  boolean supportsBackupAndRestore();
113
114  /**
115   * Creates a backup for this storage.
116   *
117   * @param backupConfig
118   *          The configuration to use when performing the backup.
119   * @throws DirectoryException
120   *           If a Directory Server error occurs.
121   */
122  void createBackup(BackupConfig backupConfig) throws DirectoryException;
123
124  /**
125   * Removes a backup for this storage.
126   *
127   * @param backupDirectory
128   *          The backup directory structure with which the specified backup is
129   *          associated.
130   * @param backupID
131   *          The backup ID for the backup to be removed.
132   * @throws DirectoryException
133   *           If it is not possible to remove the specified backup.
134   */
135  void removeBackup(BackupDirectory backupDirectory, String backupID) throws DirectoryException;
136
137  /**
138   * Restores a backup for this storage.
139   *
140   * @param restoreConfig
141   *          The configuration to use when performing the restore.
142   * @throws DirectoryException
143   *           If a Directory Server error occurs.
144   */
145  void restoreBackup(RestoreConfig restoreConfig) throws DirectoryException;
146
147  /**
148   * Lists the trees that exist in this storage.
149   *
150   * @return a set of {@link TreeName}s representing the trees that exist in this storage
151   */
152  Set<TreeName> listTrees();
153
154  @Override
155  void close();
156}