Package com.sleepycat.db

## Class Transaction

- java.lang.Object
- - com.sleepycat.db.Transaction

-     public class Transaction
      extends java.lang.Object

  The Transaction object is the handle for a transaction. Methods off the transaction handle are used to configure, abort and commit the transaction. Transaction handles are provided to other Berkeley DB methods in order to transactionally protect those operations.

  Transaction handles are not free-threaded; transactions handles may be used by multiple threads, but only serially, that is, the application must serialize access to the handle. Once the `Transaction.abort`, `Transaction.commit` or `Transaction.discard` methods are called, the handle may not be accessed again (except to retrieve the commit token), regardless of the success or failure of the method. In addition, parent transactions may not issue any Berkeley DB operations while they have active child transactions (child transactions that have not yet been committed or aborted) except for `Environment.beginTransaction`, `Transaction.abort` and `Transaction.commit`.

  To obtain a transaction with default attributes:

  >         Transaction txn = myEnvironment.beginTransaction(null, null);

  To customize the attributes of a transaction:

  >         TransactionConfig config = new TransactionConfig();
  >         config.setDirtyRead(true);
  >         Transaction txn = myEnvironment.beginTransaction(null, config);

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `abort()` | Cause an abnormal termination of the transaction.
    `void` | `commit()` | End the transaction.
    `void` | `commitNoSync()` | End the transaction, not committing synchronously.
    `void` | `commitSync()` | End the transaction, committing synchronously.
    `void` | `commitWriteNoSync()` | End the transaction, writing but not flushing the log.
    `void` | `discard()` | Free up all the per-process resources associated with the specified `Transaction` handle, neither committing nor aborting the transaction.
    `byte[]` | `getCommitToken()` | Fetch the transaction's commit token.
    `int` | `getId()` | Return the transaction's unique ID.
    `java.lang.String` | `getName()` | Get the user visible name for the transaction.
    `int` | `getPriority()` | Get the transaction's deadlock priority.
    `void` | `prepare​(byte[] gid)` | Initiate the beginning of a two-phase commit.
    `void` | `setLockTimeout​(long timeOut)` | Configure the lock request timeout value for the transaction.
    `void` | `setName​(java.lang.String name)` | Set the user visible name for the transaction.
    `void` | `setPriority​(int priority)` | Set the deadlock priority for this transaction.
    `void` | `setTxnTimeout​(long timeOut)` | Configure the timeout value for the transaction lifetime.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getCommitToken

          public byte[] getCommitToken()
                                throws java.lang.IllegalStateException

      Fetch the transaction's commit token.

      This operation can only be performed after this transaction has committed.

      Returns:
        The commit token generated at the commit time of this transaction.
      Throws:
        `java.lang.IllegalStateException`

    - #### abort

          public void abort()
                     throws DatabaseException

      Cause an abnormal termination of the transaction.

      The log is played backward, and any necessary undo operations are done. Before Transaction.abort returns, any locks held by the transaction will have been released.

      In the case of nested transactions, aborting a parent transaction causes all children (unresolved or not) of the parent transaction to be aborted.

      All cursors opened within the transaction must be closed before the transaction is aborted. This method closes all open `Cursor` handles. And if a close operation fails, the rest of the cursors are closed, and the database environment is set to the panic state.

      After Transaction.abort has been called, regardless of its return, the `Transaction` handle may not be accessed again.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### commit

          public void commit()
                      throws DatabaseException

      End the transaction. If the environment is configured for synchronous commit, the transaction will be committed synchronously to stable storage before the call returns. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

      If the environment is not configured for synchronous commit, the commit will not necessarily have been committed to stable storage before the call returns. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but it is possible this transaction may be undone during recovery.

      In the case of nested transactions, if the transaction is a parent transaction, committing the parent transaction causes all unresolved children of the parent to be committed. In the case of nested transactions, if the transaction is a child transaction, its locks are not released, but are acquired by its parent. Although the commit of the child transaction will succeed, the actual resolution of the child transaction is postponed until the parent transaction is committed or aborted; that is, if its parent transaction commits, it will be committed; and if its parent transaction aborts, it will be aborted.

      All cursors opened within the transaction must be closed before the transaction is committed. If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the transaction is aborted and the first such error is returned.

      After this method returns, the `Transaction` handle may not be accessed again (except to retrieve the commit token), regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### commitSync

          public void commitSync()
                          throws DatabaseException

      End the transaction, committing synchronously. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

      This behavior is the default for database environments unless otherwise configured using the `EnvironmentConfig.setTxnNoSync` method. This behavior may also be set for a single transaction using the `Environment.beginTransaction` method. Any value specified to this method overrides both of those settings.

      In the case of nested transactions, if the transaction is a parent transaction, committing the parent transaction causes all unresolved children of the parent to be committed. In the case of nested transactions, if the transaction is a child transaction, its locks are not released, but are acquired by its parent. Although the commit of the child transaction will succeed, the actual resolution of the child transaction is postponed until the parent transaction is committed or aborted; that is, if its parent transaction commits, it will be committed; and if its parent transaction aborts, it will be aborted.

      All cursors opened within the transaction must be closed before the transaction is committed. If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the transaction is aborted and the first such error is returned.

      After this method returns, the `Transaction` handle may not be accessed again (except to retrieve the commit token), regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### commitNoSync

          public void commitNoSync()
                            throws DatabaseException

      End the transaction, not committing synchronously. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but it is possible this transaction may be undone during recovery.

      This behavior may be set for a database environment using the `EnvironmentConfig.setTxnNoSync` method or for a single transaction using the `Environment.beginTransaction` method. Any value specified to this method overrides both of those settings.

      In the case of nested transactions, if the transaction is a parent transaction, committing the parent transaction causes all unresolved children of the parent to be committed. In the case of nested transactions, if the transaction is a child transaction, its locks are not released, but are acquired by its parent. Although the commit of the child transaction will succeed, the actual resolution of the child transaction is postponed until the parent transaction is committed or aborted; that is, if its parent transaction commits, it will be committed; and if its parent transaction aborts, it will be aborted.

      All cursors opened within the transaction must be closed before the transaction is committed. If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the transaction is aborted and the first such error is returned.

      After this method returns, the `Transaction` handle may not be accessed again (except to retrieve the commit token), regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### commitWriteNoSync

          public void commitWriteNoSync()
                                 throws DatabaseException

      End the transaction, writing but not flushing the log. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but it is possible this transaction may be undone during recovery in the event that the operating system crashes. This option provides more durability than an asynchronous commit and has less performance cost than a synchronous commit.

      This behavior may be set for a database environment using the `EnvironmentConfig.setTxnWriteNoSync` method or for a single transaction using the `Environment.beginTransaction` method. Any value specified to this method overrides both of those settings.

      In the case of nested transactions, if the transaction is a parent transaction, committing the parent transaction causes all unresolved children of the parent to be committed. In the case of nested transactions, if the transaction is a child transaction, its locks are not released, but are acquired by its parent. Although the commit of the child transaction will succeed, the actual resolution of the child transaction is postponed until the parent transaction is committed or aborted; that is, if its parent transaction commits, it will be committed; and if its parent transaction aborts, it will be aborted.

      All cursors opened within the transaction must be closed before the transaction is committed. If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the transaction is aborted and the first such error is returned.

      After this method returns, the `Transaction` handle may not be accessed again (except to retrieve the commit token), regardless of the method's success or failure. If the method encounters an error, the transaction and all child transactions of the transaction will have been aborted when the call returns.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### discard

          public void discard()
                       throws DatabaseException

      Free up all the per-process resources associated with the specified `Transaction` handle, neither committing nor aborting the transaction. This call may be used only after calls to `Environment.recover` when there are multiple global transaction managers recovering transactions in a single database environment. Any transactions returned by `Environment.recover` that are not handled by the current global transaction manager should be discarded using this method. If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the first such error is returned.

      The `Transaction` handle may not be accessed again after this method has been called, regardless of the method's success or failure.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### getId

          public int getId()
                    throws DatabaseException

      Return the transaction's unique ID.

      Locking calls made on behalf of this transaction should use the value returned from this method as the locker parameter to the `Environment.getLock` or `Environment.lockVector` calls.

      Returns:
        The transaction's unique ID.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### getName

          public java.lang.String getName()
                                   throws DatabaseException

      Get the user visible name for the transaction.

      Returns:
        The user visible name for the transaction.
      Throws:
        `DatabaseException` - if a failure occurs.

    - #### getPriority

          public int getPriority()
                          throws DatabaseException

      Get the transaction's deadlock priority.

      Returns:
        The deadlock priority for the transaction.

      Throws:
        `DatabaseException` - if a failure occurs

    - #### prepare

          public void prepare​(byte[] gid)
                       throws DatabaseException

      Initiate the beginning of a two-phase commit.

      In a distributed transaction environment, Berkeley DB can be used as a local transaction manager. In this case, the distributed transaction manager must send prepare messages to each local manager. The local manager must then issue a `Transaction.prepare` call and await its successful return before responding to the distributed transaction manager. Only after the distributed transaction manager receives successful responses from all of its prepare messages should it issue any commit messages.

      In the case of nested transactions, preparing the parent causes all unresolved children of the parent transaction to be committed. Child transactions should never be explicitly prepared. Their fate will be resolved along with their parent's during global recovery.

      If there are `Cursor` handles open when this method is called, they are all closed inside this method. And if there are errors when closing the cursor handles, the first such error is returned.

      Parameters:
        `gid` - The global transaction ID by which this transaction will be known. This global transaction ID will be returned in calls to `Environment.recover` method, telling the application which global transactions must be resolved. The gid parameter must be sized at least DB_XIDDATASIZE (currently 128) bytes; only the first DB_XIDDATASIZE bytes are used.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### setName

          public void setName​(java.lang.String name)
                       throws DatabaseException

      Set the user visible name for the transaction.

      Parameters:
        `name` - The user visible name for the transaction.
      Throws:
        `DatabaseException` - if a failure occurs.

    - #### setPriority

          public void setPriority​(int priority)
                           throws DatabaseException

      Set the deadlock priority for this transaction. The deadlock detector will reject lock requests from lower priority transactions before those from higher priority transactions.

      Parameters:
        `priority` - The deadlock priority for the transaction.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### setTxnTimeout

          public void setTxnTimeout​(long timeOut)
                             throws DatabaseException

      Configure the timeout value for the transaction lifetime.

      If the transaction runs longer than this time, the transaction may may throw `DatabaseException`.

      Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. For this reason, the accuracy of the timeout depends on how often deadlock detection is performed.

      Parameters:
        `timeOut` - The timeout value for the transaction lifetime, in microseconds. As the value is an unsigned 32-bit number of microseconds, the maximum timeout is roughly 71 minutes. A value of 0 disables timeouts for the transaction.

        This method may be called at any time during the life of the application.

      Throws:
        `DatabaseException` - if a failure occurs.

    - #### setLockTimeout

          public void setLockTimeout​(long timeOut)
                              throws DatabaseException

      Configure the lock request timeout value for the transaction.

      If a lock request cannot be granted in this time, the transaction may throw `DatabaseException`.

      Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. For this reason, the accuracy of the timeout depends on how often deadlock detection is performed.

      Parameters:
        `timeOut` - The lock request timeout value for the transaction, in microseconds. As the value is an unsigned 32-bit number of microseconds, the maximum timeout is roughly 71 minutes. A value of 0 disables timeouts for the transaction.

        This method may be called at any time during the life of the application.

      Throws:
        `DatabaseException` - if a failure occurs.

Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.