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 */ isValid()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 */ seekToFirst()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 */ seekToLast()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 */ seek(byte[] target)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 */ seekForPrev(byte[] target)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 */ seek(ByteBuffer target)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 */ seekForPrev(ByteBuffer target)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 */ next()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 */ prev()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 */ status()116 void status() throws RocksDBException; 117 } 118