Package org.rocksdb

Class Transaction

java.lang.Object
org.rocksdb.AbstractNativeReference
org.rocksdb.AbstractImmutableNativeReference
org.rocksdb.RocksObject
org.rocksdb.Transaction
All Implemented Interfaces:
AutoCloseable
public class Transaction extends RocksObject
Provides BEGIN/COMMIT/ROLLBACK transactions.

To use transactions, you must first create either an OptimisticTransactionDB or a TransactionDB To create a transaction, use OptimisticTransactionDB.beginTransaction(org.rocksdb.WriteOptions) or TransactionDB.beginTransaction(org.rocksdb.WriteOptions) It is up to the caller to synchronize access to this object.

See samples/src/main/java/OptimisticTransactionSample.java and samples/src/main/java/TransactionSample.java for some simple examples.

  • Method Details

    • setSnapshot

      public void setSnapshot()
      If a transaction has a snapshot set, the transaction will ensure that any keys successfully written (or fetched via getForUpdate(org.rocksdb.ReadOptions, org.rocksdb.ColumnFamilyHandle, byte[], boolean, boolean)) have not been modified outside of this transaction since the time the snapshot was set.

      If a snapshot has not been set, the transaction guarantees that keys have not been modified since the time each key was first written (or fetched via getForUpdate(org.rocksdb.ReadOptions, org.rocksdb.ColumnFamilyHandle, byte[], boolean, boolean)).

      Using #setSnapshot() will provide stricter isolation guarantees at the expense of potentially more transaction failures due to conflicts with other writes.

      Calling #setSnapshot() has no effect on keys written before this function has been called.

      #setSnapshot() may be called multiple times if you would like to change the snapshot used for different operations in this transaction.

      Calling #setSnapshot() will not affect the version of Data returned by get(...) methods. See get(org.rocksdb.ColumnFamilyHandle, org.rocksdb.ReadOptions, byte[]) for more details.

    • setSnapshotOnNextOperation

      public void setSnapshotOnNextOperation()
      Similar to setSnapshot(), but will not change the current snapshot until put/merge/delete/getForUpdate/multiGetForUpdate is called. By calling this function, the transaction will essentially call setSnapshot() for you right before performing the next write/getForUpdate.

      Calling #setSnapshotOnNextOperation() will not affect what snapshot is returned by getSnapshot() until the next write/getForUpdate is executed.

      When the snapshot is created the notifier's snapshotCreated method will be called so that the caller can get access to the snapshot.

      This is an optimization to reduce the likelihood of conflicts that could occur in between the time setSnapshot() is called and the first write/getForUpdate operation. i.e. this prevents the following race-condition:

      txn1->setSnapshot(); txn2->put("A", ...); txn2->commit(); txn1->getForUpdate(opts, "A", ...); * FAIL!

    • setSnapshotOnNextOperation

      public void setSnapshotOnNextOperation(AbstractTransactionNotifier transactionNotifier)
      Similar to setSnapshot(), but will not change the current snapshot until put/merge/delete/getForUpdate/multiGetForUpdate is called. By calling this function, the transaction will essentially call setSnapshot() for you right before performing the next write/getForUpdate.

      Calling setSnapshotOnNextOperation() will not affect what snapshot is returned by getSnapshot() until the next write/getForUpdate is executed.

      When the snapshot is created the AbstractTransactionNotifier.snapshotCreated(Snapshot) method will be called so that the caller can get access to the snapshot.

      This is an optimization to reduce the likelihood of conflicts that could occur in between the time setSnapshot() is called and the first write/getForUpdate operation. i.e. this prevents the following race-condition:

      txn1->setSnapshot(); txn2->put("A", ...); txn2->commit(); txn1->getForUpdate(opts, "A", ...); * FAIL!

      Parameters:
      transactionNotifier - A handler for receiving snapshot notifications for the transaction

    • getSnapshot

      public Snapshot getSnapshot()
      Returns the Snapshot created by the last call to setSnapshot().

      REQUIRED: The returned Snapshot is only valid up until the next time setSnapshot()/setSnapshotOnNextOperation() is called, clearSnapshot() is called, or the Transaction is deleted.

      Returns:
      The snapshot or null if there is no snapshot

    • clearSnapshot

      public void clearSnapshot()
      Clears the current snapshot (i.e. no snapshot will be 'set')

      This removes any snapshot that currently exists or is set to be created on the next update operation (setSnapshotOnNextOperation()).

      Calling #clearSnapshot() has no effect on keys written before this function has been called.

      If a reference to a snapshot was retrieved via getSnapshot(), it will no longer be valid and should be discarded after a call to #clearSnapshot().

    • prepare

      public void prepare() throws RocksDBException
      Prepare the current transaction for 2PC
      Throws:
      RocksDBException

    • commit

      public void commit() throws RocksDBException
      Write all batched keys to the db atomically.

      Returns OK on success.

      May return any error status that could be returned by DB:Write().

      If this transaction was created by an OptimisticTransactionDB Status::Busy() may be returned if the transaction could not guarantee that there are no write conflicts. Status::TryAgain() may be returned if the memtable history size is not large enough (See max_write_buffer_number_to_maintain).

      If this transaction was created by a TransactionDB, Status::Expired() may be returned if this transaction has lived for longer than TransactionOptions.getExpiration().

      Throws:
      RocksDBException - if an error occurs when committing the transaction

    • rollback

      public void rollback() throws RocksDBException
      Discard all batched writes in this transaction.
      Throws:
      RocksDBException - if an error occurs when rolling back the transaction

    • setSavePoint

      public void setSavePoint() throws RocksDBException
      Records the state of the transaction for future calls to rollbackToSavePoint().

      May be called multiple times to set multiple save points.

      Throws:
      RocksDBException - if an error occurs whilst setting a save point

    • rollbackToSavePoint

      public void rollbackToSavePoint() throws RocksDBException
      Undo all operations in this transaction (put, merge, delete, putLogData) since the most recent call to setSavePoint() and removes the most recent setSavePoint().

      If there is no previous call to setSavePoint(), returns Status::NotFound()

      Throws:
      RocksDBException - if an error occurs when rolling back to a save point

    • get

      @Deprecated public byte[] get(ColumnFamilyHandle columnFamilyHandle, ReadOptions readOptions, byte[] key) throws RocksDBException
      Deprecated.
      This function has an inconsistent parameter order compared to other get() methods and is deprecated in favour of one with a consistent order. This function is similar to RocksDB.get(ColumnFamilyHandle, ReadOptions, byte[]) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      readOptions - Read options.
      key - the key to retrieve the value for.
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public byte[] get(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException
      This function is similar to RocksDB.get(ColumnFamilyHandle, ReadOptions, byte[]) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge. If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned. Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).
      Parameters:
      readOptions - Read options.
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the key to retrieve the value for.
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public byte[] get(ReadOptions readOptions, byte[] key) throws RocksDBException
      This function is similar to RocksDB.get(ReadOptions, byte[]) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      readOptions - Read options.
      key - the key to retrieve the value for.
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public GetStatus get(ReadOptions opt, byte[] key, byte[] value) throws RocksDBException
      Get the value associated with the specified key in the default column family
      Parameters:
      opt - ReadOptions instance.
      key - the key to retrieve the value.
      value - the out-value to receive the retrieved value.
      Returns:
      A GetStatus wrapping the result status and the return value size. If GetStatus.status is Ok then GetStatus.requiredSize contains the size of the actual value that matches the specified key in byte. If GetStatus.requiredSize is greater than the length of value, then it indicates that the size of the input buffer value is insufficient and a partial result was returned. If GetStatus.status is NotFound this indicates that the value was not found.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public GetStatus get(ReadOptions opt, ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException
      Get the value associated with the specified key in a specified column family
      Parameters:
      opt - ReadOptions instance.
      columnFamilyHandle - the column family to find the key in
      key - the key to retrieve the value.
      value - the out-value to receive the retrieved value.
      Returns:
      A GetStatus wrapping the result status and the return value size. If GetStatus.status is Ok then GetStatus.requiredSize contains the size of the actual value that matches the specified key in byte. If GetStatus.requiredSize is greater than the length of value, then it indicates that the size of the input buffer value is insufficient and a partial result was returned. If GetStatus.status is NotFound this indicates that the value was not found.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public GetStatus get(ReadOptions opt, ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value) throws RocksDBException
      Get the value associated with the specified key within the specified column family.
      Parameters:
      opt - ReadOptions instance.
      columnFamilyHandle - the column family in which to find the key.
      key - the key to retrieve the value. It is using position and limit. Supports direct buffer only.
      value - the out-value to receive the retrieved value. It is using position and limit. Limit is set according to value size. Supports direct buffer only.
      Returns:
      A GetStatus wrapping the result status and the return value size. If GetStatus.status is Ok then GetStatus.requiredSize contains the size of the actual value that matches the specified key in byte. If GetStatus.requiredSize is greater than the length of value, then it indicates that the size of the input buffer value is insufficient and a partial result was returned. If GetStatus.status is NotFound this indicates that the value was not found.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • get

      public GetStatus get(ReadOptions opt, ByteBuffer key, ByteBuffer value) throws RocksDBException
      Get the value associated with the specified key within the default column family.
      Parameters:
      opt - ReadOptions instance.
      key - the key to retrieve the value. It is using position and limit. Supports direct buffer only.
      value - the out-value to receive the retrieved value. It is using position and limit. Limit is set according to value size. Supports direct buffer only.
      Returns:
      A GetStatus wrapping the result status and the return value size. If GetStatus.status is Ok then GetStatus.requiredSize contains the size of the actual value that matches the specified key in byte. If GetStatus.requiredSize is greater than the length of value, then it indicates that the size of the input buffer value is insufficient and a partial result was returned. If GetStatus.status is NotFound this indicates that the value was not found.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGet

      @Deprecated public byte[][] multiGet(ReadOptions readOptions, List<ColumnFamilyHandle> columnFamilyHandles, byte[][] keys) throws RocksDBException
      Deprecated.
      This function is similar to RocksDB.multiGetAsList(java.util.List<byte[]>) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      readOptions - Read options.
      columnFamilyHandles - List containing ColumnFamilyHandle instances.
      keys - of keys for which values need to be retrieved.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.
      IllegalArgumentException - thrown if the size of passed keys is not equal to the amount of passed column family handles.

    • multiGetAsList

      public List<byte[]> multiGetAsList(ReadOptions readOptions, List<ColumnFamilyHandle> columnFamilyHandles, List<byte[]> keys) throws RocksDBException
      This function is similar to RocksDB.multiGetAsList(ReadOptions, List, List) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      readOptions - Read options.
      columnFamilyHandles - List containing ColumnFamilyHandle instances.
      keys - of keys for which values need to be retrieved.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.
      IllegalArgumentException - thrown if the size of passed keys is not equal to the amount of passed column family handles.

    • multiGet

      @Deprecated public byte[][] multiGet(ReadOptions readOptions, byte[][] keys) throws RocksDBException
      Deprecated.
      This function is similar to RocksDB.multiGetAsList(java.util.List<byte[]>) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      readOptions - Read options.= ColumnFamilyHandle instances.
      keys - of keys for which values need to be retrieved.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGetAsList

      public List<byte[]> multiGetAsList(ReadOptions readOptions, List<byte[]> keys) throws RocksDBException
      This function is similar to RocksDB.multiGetAsList(java.util.List<byte[]>) except it will also read pending changes in this transaction. Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      If ReadOptions.snapshot() is not set, the current version of the key will be read. Calling setSnapshot() does not affect the version of the data returned.

      Note that setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Parameters:
      readOptions - Read options.= ColumnFamilyHandle instances.
      keys - of keys for which values need to be retrieved.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public byte[] getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, byte[] key, boolean exclusive, boolean doValidate) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ColumnFamilyHandle, ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created by an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ColumnFamilyHandle, ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the key to retrieve the value for.
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      doValidate - true if it should validate the snapshot before doing the read
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public byte[] getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, byte[] key, boolean exclusive) throws RocksDBException
      Same as getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean, boolean) with doValidate=true.
      Parameters:
      readOptions - Read options.
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the key to retrieve the value for.
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public byte[] getForUpdate(ReadOptions readOptions, byte[] key, boolean exclusive) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      key - the key to retrieve the value for.
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a byte array storing the value associated with the input key if any. null if it does not find the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, byte[] key, byte[] value, boolean exclusive) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, ByteBuffer key, ByteBuffer value, boolean exclusive) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value, boolean exclusive) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - in which to find the key/value
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value, boolean exclusive, boolean doValidate) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - in which to find the key/value
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      doValidate - true if the transaction should validate the snapshot before doing the read
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value, boolean exclusive) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - in which to find the key/value
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getForUpdate

      public GetStatus getForUpdate(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value, boolean exclusive, boolean doValidate) throws RocksDBException
      Read this key and ensure that this transaction will only be able to be committed if this key is not written outside this transaction after it has first been read (or after the snapshot if a snapshot is set in this transaction). The transaction behavior is the same regardless of whether the key exists or not.

      Note: Currently, this function will return Status::MergeInProgress if the most recent write to the queried key in this batch is a Merge.

      The values returned by this function are similar to RocksDB.get(ReadOptions, byte[]). If value==nullptr, then this function will not read any data, but will still ensure that this key cannot be written to by outside of this transaction.

      If this transaction was created on an OptimisticTransactionDB, getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean) could cause commit() to fail. Otherwise, it could return any error that could be returned by RocksDB.get(ReadOptions, byte[]).

      If this transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain() Status.Code.MergeInProgress if merge operations cannot be resolved.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - in which to find the key/value
      key - the key to retrieve the value for.
      value - the value associated with the input key if * any. The result is undefined in no value is associated with the key
      exclusive - true if the transaction should have exclusive access to the key, otherwise false for shared access.
      doValidate - true if the transaction should validate the snapshot before doing the read
      Returns:
      a status object containing Status.OK if the requested value was read Status.NotFound if the requested value does not exist
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGetForUpdate

      @Deprecated public byte[][] multiGetForUpdate(ReadOptions readOptions, List<ColumnFamilyHandle> columnFamilyHandles, byte[][] keys) throws RocksDBException
      Deprecated.
      A multi-key version of getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean).

      Parameters:
      readOptions - Read options.
      columnFamilyHandles - ColumnFamilyHandle instances
      keys - the keys to retrieve the values for.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGetForUpdateAsList

      public List<byte[]> multiGetForUpdateAsList(ReadOptions readOptions, List<ColumnFamilyHandle> columnFamilyHandles, List<byte[]> keys) throws RocksDBException
      A multi-key version of getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean).

      Parameters:
      readOptions - Read options.
      columnFamilyHandles - ColumnFamilyHandle instances
      keys - the keys to retrieve the values for.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGetForUpdate

      @Deprecated public byte[][] multiGetForUpdate(ReadOptions readOptions, byte[][] keys) throws RocksDBException
      Deprecated.
      A multi-key version of getForUpdate(ReadOptions, byte[], boolean).

      Parameters:
      readOptions - Read options.
      keys - the keys to retrieve the values for.
      Returns:
      Array of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • multiGetForUpdateAsList

      public List<byte[]> multiGetForUpdateAsList(ReadOptions readOptions, List<byte[]> keys) throws RocksDBException
      A multi-key version of getForUpdate(ReadOptions, byte[], boolean).

      Parameters:
      readOptions - Read options.
      keys - the keys to retrieve the values for.
      Returns:
      List of values, one for each key
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • getIterator

      public RocksIterator getIterator()
      Returns an iterator that will iterate on all keys in the default column family including both keys in the DB and uncommitted keys in this transaction.

      Caller is responsible for deleting the returned Iterator.

      The returned iterator is only valid until commit(), rollback(), or rollbackToSavePoint() is called.

      Returns:
      instance of iterator object.

    • getIterator

      public RocksIterator getIterator(ReadOptions readOptions)
      Returns an iterator that will iterate on all keys in the default column family including both keys in the DB and uncommitted keys in this transaction. Setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Caller is responsible for deleting the returned Iterator.

      The returned iterator is only valid until commit(), rollback(), or rollbackToSavePoint() is called.

      Parameters:
      readOptions - Read options.
      Returns:
      instance of iterator object.

    • getIterator

      public RocksIterator getIterator(ReadOptions readOptions, ColumnFamilyHandle columnFamilyHandle)
      Returns an iterator that will iterate on all keys in the column family specified by columnFamilyHandle including both keys in the DB and uncommitted keys in this transaction.

      Setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Caller is responsible for calling AbstractImmutableNativeReference.close() on the returned Iterator.

      The returned iterator is only valid until commit(), rollback(), or rollbackToSavePoint() is called.

      Parameters:
      readOptions - Read options.
      columnFamilyHandle - ColumnFamilyHandle instance
      Returns:
      instance of iterator object.

    • getIterator

      public RocksIterator getIterator(ColumnFamilyHandle columnFamilyHandle)
      Returns an iterator that will iterate on all keys in the column family specified by columnFamilyHandle including both keys in the DB and uncommitted keys in this transaction.

      Setting ReadOptions.setSnapshot(Snapshot) will affect what is read from the DB but will NOT change which keys are read from this transaction (the keys in this transaction do not yet belong to any snapshot and will be fetched regardless).

      Caller is responsible for calling AbstractImmutableNativeReference.close() on the returned Iterator.

      The returned iterator is only valid until commit(), rollback(), or rollbackToSavePoint() is called.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      Returns:
      instance of iterator object.

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.put(ColumnFamilyHandle, byte[], byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException
      Similar to put(ColumnFamilyHandle, byte[], byte[], boolean) but with assumeTracked = false.

      Will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.put(byte[], byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts, byte[][] valueParts, boolean assumeTracked) throws RocksDBException
      Similar to put(ColumnFamilyHandle, byte[], byte[]) but allows you to specify the key and value in several parts that will be concatenated together.
      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      keyParts - the specified key to be inserted.
      valueParts - the value associated with the specified key.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts, byte[][] valueParts) throws RocksDBException
      Similar to put(ColumnFamilyHandle, byte[][], byte[][], boolean) but with with assumeTracked = false.

      Allows you to specify the key and value in several parts that will be concatenated together.

      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      keyParts - the specified key to be inserted.
      valueParts - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ByteBuffer key, ByteBuffer value) throws RocksDBException
      Similar to RocksDB.put(byte[], byte[]), but will also perform conflict checking on the keys be written. If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed. If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()
      Parameters:
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.put(byte[], byte[]), but will also perform conflict checking on the keys be written. If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed. If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()
      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • put

      public void put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value) throws RocksDBException
      Throws:
      RocksDBException

    • put

      public void put(byte[][] keyParts, byte[][] valueParts) throws RocksDBException
      Similar to put(byte[], byte[]) but allows you to specify the key and value in several parts that will be concatenated together
      Parameters:
      keyParts - the specified key to be inserted.
      valueParts - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.merge(ColumnFamilyHandle, byte[], byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to merge the key/value into
      key - the specified key to be merged.
      value - the value associated with the specified key.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException
      Similar to merge(ColumnFamilyHandle, byte[], byte[], boolean) but with assumeTracked = false.

      Will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to merge the key/value into
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(ByteBuffer key, ByteBuffer value) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but will also perform conflict checking on the keys be written. If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed. If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()
      Parameters:
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but will also perform conflict checking on the keys be written. If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed. If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()
      Parameters:
      columnFamilyHandle - in which to apply the merge
      key - the specified key to be merged.
      value - the value associated with the specified key.
      assumeTracked - expects the key be already tracked.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • merge

      public void merge(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but will also perform conflict checking on the keys be written. If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed. If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()
      Parameters:
      columnFamilyHandle - in which to apply the merge
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(ColumnFamilyHandle columnFamilyHandle, byte[] key, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.delete(ColumnFamilyHandle, byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      key - the specified key to be deleted.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException
      Similar to delete(ColumnFamilyHandle, byte[], boolean) but with assumeTracked = false.

      Will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(byte[] key) throws RocksDBException
      Similar to RocksDB.delete(byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts, boolean assumeTracked) throws RocksDBException
      Similar to delete(ColumnFamilyHandle, byte[]) but allows you to specify the key in several parts that will be concatenated together.
      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      keyParts - the specified key to be deleted.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the the key was previous tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts) throws RocksDBException
      Similar todelete(ColumnFamilyHandle, byte[][], boolean) but with assumeTracked = false.

      Allows you to specify the key in several parts that will be concatenated together.

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      keyParts - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • delete

      public void delete(byte[][] keyParts) throws RocksDBException
      Similar to delete(byte[]) but allows you to specify key the in several parts that will be concatenated together.
      Parameters:
      keyParts - the specified key to be deleted
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[] key, boolean assumeTracked) throws RocksDBException
      Similar to RocksDB.singleDelete(ColumnFamilyHandle, byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      key - the specified key to be deleted.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the key was previously tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException
      Similar to singleDelete(ColumnFamilyHandle, byte[], boolean) but with assumeTracked = false.

      will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(byte[] key) throws RocksDBException
      Similar to RocksDB.singleDelete(byte[]), but will also perform conflict checking on the keys be written.

      If this Transaction was created on an OptimisticTransactionDB, these functions should always succeed.

      If this Transaction was created on a TransactionDB, an RocksDBException may be thrown with an accompanying Status when: Status.Code.Busy if there is a write conflict, Status.Code.TimedOut if a lock could not be acquired, Status.Code.TryAgain if the memtable history size is not large enough. See ColumnFamilyOptions.maxWriteBufferNumberToMaintain()

      Parameters:
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts, boolean assumeTracked) throws RocksDBException
      Similar to singleDelete(ColumnFamilyHandle, byte[]) but allows you to specify the key in several parts that will be concatenated together.
      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      keyParts - the specified key to be deleted.
      assumeTracked - true when it is expected that the key is already tracked. More specifically, it means the key was previously tracked in the same savepoint, with the same exclusive flag, and at a lower sequence number. If valid then it skips ValidateSnapshot, throws an error otherwise.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts) throws RocksDBException
      Similar tosingleDelete(ColumnFamilyHandle, byte[][], boolean) but with assumeTracked = false.

      Allows you to specify the key in several parts that will be concatenated together.

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      keyParts - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") public void singleDelete(byte[][] keyParts) throws RocksDBException
      Similar to singleDelete(byte[]) but allows you to specify the key in several parts that will be concatenated together.
      Parameters:
      keyParts - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • putUntracked

      public void putUntracked(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.put(ColumnFamilyHandle, byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike put(ColumnFamilyHandle, byte[], byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • putUntracked

      public void putUntracked(byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.put(byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike put(byte[], byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • putUntracked

      public void putUntracked(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts, byte[][] valueParts) throws RocksDBException
      Similar to putUntracked(ColumnFamilyHandle, byte[], byte[]) but allows you to specify the key and value in several parts that will be concatenated together.
      Parameters:
      columnFamilyHandle - The column family to put the key/value into
      keyParts - the specified key to be inserted.
      valueParts - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • putUntracked

      public void putUntracked(byte[][] keyParts, byte[][] valueParts) throws RocksDBException
      Similar to putUntracked(byte[], byte[]) but allows you to specify the key and value in several parts that will be concatenated together.
      Parameters:
      keyParts - the specified key to be inserted.
      valueParts - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • mergeUntracked

      public void mergeUntracked(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.merge(ColumnFamilyHandle, byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike merge(ColumnFamilyHandle, byte[], byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      columnFamilyHandle - The column family to merge the key/value into
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • mergeUntracked

      public void mergeUntracked(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value) throws RocksDBException
      Similar to RocksDB.merge(ColumnFamilyHandle, byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully. Unlike merge(ColumnFamilyHandle, byte[], byte[]) no conflict checking will be performed for this key. If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.
      Parameters:
      columnFamilyHandle - The column family to merge the key/value into
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • mergeUntracked

      public void mergeUntracked(byte[] key, byte[] value) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike merge(byte[], byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • mergeUntracked

      public void mergeUntracked(ByteBuffer key, ByteBuffer value) throws RocksDBException
      Similar to RocksDB.merge(byte[], byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully. Unlike merge(byte[], byte[]) no conflict checking will be performed for this key. If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.
      Parameters:
      key - the specified key to be merged.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • deleteUntracked

      public void deleteUntracked(ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException
      Similar to RocksDB.delete(ColumnFamilyHandle, byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike delete(ColumnFamilyHandle, byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • deleteUntracked

      public void deleteUntracked(byte[] key) throws RocksDBException
      Similar to RocksDB.delete(byte[]), but operates on the transactions write batch. This write will only happen if this transaction gets committed successfully.

      Unlike delete(byte[]) no conflict checking will be performed for this key.

      If this Transaction was created on a TransactionDB, this function will still acquire locks necessary to make sure this write doesn't cause conflicts in other transactions; This may cause a RocksDBException with associated Status.Code.Busy.

      Parameters:
      key - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • deleteUntracked

      public void deleteUntracked(ColumnFamilyHandle columnFamilyHandle, byte[][] keyParts) throws RocksDBException
      Similar to deleteUntracked(ColumnFamilyHandle, byte[]) but allows you to specify the key in several parts that will be concatenated together.
      Parameters:
      columnFamilyHandle - The column family to delete the key/value from
      keyParts - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • deleteUntracked

      public void deleteUntracked(byte[][] keyParts) throws RocksDBException
      Similar to deleteUntracked(byte[]) but allows you to specify the key in several parts that will be concatenated together.
      Parameters:
      keyParts - the specified key to be deleted.
      Throws:
      RocksDBException - when one of the TransactionalDB conditions described above occurs, or in the case of an unexpected error

    • putLogData

      public void putLogData(byte[] blob)
      Similar to AbstractWriteBatch.putLogData(byte[])
      Parameters:
      blob - binary object to be inserted

    • disableIndexing

      public void disableIndexing()
      By default, all put/merge/delete operations will be indexed in the transaction so that get/getForUpdate/getIterator can search for these keys.

      If the caller does not want to fetch the keys about to be written, they may want to avoid indexing as a performance optimization. Calling #disableIndexing() will turn off indexing for all future put/merge/delete operations until enableIndexing() is called.

      If a key is put/merge/deleted after #disableIndexing() is called and then is fetched via get/getForUpdate/getIterator, the result of the fetch is undefined.

    • enableIndexing

      public void enableIndexing()
      Re-enables indexing after a previous call to disableIndexing()

    • getNumKeys

      public long getNumKeys()
      Returns the number of distinct Keys being tracked by this transaction. If this transaction was created by a TransactionDB, this is the number of keys that are currently locked by this transaction. If this transaction was created by an OptimisticTransactionDB, this is the number of keys that need to be checked for conflicts at commit time.
      Returns:
      the number of distinct Keys being tracked by this transaction

    • getNumPuts

      public long getNumPuts()
      Returns the number of puts that have been applied to this transaction so far.
      Returns:
      the number of puts that have been applied to this transaction

    • getNumDeletes

      public long getNumDeletes()
      Returns the number of deletes that have been applied to this transaction so far.
      Returns:
      the number of deletes that have been applied to this transaction

    • getNumMerges

      public long getNumMerges()
      Returns the number of merges that have been applied to this transaction so far.
      Returns:
      the number of merges that have been applied to this transaction

    • getElapsedTime

      public long getElapsedTime()
      Returns the elapsed time in milliseconds since this Transaction began.
      Returns:
      the elapsed time in milliseconds since this transaction began.

    • getWriteBatch

      public WriteBatchWithIndex getWriteBatch()
      Fetch the underlying write batch that contains all pending changes to be committed.

      Note: You should not write or delete anything from the batch directly and should only use the functions in the Transaction class to write to this transaction.

      Returns:
      The write batch

    • setLockTimeout

      public void setLockTimeout(long lockTimeout)
      Change the value of TransactionOptions.getLockTimeout() (in milliseconds) for this transaction.

      Has no effect on OptimisticTransactions.

      Parameters:
      lockTimeout - the timeout (in milliseconds) for locks used by this transaction.

    • getWriteOptions

      public WriteOptions getWriteOptions()
      Return the WriteOptions that will be used during commit().
      Returns:
      the WriteOptions that will be used

    • setWriteOptions

      public void setWriteOptions(WriteOptions writeOptions)
      Reset the WriteOptions that will be used during commit().
      Parameters:
      writeOptions - The new WriteOptions

    • undoGetForUpdate

      public void undoGetForUpdate(ColumnFamilyHandle columnFamilyHandle, byte[] key)
      If this key was previously fetched in this transaction using getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean)/ multiGetForUpdate(ReadOptions, List, byte[][]), calling #undoGetForUpdate(ColumnFamilyHandle, byte[]) will tell the transaction that it no longer needs to do any conflict checking for this key.

      If a key has been fetched N times via getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean)/ multiGetForUpdate(ReadOptions, List, byte[][]), then #undoGetForUpdate(ColumnFamilyHandle, byte[]) will only have an effect if it is also called N times. If this key has been written to in this transaction, #undoGetForUpdate(ColumnFamilyHandle, byte[]) will have no effect.

      If setSavePoint() has been called after the getForUpdate(ReadOptions, ColumnFamilyHandle, byte[], boolean), #undoGetForUpdate(ColumnFamilyHandle, byte[]) will not have any effect.

      If this Transaction was created by an OptimisticTransactionDB, calling #undoGetForUpdate(ColumnFamilyHandle, byte[]) can affect whether this key is conflict checked at commit time. If this Transaction was created by a TransactionDB, calling #undoGetForUpdate(ColumnFamilyHandle, byte[]) may release any held locks for this key.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the key to retrieve the value for.

    • undoGetForUpdate

      public void undoGetForUpdate(byte[] key)
      If this key was previously fetched in this transaction using getForUpdate(ReadOptions, byte[], boolean)/ multiGetForUpdate(ReadOptions, List, byte[][]), calling #undoGetForUpdate(byte[]) will tell the transaction that it no longer needs to do any conflict checking for this key.

      If a key has been fetched N times via getForUpdate(ReadOptions, byte[], boolean)/ multiGetForUpdate(ReadOptions, List, byte[][]), then #undoGetForUpdate(byte[]) will only have an effect if it is also called N times. If this key has been written to in this transaction, #undoGetForUpdate(byte[]) will have no effect.

      If setSavePoint() has been called after the getForUpdate(ReadOptions, byte[], boolean), #undoGetForUpdate(byte[]) will not have any effect.

      If this Transaction was created by an OptimisticTransactionDB, calling #undoGetForUpdate(byte[]) can affect whether this key is conflict checked at commit time. If this Transaction was created by a TransactionDB, calling #undoGetForUpdate(byte[]) may release any held locks for this key.

      Parameters:
      key - the key to retrieve the value for.

    • rebuildFromWriteBatch

      public void rebuildFromWriteBatch(WriteBatch writeBatch) throws RocksDBException
      Adds the keys from the WriteBatch to the transaction
      Parameters:
      writeBatch - The write batch to read from
      Throws:
      RocksDBException - if an error occurs whilst rebuilding from the write batch.

    • getCommitTimeWriteBatch

      public WriteBatch getCommitTimeWriteBatch()
      Get the Commit time Write Batch.
      Returns:
      the commit time write batch.

    • setLogNumber

      public void setLogNumber(long logNumber)
      Set the log number.
      Parameters:
      logNumber - the log number

    • getLogNumber

      public long getLogNumber()
      Get the log number.
      Returns:
      the log number

    • setName

      public void setName(String transactionName) throws RocksDBException
      Set the name of the transaction.
      Parameters:
      transactionName - the name of the transaction
      Throws:
      RocksDBException - if an error occurs when setting the transaction name.

    • getName

      public String getName()
      Get the name of the transaction.
      Returns:
      the name of the transaction

    • getID

      public long getID()
      Get the ID of the transaction.
      Returns:
      the ID of the transaction.

    • isDeadlockDetect

      public boolean isDeadlockDetect()
      Determine if a deadlock has been detected.
      Returns:
      true if a deadlock has been detected.

    • getWaitingTxns

      public Transaction.WaitingTransactions getWaitingTxns()
      Get the list of waiting transactions.
      Returns:
      The list of waiting transactions.

    • getState

      public Transaction.TransactionState getState()
      Get the execution status of the transaction.

      NOTE: The execution status of an Optimistic Transaction never changes. This is only useful for non-optimistic transactions!

      Returns:
      The execution status of the transaction

    • getId

      @Experimental("NOTE: Experimental feature") public long getId()
      The globally unique id with which the transaction is identified. This id might or might not be set depending on the implementation. Similarly the implementation decides the point in lifetime of a transaction at which it assigns the id. Although currently it is the case, the id is not guaranteed to remain the same across restarts.
      Returns:
      the transaction id.

    • disposeInternal

      protected final void disposeInternal(long handle)
      Specified by:
      disposeInternal in class RocksObject