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