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-2015 ForgeRock AS.
015 */
016package org.opends.server.backends.pluggable.spi;
017
018import org.forgerock.opendj.ldap.ByteSequence;
019
020/**
021 * Sequential cursor extended with navigation methods.
022 * @param <K> Type of the record's key
023 * @param <V> Type of the record's value
024 */
025public interface Cursor<K,V> extends SequentialCursor<K, V>
026{
027  /**
028   * Positions the cursor to the provided key if it exists in the tree.
029   *
030   * @param key
031   *          the key where to position the cursor
032   * @return {@code true} if the cursor could be positioned to the key,
033   *         {@code false} otherwise
034   */
035  boolean positionToKey(ByteSequence key);
036
037  /**
038   * Positions the cursor to the provided key if it exists in the tree,
039   * or else the lesser key greater than the provided key in the tree.
040   *
041   * @param key
042   *          the key where to position the cursor
043   * @return {@code true} if the cursor could be positioned to the key
044   *         or the next one, {@code false} otherwise
045   */
046  boolean positionToKeyOrNext(ByteSequence key);
047
048  /**
049   * Positions the cursor to the last key in the tree.
050   *
051   * @return {@code true} if the cursor could be positioned to the last key,
052   *         {@code false} otherwise
053   */
054  boolean positionToLastKey();
055
056  /**
057   * Positions the cursor to the specified index within the tree. Implementations may take advantage
058   * of optimizations provided by the underlying storage, such as counted B-Trees.
059   *
060   * @param index
061   *          the index where the cursor should be positioned, (0 is the first record).
062   * @return {@code true} if the cursor could be positioned to the index, {@code false} otherwise
063   */
064  boolean positionToIndex(int index);
065}