Package org.rocksdb

Class Transaction

    • Method Detail

      • 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

      • 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().

      • 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,
                     java.nio.ByteBuffer key,
                     java.nio.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,
                     java.nio.ByteBuffer key,
                     java.nio.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,
                         java.util.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.
        java.lang.IllegalArgumentException - thrown if the size of passed keys is not equal to the amount of passed column family handles.

      • multiGetAsList

        public java.util.List<byte[]> multiGetAsList​(ReadOptions readOptions,
                                             java.util.List<ColumnFamilyHandle> columnFamilyHandles,
                                             java.util.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.
        java.lang.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 java.util.List<byte[]> multiGetAsList​(ReadOptions readOptions,
                                             java.util.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,
                           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,
                              java.nio.ByteBuffer key,
                              java.nio.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,
                              java.nio.ByteBuffer key,
                              java.nio.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,
                              java.nio.ByteBuffer key,
                              java.nio.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.

      • multiGetForUpdateAsList

        public java.util.List<byte[]> multiGetForUpdateAsList​(ReadOptions readOptions,
                                                      java.util.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.

      • 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​(ColumnFamilyHandle columnFamilyHandle,
                java.nio.ByteBuffer key,
                java.nio.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​(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

      • 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[][] 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,
                           java.nio.ByteBuffer key,
                           java.nio.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​(java.nio.ByteBuffer key,
                           java.nio.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

      • 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

      • 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​(java.lang.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 java.lang.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.