ceph/src/rocksdb/java/src/main/java/org/rocksdb/RocksIteratorInterface.java

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5
   6 package org.rocksdb;
   7
   8 /**
   9  * <p>Defines the interface for an Iterator which provides
  10  * access to data one entry at a time. Multiple implementations
  11  * are provided by this library.  In particular, iterators are provided
  12  * to access the contents of a DB and Write Batch.</p>
  13  *
  14  * <p>Multiple threads can invoke const methods on an RocksIterator without
  15  * external synchronization, but if any of the threads may call a
  16  * non-const method, all threads accessing the same RocksIterator must use
  17  * external synchronization.</p>
  18  *
  19  * @see org.rocksdb.RocksObject
  20  */
  21 public interface RocksIteratorInterface {
  22
  23   /**
  24    * <p>An iterator is either positioned at an entry, or
  25    * not valid.  This method returns true if the iterator is valid.</p>
  26    *
  27    * @return true if iterator is valid.
  28    */
  29   boolean isValid();
  30
  31   /**
  32    * <p>Position at the first entry in the source.  The iterator is Valid()
  33    * after this call if the source is not empty.</p>
  34    */
  35   void seekToFirst();
  36
  37   /**
  38    * <p>Position at the last entry in the source.  The iterator is
  39    * valid after this call if the source is not empty.</p>
  40    */
  41   void seekToLast();
  42
  43   /**
  44    * <p>Position at the first entry in the source whose key is that or
  45    * past target.</p>
  46    *
  47    * <p>The iterator is valid after this call if the source contains
  48    * a key that comes at or past target.</p>
  49    *
  50    * @param target byte array describing a key or a
  51    *               key prefix to seek for.
  52    */
  53   void seek(byte[] target);
  54
  55   /**
  56    * <p>Position at the first entry in the source whose key is that or
  57    * before target.</p>
  58    *
  59    * <p>The iterator is valid after this call if the source contains
  60    * a key that comes at or before target.</p>
  61    *
  62    * @param target byte array describing a key or a
  63    *               key prefix to seek for.
  64    */
  65   void seekForPrev(byte[] target);
  66
  67   /**
  68    * <p>Moves to the next entry in the source.  After this call, Valid() is
  69    * true if the iterator was not positioned at the last entry in the source.</p>
  70    *
  71    * <p>REQUIRES: {@link #isValid()}</p>
  72    */
  73   void next();
  74
  75   /**
  76    * <p>Moves to the previous entry in the source.  After this call, Valid() is
  77    * true if the iterator was not positioned at the first entry in source.</p>
  78    *
  79    * <p>REQUIRES: {@link #isValid()}</p>
  80    */
  81   void prev();
  82
  83   /**
  84    * <p>If an error has occurred, return it.  Else return an ok status.
  85    * If non-blocking IO is requested and this operation cannot be
  86    * satisfied without doing some IO, then this returns Status::Incomplete().</p>
  87    *
  88    * @throws RocksDBException thrown if error happens in underlying
  89    *                          native library.
  90    */
  91   void status() throws RocksDBException;
  92 }