]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
11fdf7f2 TL |
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). | |
7c673cae FG |
5 | |
6 | package org.rocksdb; | |
7 | ||
f67539c2 TL |
8 | import java.nio.ByteBuffer; |
9 | ||
7c673cae FG |
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 | /** | |
494da23a | 46 | * <p>Position at the first entry in the source whose key is at or |
7c673cae FG |
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 | ||
11fdf7f2 TL |
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 | ||
f67539c2 TL |
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 | ||
7c673cae FG |
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; | |
20effc67 TL |
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; | |
7c673cae | 127 | } |