ceph/src/rocksdb/java/src/main/java/org/rocksdb/WriteBatchInterface.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 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      */
  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      */
  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      */
  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      */
  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      */
  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      */
  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      */
  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
 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
 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      */
 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      */
 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")
 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")
 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      */
 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      */
 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      */
 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      */
 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      */
 258     void putLogData(byte[] blob) throws RocksDBException;
 259
 260     /**
 261      * Clear all updates buffered in this batch
 262      */
 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      */
 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      */
 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      */
 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      */
 297     void setMaxBytes(long maxBytes);
 298
 299     /**
 300      * Get the underlying Write Batch.
 301      *
 302      * @return the underlying WriteBatch.
 303      */
 304     WriteBatch getWriteBatch();
 305 }