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 a Write Batch which
12  * holds a collection of updates to apply atomically to a DB.</p>
13  */
14 public interface WriteBatchInterface {
15 
16     /**
17      * Returns the number of updates in the batch.
18      *
19      * @return number of items in WriteBatch
20      */
count()21     int count();
22 
23     /**
24      * <p>Store the mapping "key-&gt;value" in the database.</p>
25      *
26      * @param key the specified key to be inserted.
27      * @param value the value associated with the specified key.
28      * @throws RocksDBException thrown if error happens in underlying native library.
29      */
put(byte[] key, byte[] value)30     void put(byte[] key, byte[] value) throws RocksDBException;
31 
32     /**
33      * <p>Store the mapping "key-&gt;value" within given column
34      * family.</p>
35      *
36      * @param columnFamilyHandle {@link org.rocksdb.ColumnFamilyHandle}
37      *     instance
38      * @param key the specified key to be inserted.
39      * @param value the value associated with the specified key.
40      * @throws RocksDBException thrown if error happens in underlying native library.
41      */
put(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value)42     void put(ColumnFamilyHandle columnFamilyHandle,
43                     byte[] key, byte[] value) throws RocksDBException;
44 
45     /**
46      * <p>Store the mapping "key-&gt;value" within given column
47      * family.</p>
48      *
49      * @param key the specified key to be inserted. It is using position and limit.
50      *     Supports direct buffer only.
51      * @param value the value associated with the specified key. It is using position and limit.
52      *     Supports direct buffer only.
53      * @throws RocksDBException
54      */
put(ByteBuffer key, ByteBuffer value)55     void put(ByteBuffer key, ByteBuffer value) throws RocksDBException;
56 
57     /**
58      * <p>Store the mapping "key-&gt;value" within given column
59      * family.</p>
60      *
61      * @param columnFamilyHandle {@link org.rocksdb.ColumnFamilyHandle}
62      *     instance
63      * @param key the specified key to be inserted. It is using position and limit.
64      *     Supports direct buffer only.
65      * @param value the value associated with the specified key. It is using position and limit.
66      *     Supports direct buffer only.
67      * @throws RocksDBException
68      */
put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value)69     void put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value)
70         throws RocksDBException;
71 
72     /**
73      * <p>Merge "value" with the existing value of "key" in the database.
74      * "key-&gt;merge(existing, value)"</p>
75      *
76      * @param key the specified key to be merged.
77      * @param value the value to be merged with the current value for
78      * the specified key.
79      * @throws RocksDBException thrown if error happens in underlying native library.
80      */
merge(byte[] key, byte[] value)81     void merge(byte[] key, byte[] value) throws RocksDBException;
82 
83     /**
84      * <p>Merge "value" with the existing value of "key" in given column family.
85      * "key-&gt;merge(existing, value)"</p>
86      *
87      * @param columnFamilyHandle {@link ColumnFamilyHandle} instance
88      * @param key the specified key to be merged.
89      * @param value the value to be merged with the current value for
90      * the specified key.
91      * @throws RocksDBException thrown if error happens in underlying native library.
92      */
merge(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value)93     void merge(ColumnFamilyHandle columnFamilyHandle,
94                       byte[] key, byte[] value) throws RocksDBException;
95 
96     /**
97      * <p>If the database contains a mapping for "key", erase it.  Else do nothing.</p>
98      *
99      * @param key Key to delete within database
100      *
101      * @deprecated Use {@link #delete(byte[])}
102      * @throws RocksDBException thrown if error happens in underlying native library.
103      */
104     @Deprecated
remove(byte[] key)105     void remove(byte[] key) throws RocksDBException;
106 
107     /**
108      * <p>If column family contains a mapping for "key", erase it.  Else do nothing.</p>
109      *
110      * @param columnFamilyHandle {@link ColumnFamilyHandle} instance
111      * @param key Key to delete within database
112      *
113      * @deprecated Use {@link #delete(ColumnFamilyHandle, byte[])}
114      * @throws RocksDBException thrown if error happens in underlying native library.
115      */
116     @Deprecated
remove(ColumnFamilyHandle columnFamilyHandle, byte[] key)117     void remove(ColumnFamilyHandle columnFamilyHandle, byte[] key)
118         throws RocksDBException;
119 
120     /**
121      * <p>If the database contains a mapping for "key", erase it.  Else do nothing.</p>
122      *
123      * @param key Key to delete within database
124      * @throws RocksDBException thrown if error happens in underlying native library.
125      */
delete(byte[] key)126     void delete(byte[] key) throws RocksDBException;
127 
128     /**
129      * <p>If column family contains a mapping for "key", erase it.  Else do nothing.</p>
130      *
131      * @param columnFamilyHandle {@link ColumnFamilyHandle} instance
132      * @param key Key to delete within database
133      * @throws RocksDBException thrown if error happens in underlying native library.
134      */
delete(ColumnFamilyHandle columnFamilyHandle, byte[] key)135     void delete(ColumnFamilyHandle columnFamilyHandle, byte[] key)
136         throws RocksDBException;
137 
138     /**
139      * Remove the database entry for {@code key}. Requires that the key exists
140      * and was not overwritten. It is not an error if the key did not exist
141      * in the database.
142      *
143      * If a key is overwritten (by calling {@link #put(byte[], byte[])} multiple
144      * times), then the result of calling SingleDelete() on this key is undefined.
145      * SingleDelete() only behaves correctly if there has been only one Put()
146      * for this key since the previous call to SingleDelete() for this key.
147      *
148      * This feature is currently an experimental performance optimization
149      * for a very specific workload. It is up to the caller to ensure that
150      * SingleDelete is only used for a key that is not deleted using Delete() or
151      * written using Merge(). Mixing SingleDelete operations with Deletes and
152      * Merges can result in undefined behavior.
153      *
154      * @param key Key to delete within database
155      *
156      * @throws RocksDBException thrown if error happens in underlying
157      *     native library.
158      */
159     @Experimental("Performance optimization for a very specific workload")
singleDelete(final byte[] key)160     void singleDelete(final byte[] key) throws RocksDBException;
161 
162     /**
163      * Remove the database entry for {@code key}. Requires that the key exists
164      * and was not overwritten. It is not an error if the key did not exist
165      * in the database.
166      *
167      * If a key is overwritten (by calling {@link #put(byte[], byte[])} multiple
168      * times), then the result of calling SingleDelete() on this key is undefined.
169      * SingleDelete() only behaves correctly if there has been only one Put()
170      * for this key since the previous call to SingleDelete() for this key.
171      *
172      * This feature is currently an experimental performance optimization
173      * for a very specific workload. It is up to the caller to ensure that
174      * SingleDelete is only used for a key that is not deleted using Delete() or
175      * written using Merge(). Mixing SingleDelete operations with Deletes and
176      * Merges can result in undefined behavior.
177      *
178      * @param columnFamilyHandle The column family to delete the key from
179      * @param key Key to delete within database
180      *
181      * @throws RocksDBException thrown if error happens in underlying
182      *     native library.
183      */
184     @Experimental("Performance optimization for a very specific workload")
singleDelete(final ColumnFamilyHandle columnFamilyHandle, final byte[] key)185     void singleDelete(final ColumnFamilyHandle columnFamilyHandle,
186             final byte[] key) throws RocksDBException;
187 
188     /**
189      * <p>If column family contains a mapping for "key", erase it.  Else do nothing.</p>
190      *
191      * @param key Key to delete within database. It is using position and limit.
192      *     Supports direct buffer only.
193      * @throws RocksDBException
194      */
remove(ByteBuffer key)195     void remove(ByteBuffer key) throws RocksDBException;
196 
197     /**
198      * <p>If column family contains a mapping for "key", erase it.  Else do nothing.</p>
199      *
200      * @param columnFamilyHandle {@link ColumnFamilyHandle} instance
201      * @param key Key to delete within database. It is using position and limit.
202      *     Supports direct buffer only.
203      * @throws RocksDBException
204      */
remove(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key)205     void remove(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key) throws RocksDBException;
206 
207     /**
208      * Removes the database entries in the range ["beginKey", "endKey"), i.e.,
209      * including "beginKey" and excluding "endKey". a non-OK status on error. It
210      * is not an error if no keys exist in the range ["beginKey", "endKey").
211      *
212      * Delete the database entry (if any) for "key". Returns OK on success, and a
213      * non-OK status on error. It is not an error if "key" did not exist in the
214      * database.
215      *
216      * @param beginKey
217      *          First key to delete within database (included)
218      * @param endKey
219      *          Last key to delete within database (excluded)
220      * @throws RocksDBException thrown if error happens in underlying native library.
221      */
deleteRange(byte[] beginKey, byte[] endKey)222     void deleteRange(byte[] beginKey, byte[] endKey) throws RocksDBException;
223 
224     /**
225      * Removes the database entries in the range ["beginKey", "endKey"), i.e.,
226      * including "beginKey" and excluding "endKey". a non-OK status on error. It
227      * is not an error if no keys exist in the range ["beginKey", "endKey").
228      *
229      * Delete the database entry (if any) for "key". Returns OK on success, and a
230      * non-OK status on error. It is not an error if "key" did not exist in the
231      * database.
232      *
233      * @param columnFamilyHandle {@link ColumnFamilyHandle} instance
234      * @param beginKey
235      *          First key to delete within database (included)
236      * @param endKey
237      *          Last key to delete within database (excluded)
238      * @throws RocksDBException thrown if error happens in underlying native library.
239      */
deleteRange(ColumnFamilyHandle columnFamilyHandle, byte[] beginKey, byte[] endKey)240     void deleteRange(ColumnFamilyHandle columnFamilyHandle, byte[] beginKey,
241             byte[] endKey) throws RocksDBException;
242 
243     /**
244      * Append a blob of arbitrary size to the records in this batch. The blob will
245      * be stored in the transaction log but not in any other file. In particular,
246      * it will not be persisted to the SST files. When iterating over this
247      * WriteBatch, WriteBatch::Handler::LogData will be called with the contents
248      * of the blob as it is encountered. Blobs, puts, deletes, and merges will be
249      * encountered in the same order in thich they were inserted. The blob will
250      * NOT consume sequence number(s) and will NOT increase the count of the batch
251      *
252      * Example application: add timestamps to the transaction log for use in
253      * replication.
254      *
255      * @param blob binary object to be inserted
256      * @throws RocksDBException thrown if error happens in underlying native library.
257      */
putLogData(byte[] blob)258     void putLogData(byte[] blob) throws RocksDBException;
259 
260     /**
261      * Clear all updates buffered in this batch
262      */
clear()263     void clear();
264 
265     /**
266      * Records the state of the batch for future calls to RollbackToSavePoint().
267      * May be called multiple times to set multiple save points.
268      */
setSavePoint()269     void setSavePoint();
270 
271     /**
272      * Remove all entries in this batch (Put, Merge, Delete, PutLogData) since
273      * the most recent call to SetSavePoint() and removes the most recent save
274      * point.
275      *
276      * @throws RocksDBException if there is no previous call to SetSavePoint()
277      */
rollbackToSavePoint()278     void rollbackToSavePoint() throws RocksDBException;
279 
280     /**
281      * Pop the most recent save point.
282      *
283      * That is to say that it removes the last save point,
284      * which was set by {@link #setSavePoint()}.
285      *
286      * @throws RocksDBException If there is no previous call to
287      *     {@link #setSavePoint()}, an exception with
288      *     {@link Status.Code#NotFound} will be thrown.
289      */
popSavePoint()290     void popSavePoint() throws RocksDBException;
291 
292     /**
293      * Set the maximum size of the write batch.
294      *
295      * @param maxBytes the maximum size in bytes.
296      */
setMaxBytes(long maxBytes)297     void setMaxBytes(long maxBytes);
298 
299     /**
300      * Get the underlying Write Batch.
301      *
302      * @return the underlying WriteBatch.
303      */
getWriteBatch()304     WriteBatch getWriteBatch();
305 }
306