STransaction (Oracle - Berkeley DB Client-Server API)
Date: 2018-05-29

com.sleepycat.client

## Class STransaction

- java.lang.Object
- - com.sleepycat.client.STransaction

-     public class STransaction
      extends java.lang.Object

  The STransaction 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 driver methods in order to transactionally protect those operations.

  Once the `abort()`, or `commit()` methods are called, the handle may not be accessed again, regardless of the success or failure of the method. In addition, parent transactions may not issue any Berkeley DB driver operations while they have active child transactions (child transactions that have not yet been committed or aborted) except for `SEnvironment.beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig)`, `abort()` and `commit()`.

  To obtain a transaction with default attributes:

        STransaction txn = myEnvironment.beginTransaction(null, null);

  To customize the attributes of a transaction:

        STransactionConfig config = new STransactionConfig();
        config.setReadUncommitted(true);
        STransaction txn = myEnvironment.beginTransaction(null, config);

- - ### Method Summary

    All Methods Instance Methods Concrete Methods Default Methods
    Modifier and Type | Method and 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.
    `int` | `getPriority()` Get the transaction's deadlock priority.
    `default <V> V` | `handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)`
    `default <V> V` | `remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)`
    `default <V> V` | `remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)`
    `void` | `setPriority(int priority)` Set the deadlock priority for this transaction.

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

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

- - ### Method Detail

    - #### abort

          public void abort()
                     throws SDatabaseException

      Cause an abnormal termination of the transaction.

      The log is played backward, and any necessary undo operations are done. Before this method 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 `SCursor` 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 this method has been called, regardless of its return, this handle may not be accessed again.

      Throws:
        `SDatabaseException` - if any error occurs

    - #### commit

          public void commit()
                      throws SDatabaseException

      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 `SCursor` 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, this handle may not be accessed again, 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:
        `SDatabaseException` - if any error occurs

    - #### commitNoSync

          public void commitNoSync()
                            throws SDatabaseException

      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 `SEnvironmentConfig.setTxnNoSync(boolean)` method or for a single transaction using the `SEnvironment.beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig)` 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 `SCursor` 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, this handle may not be accessed again, 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:
        `SDatabaseException` - if any error occurs

    - #### commitSync

          public void commitSync()
                          throws SDatabaseException

      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 `SEnvironmentConfig.setTxnNoSync(boolean)` method. This behavior may also be set for a single transaction using the `SEnvironment.beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig)` 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 `SCursor` 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, this handle may not be accessed again, 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:
        `SDatabaseException` - if any error occurs

    - #### commitWriteNoSync

          public void commitWriteNoSync()
                                 throws SDatabaseException

      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 `SEnvironmentConfig.setTxnWriteNoSync(boolean)` method or for a single transaction using the `SEnvironment.beginTransaction(com.sleepycat.client.STransaction, com.sleepycat.client.STransactionConfig)` 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 `SCursor` 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, this handle may not be accessed again, 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:
        `SDatabaseException` - if any error occurs

    - #### getPriority

          public int getPriority()
                          throws SDatabaseException

      Get the transaction's deadlock priority.
      Returns:
        the transaction's deadlock priority
      Throws:
        `SDatabaseException` - if any error occurs

    - #### setPriority

          public void setPriority(int priority)
                           throws SDatabaseException

      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:
        `SDatabaseException` - if any error occurs

    - #### remoteCallWithIOException

          public <V> V remoteCallWithIOException(com.sleepycat.client.RemoteServiceCallable<V> remote)
                                          throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### remoteCall

          public <V> V remoteCall(com.sleepycat.client.RemoteServiceCallable<V> remote)

    - #### handleRuntimeExceptions

          public <V> V handleRuntimeExceptions(com.sleepycat.client.RemoteServiceCallable<V> remote)
                                        throws org.apache.thrift.TException

      Throws:
        `org.apache.thrift.TException`

Copyright (c) 2016, 2018 Oracle and/or its affiliates. All rights reserved.