Package org.opends.server.backends.pdb

Class PDBStorage

    • Constructor Detail

      • PDBStorage

        public PDBStorage​(PDBBackendCfg cfg,
                  ServerContext serverContext)
           throws ConfigException
        Creates a new persistit storage with the provided configuration.
        Parameters:
        cfg - The configuration.
        serverContext - This server instance context
        Throws:
        ConfigException - if memory cannot be reserved

    • Method Detail

      • read

        public <T> T read​(ReadOperation<T> operation)
           throws Exception
        Description copied from interface: Storage
        Executes a read operation. In case of a read operation rollback, implementations must propagate the failure to the caller rather than replay the operation: unlike WriteOperation, a ReadOperation is not required to be idempotent, and several of them are not - they write to a stream, print, or accumulate state that a second attempt would double.
        Specified by:
        read in interface Storage
        Type Parameters:
        T - type of the value returned
        Parameters:
        operation - the read operation to execute
        Returns:
        the value read by the read operation
        Throws:
        Exception - if a problem occurs with the underlying storage engine

      • write

        public void write​(WriteOperation operation)
           throws Exception
        Executes a write operation. In case of a write operation rollback, implementations may replay the write operation rather than propagate the failure: a WriteOperation is required to be idempotent for exactly that reason. A replay may be bounded - by a number of attempts, by a window of time, or by both - so that a conflict which does not clear reaches the caller, or may go on for as long as the conflict lasts, the way a writer of a lock based engine waits for a lock; an engine which resolves every conflict by a rollback should bound it by time only, since a healthy write under concurrent load loses several in a row. The pluggable backend holds locks across this method, up to the exclusive lock of an entry container, and every thread waiting on one of those locks waits for as long as this method does.

        A caller that mutates state around this method must handle that bound being spent. Removing an entry from an in-memory map before the write so that a replay still finds the work to do, or reading configuration back out of the operation once it returns, both assume the write is applied; when it is not, this method throws with that state already changed and the transaction not applied, and the caller is the only place that can reconcile the two.

        A transaction the engine rolled back is replayed for as long as the db-txn-retry-time-limit of the backend allows - without limit when it is 0, its default - except that the limit never ends the replays before one has been made. A rollback is how persistit resolves two transactions writing the same key, so a healthy write under concurrent load can lose several of them in a row: a count of attempts failed such writes (#1149), and the replays are bounded by time alone. Without a limit a write waits for its conflict to clear the way a JE writer waits for a lock. A limit is for the configuration change paths of the pluggable backend, which hold an entry container's exclusive lock across this method: every reader of that suffix then waits - untimed and uninterruptibly - until it returns.

        Once the limit is spent the conflict is reported as a StorageRuntimeException naming the backend, the attempts spent, the time they took and the property whose value ran out. It carries the conflict as a suppressed exception rather than as its cause: a cause is unwrapped below and thrown in its place, and EntryContainer.throwAllowedExceptionTypes likewise passes a StorageRuntimeException through untouched only while it has no cause. Given a cause, both hand the caller a bare RollbackException instead, and the message of a StorageRuntimeException wrapping one is just its class name - which is all ERR_OPEN_ENV_FAIL would report when this happens as a backend starts.

        Specified by:
        write in interface Storage
        Parameters:
        operation - the write operation to execute
        Throws:
        Exception - if a problem occurs with the underlying storage engine, including a conflict that outlasted the replays the implementation makes

      • supportsBackupAndRestore

        public boolean supportsBackupAndRestore()
        Description copied from interface: Storage
        Returns true if this storage supports backup and restore.
        Specified by:
        supportsBackupAndRestore in interface Storage
        Returns:
        true if this storage supports backup and restore.

      • getDirectory

        public File getDirectory()
        Description copied from interface: Backupable
        Returns the directory which acts as the root of all files to backup and restore.
        Specified by:
        getDirectory in interface Backupable
        Returns:
        the root directory

      • beforeRestore

        public Path beforeRestore()
                   throws DirectoryException
        Description copied from interface: Backupable
        Called before the restore operation begins.

        In case of direct restore, the backupable entity should take any action to save a copy of existing data before restore operation. Saving includes removing the existing data and copying it in a save directory.

        Specified by:
        beforeRestore in interface Backupable
        Returns:
        the directory where current files are saved. It may be null if not applicable.
        Throws:
        DirectoryException - If an error occurs.

      • isDirectRestore

        public boolean isDirectRestore()
        Description copied from interface: Backupable
        Indicates if restore is done directly in the restore directory.
        Specified by:
        isDirectRestore in interface Backupable
        Returns:
        true if restore is done directly in the restore directory provided by getDirectory() method, or false if restore is done in a temporary directory.

      • afterRestore

        public void afterRestore​(Path restoreDirectory,
                         Path saveDirectory)
                  throws DirectoryException
        Description copied from interface: Backupable
        Called after the restore operation has finished successfully.

        For direct restore, the backupable entity can safely discard the saved copy. For indirect restore, the backupable entity should switch the restored directory to the final restore directory.

        Specified by:
        afterRestore in interface Backupable
        Parameters:
        restoreDirectory - The directory in which files have actually been restored. It is never null.
        saveDirectory - The directory in which current files have been saved. It may be null if beforeRestore() returned null.
        Throws:
        DirectoryException - If an error occurs.

      • createBackup

        public void createBackup​(BackupConfig backupConfig)
                  throws DirectoryException
        Description copied from interface: Storage
        Creates a backup for this storage.
        Specified by:
        createBackup in interface Storage
        Parameters:
        backupConfig - The configuration to use when performing the backup.
        Throws:
        DirectoryException - If a Directory Server error occurs.

      • removeBackup

        public void removeBackup​(BackupDirectory backupDirectory,
                         String backupID)
                  throws DirectoryException
        Description copied from interface: Storage
        Removes a backup for this storage.
        Specified by:
        removeBackup in interface Storage
        Parameters:
        backupDirectory - The backup directory structure with which the specified backup is associated.
        backupID - The backup ID for the backup to be removed.
        Throws:
        DirectoryException - If it is not possible to remove the specified backup.

      • restoreBackup

        public void restoreBackup​(RestoreConfig restoreConfig)
                   throws DirectoryException
        Description copied from interface: Storage
        Restores a backup for this storage.
        Specified by:
        restoreBackup in interface Storage
        Parameters:
        restoreConfig - The configuration to use when performing the restore.
        Throws:
        DirectoryException - If a Directory Server error occurs.

      • listTrees

        public Set<TreeName> listTrees()
        Description copied from interface: Storage
        Lists the trees that exist in this storage.
        Specified by:
        listTrees in interface Storage
        Returns:
        a set of TreeNames representing the trees that exist in this storage

      • isConfigurationChangeAcceptable

        public boolean isConfigurationChangeAcceptable​(PDBBackendCfg newCfg,
                                               List<org.forgerock.i18n.LocalizableMessage> unacceptableReasons)
        Description copied from interface: ConfigurationChangeListener
        Indicates whether the proposed change to the configuration is acceptable to this change listener.
        Specified by:
        isConfigurationChangeAcceptable in interface ConfigurationChangeListener<PDBBackendCfg>
        Parameters:
        newCfg - The new configuration containing the changes.
        unacceptableReasons - A list that can be used to hold messages about why the provided configuration is not acceptable.
        Returns:
        Returns true if the proposed change is acceptable, or false if it is not.

      • getStorageStatus

        public StorageStatus getStorageStatus()
        Description copied from interface: Storage
        Returns the current status of the storage.
        Specified by:
        getStorageStatus in interface Storage
        Returns:
        the current status of the storage

      • diskFullThresholdReached

        public void diskFullThresholdReached​(File directory,
                                     long thresholdInBytes)
        Description copied from interface: DiskSpaceMonitorHandler
        Notifies that the registered "full" threshold have been reached.
        Specified by:
        diskFullThresholdReached in interface DiskSpaceMonitorHandler
        Parameters:
        directory - the directory for which the threshold has been triggered
        thresholdInBytes - the threshold value in bytes

      • diskLowThresholdReached

        public void diskLowThresholdReached​(File directory,
                                    long thresholdInBytes)
        Description copied from interface: DiskSpaceMonitorHandler
        Notifies that the registered "low" threshold have been reached.
        Specified by:
        diskLowThresholdReached in interface DiskSpaceMonitorHandler
        Parameters:
        directory - the directory for which the threshold has been triggered
        thresholdInBytes - the threshold value in bytes

      • diskSpaceRestored

        public void diskSpaceRestored​(File directory,
                              long lowThresholdInBytes,
                              long fullThresholdInBytes)
        Description copied from interface: DiskSpaceMonitorHandler
        Notifies that the free disk space is now above both "low" and "full" thresholds.
        Specified by:
        diskSpaceRestored in interface DiskSpaceMonitorHandler
        Parameters:
        directory - the directory for which the threshold has been triggeredTODO
        lowThresholdInBytes - the low threshold value in bytes
        fullThresholdInBytes - the full threshold value in bytes