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 2014-2016 ForgeRock AS.
015 */
016package org.opends.server.backends.pluggable.spi;
017
018import java.io.Closeable;
019
020import net.jcip.annotations.ThreadSafe;
021
022import org.forgerock.opendj.ldap.ByteSequence;
023import org.forgerock.opendj.ldap.ByteString;
024
025/**
026 * Allows to run an import. For performance reasons, imports are run without transactions.
027 * <p>
028 * Since import is multi threaded, implementations must be thread-safe.
029 */
030@ThreadSafe
031public interface Importer extends Closeable
032{
033  /**
034   * Clear the tree whose name is provided. Ensure that an empty tree with the given name exists. If the tree already
035   * exists, all the data it contains will be deleted. If not, an empty tree will be created.
036   *
037   * @param treeName name of the tree to clear
038   */
039  void clearTree(TreeName treeName);
040
041  /**
042   * Creates a record with the provided key and value in the tree identified by the provided name. At the end of this
043   * method, the record is visible by {@link #read(TreeName, ByteSequence)} and {@link #openCursor(TreeName)} methods of
044   * this instance. The record is guaranteed to be persisted only after {@link #close()}.
045   *
046   * @param treeName
047   *          the tree name
048   * @param key
049   *          the new record's key
050   * @param value
051   *          the new record's value
052   */
053  void put(TreeName treeName, ByteSequence key, ByteSequence value);
054
055  /**
056   * Reads the record's value associated to the provided key, in the tree whose name is provided.
057   *
058   * @param treeName
059   *          the tree name
060   * @param key
061   *          the record's key
062   * @return the record's value, or {@code null} if none exists
063   */
064  ByteString read(TreeName treeName, ByteSequence key);
065
066  /**
067   * Opens a cursor on the tree whose name is provided. Cursors are predictable only if there is no pending
068   * {@link #put(TreeName, ByteSequence, ByteSequence)} operations. Indeed, once opened, cursors might not reflect
069   * changes.
070   *
071   * @param treeName
072   *          the tree name
073   * @return a new cursor
074   */
075  SequentialCursor<ByteString, ByteString> openCursor(TreeName treeName);
076
077  @Override
078  void close();
079}
080