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 import java.nio.ByteBuffer;
   9
  10 /**
  11  * <p>Defines the interface for an Iterator which provides
  12  * access to data one entry at a time. Multiple implementations
  13  * are provided by this library.  In particular, iterators are provided
  14  * to access the contents of a DB and Write Batch.</p>
  15  *
  16  * <p>Multiple threads can invoke const methods on an RocksIterator without
  17  * external synchronization, but if any of the threads may call a
  18  * non-const method, all threads accessing the same RocksIterator must use
  19  * external synchronization.</p>
  20  *
  21  * @see org.rocksdb.RocksObject
  22  */
  23 public interface RocksIteratorInterface {
  24
  25   /**
  26    * <p>An iterator is either positioned at an entry, or
  27    * not valid.  This method returns true if the iterator is valid.</p>
  28    *
  29    * @return true if iterator is valid.
  30    */
  31   boolean isValid();
  32
  33   /**
  34    * <p>Position at the first entry in the source.  The iterator is Valid()
  35    * after this call if the source is not empty.</p>
  36    */
  37   void seekToFirst();
  38
  39   /**
  40    * <p>Position at the last entry in the source.  The iterator is
  41    * valid after this call if the source is not empty.</p>
  42    */
  43   void seekToLast();
  44
  45   /**
  46    * <p>Position at the first entry in the source whose key is at or
  47    * past target.</p>
  48    *
  49    * <p>The iterator is valid after this call if the source contains
  50    * a key that comes at or past target.</p>
  51    *
  52    * @param target byte array describing a key or a
  53    *               key prefix to seek for.
  54    */
  55   void seek(byte[] target);
  56
  57   /**
  58    * <p>Position at the first entry in the source whose key is that or
  59    * before target.</p>
  60    *
  61    * <p>The iterator is valid after this call if the source contains
  62    * a key that comes at or before target.</p>
  63    *
  64    * @param target byte array describing a key or a
  65    *               key prefix to seek for.
  66    */
  67   void seekForPrev(byte[] target);
  68
  69   /**
  70    * <p>Position at the first entry in the source whose key is that or
  71    * past target.</p>
  72    *
  73    * <p>The iterator is valid after this call if the source contains
  74    * a key that comes at or past target.</p>
  75    *
  76    * @param target byte array describing a key or a
  77    *               key prefix to seek for. Supports direct buffer only.
  78    */
  79   void seek(ByteBuffer target);
  80
  81   /**
  82    * <p>Position at the last key that is less than or equal to the target key.</p>
  83    *
  84    * <p>The iterator is valid after this call if the source contains
  85    * a key that comes at or past target.</p>
  86    *
  87    * @param target byte array describing a key or a
  88    *               key prefix to seek for. Supports direct buffer only.
  89    */
  90   void seekForPrev(ByteBuffer target);
  91
  92   /**
  93    * <p>Moves to the next entry in the source.  After this call, Valid() is
  94    * true if the iterator was not positioned at the last entry in the source.</p>
  95    *
  96    * <p>REQUIRES: {@link #isValid()}</p>
  97    */
  98   void next();
  99
 100   /**
 101    * <p>Moves to the previous entry in the source.  After this call, Valid() is
 102    * true if the iterator was not positioned at the first entry in source.</p>
 103    *
 104    * <p>REQUIRES: {@link #isValid()}</p>
 105    */
 106   void prev();
 107
 108   /**
 109    * <p>If an error has occurred, return it.  Else return an ok status.
 110    * If non-blocking IO is requested and this operation cannot be
 111    * satisfied without doing some IO, then this returns Status::Incomplete().</p>
 112    *
 113    * @throws RocksDBException thrown if error happens in underlying
 114    *                          native library.
 115    */
 116   void status() throws RocksDBException;
 117
 118   /**
 119    * <p>If supported, renew the iterator to represent the latest state. The iterator will be
 120    * invalidated after the call. Not supported if {@link ReadOptions#setSnapshot(Snapshot)} was
 121    * specified when creating the iterator.</p>
 122    *
 123    * @throws RocksDBException thrown if the operation is not supported or an error happens in the
 124    *     underlying native library
 125    */
 126   void refresh() throws RocksDBException;
 127 }