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   *
047   * @return a new Importer object which must be closed to release all resources
048   * @throws ConfigException
049   *           if there is a problem with the configuration
050   * @throws StorageRuntimeException
051   *           if a problem occurs with the underlying storage engine
052   * @see #close() to release all resources once import is finished
053   */
054  Importer startImport() throws ConfigException, StorageRuntimeException;
055
056  /**
057   * Opens the storage engine to allow executing operations on it.
058   *
059   * @param accessMode
060   *           Specify the access mode to this storage.
061   * @throws NullPointerException
062   *           if accessMode is null.
063   * @throws Exception
064   *           if a problem occurs with the underlying storage engine
065   * @see #close() to release all resources once import is finished
066   */
067  void open(AccessMode accessMode) throws Exception;
068
069  /**
070   * Executes a read operation. In case of a read operation rollback, implementations must ensure
071   * the read operation is retried until it succeeds.
072   *
073   * @param <T>
074   *          type of the value returned
075   * @param readOperation
076   *          the read operation to execute
077   * @return the value read by the read operation
078   * @throws Exception
079   *           if a problem occurs with the underlying storage engine
080   */
081  <T> T read(ReadOperation<T> readOperation) throws Exception;
082
083  /**
084   * Executes a write operation. In case of a write operation rollback, implementations must ensure
085   * the write operation is retried until it succeeds.
086   *
087   * @param writeOperation
088   *          the write operation to execute
089   * @throws Exception
090   *           if a problem occurs with the underlying storage engine
091   */
092  void write(WriteOperation writeOperation) throws Exception;
093
094  /**
095   * Remove all files for a backend of this storage.
096   *
097   * @throws StorageRuntimeException if removal fails
098   */
099  void removeStorageFiles() throws StorageRuntimeException;
100
101  /**
102   * Returns the current status of the storage.
103   *
104   * @return the current status of the storage
105   */
106  StorageStatus getStorageStatus();
107
108  /**
109   * Returns {@code true} if this storage supports backup and restore.
110   *
111   * @return {@code true} if this storage supports backup and restore.
112   */
113  boolean supportsBackupAndRestore();
114
115  /** {@inheritDoc} */
116  @Override
117  void close();
118
119  /**
120   * Creates a backup for this storage.
121   *
122   * @param backupConfig
123   *          The configuration to use when performing the backup.
124   * @throws DirectoryException
125   *           If a Directory Server error occurs.
126   */
127  void createBackup(BackupConfig backupConfig) throws DirectoryException;
128
129  /**
130   * Removes a backup for this storage.
131   *
132   * @param backupDirectory
133   *          The backup directory structure with which the specified backup is
134   *          associated.
135   * @param backupID
136   *          The backup ID for the backup to be removed.
137   * @throws DirectoryException
138   *           If it is not possible to remove the specified backup.
139   */
140  void removeBackup(BackupDirectory backupDirectory, String backupID) throws DirectoryException;
141
142  /**
143   * Restores a backup for this storage.
144   *
145   * @param restoreConfig
146   *          The configuration to use when performing the restore.
147   * @throws DirectoryException
148   *           If a Directory Server error occurs.
149   */
150  void restoreBackup(RestoreConfig restoreConfig) throws DirectoryException;
151
152  /**
153   * TODO JNR.
154   *
155   * @return TODO JNR
156   */
157  Set<TreeName> listTrees();
158}