Transaction (Carbonado 1.2.3 API)

+
+
All Known Implementing Classes:
+
TransactionPair
+
+
+
+
```
public interface Transaction
```
+
Transactions define atomic operations which can be committed or aborted as a + unit. Transactions are entered by calling Repository.enterTransaction(). + Transactions are thread-local, and so no special action needs to be taken to + bind operations to them. Cursors which are opened in the scope of a + transaction are automatically closed when the transaction is committed or + aborted. + +
Transactions do not exit when they are committed. The transaction is + still valid after a commit, but new operations are grouped into a separate + atomic unit. The exit method must be invoked on every + transaction. The following pattern is recommended: + +
```
+ Transaction txn = repository.enterTransaction();
+ try {
+     // Make updates to storage layer
+     ...
+
+     // Commit the changes up to this point
+     txn.commit();
+
+     // Optionally make more updates
+     ...
+
+     // Commit remaining changes
+     txn.commit();
+ } finally {
+     // Ensure transaction exits, aborting uncommitted changes if an exception was thrown
+     txn.exit();
+ }
+ 
```
+ +
Transactions may be nested. Calling commit or abort on an outer + transaction will recursively apply the same operation to all inner + transactions as well. All Cursors contained within are also closed. + +
Transaction instances are mutable, but they are thread-safe.
+
Author:
+
Brian S O'Neill
+

+ +

Method Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
Modifier and Type	Method and Description
`void`	`attach()` + Attaches this transaction to the current thread, if it has been + detached. +
`void`	`commit()` + If currently in a transaction, commits all changes to the storage layer + since the last commit within the transaction. +
`void`	`detach()` + Detaches this transaction from the current thread. +
`void`	`exit()` + Closes the current transaction, aborting all changes since the last + commit. +
`IsolationLevel`	`getIsolationLevel()` + Returns the isolation level of this transaction. +
`boolean`	`isForUpdate()` + Returns true if this transaction is in update mode, which is adjusted by + calling `setForUpdate(boolean)`. +
`boolean`	`preCommit()` + Calling this method commits all nested child transactions, closes all + scoped cursors, and locks out some interactions from other threads. +
`void`	`setDesiredLockTimeout(int timeout, + java.util.concurrent.TimeUnit unit)` + Specify a desired timeout for aquiring locks within this + transaction. +
`void`	`setForUpdate(boolean forUpdate)` + Set to true to force all read operations within this transaction to + acquire upgradable or write locks. +

+ +
- + + +
  Method Detail
  + + + +
  - +
    commit
    +
```
void commit()
+            throws PersistException
```
    +
    If currently in a transaction, commits all changes to the storage layer + since the last commit within the transaction.
    +
    Throws:
    +
    PersistException - if storage layer throws an exception
    +
  + + + +
  - +
    exit
    +
```
void exit()
+          throws PersistException
```
    +
    Closes the current transaction, aborting all changes since the last + commit.
    +
    Throws:
    +
    PersistException - if storage layer throws an exception
    +
  + + + +
  - +
    setForUpdate
    +
```
void setForUpdate(boolean forUpdate)
```
    +
    Set to true to force all read operations within this transaction to + acquire upgradable or write locks. This option eliminates deadlocks that + may occur when updating records, except it may increase contention.
    +
  + + + +
  - +
    isForUpdate
    +
```
boolean isForUpdate()
```
    +
    Returns true if this transaction is in update mode, which is adjusted by + calling setForUpdate(boolean).
    +
  + + + +
  - +
    setDesiredLockTimeout
    +
```
void setDesiredLockTimeout(int timeout,
+                         java.util.concurrent.TimeUnit unit)
```
    +
    Specify a desired timeout for aquiring locks within this + transaction. Calling this method may have have no effect at all, if the + repository does not support this feature. In addition, the lock timeout + might not be alterable if the transaction contains uncommitted data. + +
    Also, the range of lock timeout values supported might be small. For + example, only a timeout value of zero might be supported. In that case, + the transaction is configured to not wait at all when trying to acquire + locks. Expect immediate timeout exceptions when locks cannot be + granted. + +
    Nested transactions inherit the desired lock timeout of their + parent. Top transactions always begin with the default lock timeout.
    +
    Parameters:
    timeout - Desired lock timeout. If negative, revert lock timeout to + default value.
    unit - Time unit for timeout. If null, revert lock timeout to + default value.
    +
  + + + +
  - +
    getIsolationLevel
    +
```
IsolationLevel getIsolationLevel()
```
    +
    Returns the isolation level of this transaction.
    +
  + + + +
  - +
    detach
    +
```
void detach()
```
    +
    Detaches this transaction from the current thread. It can be attached + later, and to any thread which currently has no thread-local + transaction. + +
    Detaching a transaction also detaches any parent and nested child + transactions. Attaching any of them achieves the same result as + attaching this transaction.
    +
    Throws:
    +
    java.lang.IllegalStateException - if transaction is attached to a different + thread
    Since:
    +
    1.2
    +
  + + + +
  - +
    attach
    +
```
void attach()
```
    +
    Attaches this transaction to the current thread, if it has been + detached. Attaching a transaction also attaches any parent and nested + child transactions.
    +
    Throws:
    +
    java.lang.IllegalStateException - if current thread has a different + transaction already attached
    Since:
    +
    1.2
    +
  + + + +
  - +
    preCommit
    +
```
boolean preCommit()
+                  throws PersistException
```
    +
    Calling this method commits all nested child transactions, closes all + scoped cursors, and locks out some interactions from other threads. The + commit method must still be called to finish the commit. Most applications + have no use for pre-commit and should only ever call commit. + +
    The intent of this method is to complete as many operations as + possible leading up to the actual commit. If pre-commit succeeds, then + commit will most likely succeed as well. While in a pre-commit state, the + transaction can still be used by the current thread. Calling pre-commit + again ensures that child transactions and cursors are closed.
    +
    Returns:
    false if transaction has exited
    +
    Throws:
    +
    PersistException
    +
  +
+

Interface Transaction

Method Summary

Method Detail

commit

exit

setForUpdate

isForUpdate

setDesiredLockTimeout

getIsolationLevel

detach

attach

preCommit