Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.je
Class Transaction

    java.lang.Object
      com.sleepycat.je.Transaction

    public class Transaction

extends 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.

A single Transaction may be used to protect operations for any number of Databases in a given environment. However, a single Transaction may not be used for operations in more than one distinct environment.

Transaction handles are free-threaded; transactions handles may be used concurrently by multiple threads. Once the `Transaction.abort` or `Transaction.commit` method is called, the handle may not be accessed again, regardless of the success or failure of the method, with one exception: the `abort` method may be called any number of times to simplify error handling.

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.setReadUncommitted(true);
>          Transaction txn = myEnvironment.beginTransaction(null, config);

Constructor Summary
`protected` | `Transaction(Environment env, com.sleepycat.je.txn.Txn txn)` Creates a transaction.

Method Summary
`void` | `abort()` Cause an abnormal termination of the transaction.
`void` | `commit()` End the transaction.
`void` | `commit(Durability durability)` End the transaction using the specified durability requirements.
`void` | `commitNoSync()` End the transaction, not writing to stable storage and not committing synchronously.
`void` | `commitSync()` End the transaction, writing to stable storage and committing synchronously.
`void` | `commitWriteNoSync()` End the transaction, writing to stable storage but not committing synchronously.
`CommitToken` | `getCommitToken()` This method is intended for use with a replicated environment.
`long` | `getId()` Return the transaction's unique ID.
`long` | `getLockTimeout(TimeUnit unit)` Returns the lock request timeout value for the transaction.
`String` | `getName()` Get the user visible name for the transaction.
`long` | `getTxnTimeout(TimeUnit unit)` Returns the timeout value for the transaction lifetime.
`boolean` | `isValid()` Returns whether this `Transaction` is open, valid and can be used.
`void` | `setLockTimeout(long timeOut)` Deprecated. as of 4.0, replaced by `setLockTimeout(long, TimeUnit)`.
`void` | `setLockTimeout(long timeOut, TimeUnit unit)` Configures the lock request timeout value for the transaction.
`void` | `setName(String name)` Set the user visible name for the transaction.
`void` | `setTxnTimeout(long timeOut)` Deprecated. as of 4.0, replaced by `setTxnTimeout(long, TimeUnit)`.
`void` | `setTxnTimeout(long timeOut, TimeUnit unit)` Configures the timeout value for the transaction lifetime.
`String` | `toString()`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### Transaction

    protected Transaction(Environment env,
                          com.sleepycat.je.txn.Txn txn)

  Creates a transaction.

Method Detail

### 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.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method itself may be called any number of times to simplify error handling.

  Throws:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the environment has been closed, or cursors associated with the transaction are still open.
    `DatabaseException`

### getId

    public long getId()

  Return the transaction's unique ID.

  Returns:
    The transaction's unique ID.

### getCommitToken

    public CommitToken getCommitToken()
                               throws IllegalStateException

  This method is intended for use with a replicated environment.

  It returns the commitToken associated with a successful replicated commit. A null value is returned if the txn was not associated with a replicated environment, or the txn did not result in any changes to the environment. This method should only be called after the transaction has finished.

  This method is typically used in conjunction with the `CommitPointConsistencyPolicy`.

  Returns:
    the token used to identify the replicated commit. Return null if the transaction has aborted, or has committed without making any updates.
  Throws:
    `IllegalStateException` - if the method is called before the transaction has committed or aborted.
  See Also:
    `CommitPointConsistencyPolicy`

### 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.

  All cursors opened within the transaction must be closed before the transaction is committed.

  If the method encounters an error, the transaction will have been aborted when the call returns.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method may be called any number of times to simplify error handling.

  Throws:
    `InsufficientReplicasException` - if the master in a replicated environment could not contact a quorum of replicas as determined by the `Durability.ReplicaAckPolicy`. The application must abort the transaction and can choose to retry it.
    `InsufficientAcksException` - if the master in a replicated environment did not receive enough replica acknowledgments, although the commit succeeded locally.
    `ReplicaWriteException` - if a write operation was performed with this transaction, but this node is now a Replica.
    `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed, or cursors associated with the transaction are still open.
    `DatabaseException`

### commit

    public void commit(Durability durability)
                throws DatabaseException

  End the transaction using the specified durability requirements. This requirement overrides any default durability requirements associated with the environment. If the durability requirements cannot be satisfied, an exception is thrown to describe the problem. Please see `Durability` for specific exceptions that could result when the durability requirements cannot be satisfied.

  All cursors opened within the transaction must be closed before the transaction is committed.

  If the method encounters an error, the transaction will have been aborted when the call returns.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method may be called any number of times to simplify error handling.

  Parameters:
    `durability` - the durability requirements for this transaction
  Throws:
    `InsufficientReplicasException` - if the master in a replicated environment could not contact enough replicas to initiate the commit.
    `InsufficientAcksException` - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.
    `ReplicaWriteException` - if a write operation was performed with this transaction, but this node is now a Replica.
    `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed, or cursors associated with the transaction are still open.
    `IllegalArgumentException` - if an invalid parameter is specified.
    `DatabaseException`

### commitSync

    public void commitSync()
                    throws DatabaseException

  End the transaction, writing to stable storage and 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.

  All cursors opened within the transaction must be closed before the transaction is committed.

  If the method encounters an error, the transaction will have been aborted when the call returns.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method may be called any number of times to simplify error handling.

  Throws:
    `InsufficientReplicasException` - if the master in a replicated environment could not contact enough replicas to initiate the commit.
    `InsufficientAcksException` - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.
    `ReplicaWriteException` - if a write operation was performed with this transaction, but this node is now a Replica.
    `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed, or cursors associated with the transaction are still open.
    `DatabaseException`

### commitNoSync

    public void commitNoSync()
                      throws DatabaseException

  End the transaction, not writing to stable storage and 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.

  All cursors opened within the transaction must be closed before the transaction is committed.

  If the method encounters an error, the transaction will have been aborted when the call returns.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method may be called any number of times to simplify error handling.

  Throws:
    `InsufficientReplicasException` - if the master in a replicated environment could not contact enough replicas to initiate the commit.
    `InsufficientAcksException` - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.
    `ReplicaWriteException` - if a write operation was performed with this transaction, but this node is now a Replica.
    `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed, or cursors associated with the transaction are still open.
    `DatabaseException`

### commitWriteNoSync

    public void commitWriteNoSync()
                           throws DatabaseException

  End the transaction, writing to stable storage but 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 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.

  All cursors opened within the transaction must be closed before the transaction is committed.

  If the method encounters an error, the transaction will have been aborted when the call returns.

  After this method has been called, regardless of its return, the `Transaction` handle may not be accessed again, with one exception: the `abort` method may be called any number of times to simplify error handling.

  Throws:
    `InsufficientReplicasException` - if the master in a replicated environment could not contact enough replicas to initiate the commit.
    `InsufficientAcksException` - if the master in a replicated environment did not receive enough replica acknowledgments, althought the commit succeeded locally.
    `ReplicaWriteException` - if a write operation was performed with this transaction, but this node is now a Replica.
    `OperationFailureException` - if this exception occurred earlier and caused the transaction to be invalidated.
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed, or cursors associated with the transaction are still open.
    `DatabaseException`

### getTxnTimeout

    public long getTxnTimeout(TimeUnit unit)
                       throws EnvironmentFailureException,
                              IllegalStateException,
                              IllegalArgumentException

  Returns the timeout value for the transaction lifetime.

  If `setTxnTimeout(long,TimeUnit)` has not been called to configure the timeout, the environment configuration value (`EnvironmentConfig.TXN_TIMEOUT` )is returned.

  Parameters:
    `unit` - the `TimeUnit` of the returned value. May not be null.
  Throws:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed.
    `IllegalArgumentException` - if the unit is null.
  Since:
    4.0

### setTxnTimeout

    public void setTxnTimeout(long timeOut,
                              TimeUnit unit)
                       throws IllegalArgumentException,
                              DatabaseException

  Configures the timeout value for the transaction lifetime.

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

  Transaction 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 the length of the lock timeout and how often deadlock detection is performed.

  Parameters:
    `timeOut` - The timeout value for the transaction lifetime. A value of 0 disables timeouts for the transaction, meaning that no limit on the duration of the transaction is enforced.
    `unit` - the `TimeUnit` of the timeOut value. May be null only if timeOut is zero.
  Throws:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed.
    `IllegalArgumentException` - if timeOut or unit is invalid.
    `DatabaseException`
  Since:
    4.0

### setTxnTimeout

    public void setTxnTimeout(long timeOut)
                       throws IllegalArgumentException,
                              DatabaseException

  Deprecated. as of 4.0, replaced by `setTxnTimeout(long, TimeUnit)`.

  Configures the timeout value for the transaction lifetime, with the timeout value specified in microseconds. This method is equivalent to:

      setTxnTimeout(long, TimeUnit.MICROSECONDS);

  Throws:
    `IllegalArgumentException`
    `DatabaseException`

### getLockTimeout

    public long getLockTimeout(TimeUnit unit)
                        throws EnvironmentFailureException,
                               IllegalStateException,
                               IllegalArgumentException

  Returns the lock request timeout value for the transaction.

  If `setLockTimeout(long,TimeUnit)` has not been called to configure the timeout, the environment configuration value (`EnvironmentConfig.LOCK_TIMEOUT`) is returned.

  Parameters:
    `unit` - the `TimeUnit` of the returned value. May not be null.
  Throws:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed.
    `IllegalArgumentException` - if the unit is null.
  Since:
    4.0

### setLockTimeout

    public void setLockTimeout(long timeOut,
                               TimeUnit unit)
                        throws IllegalArgumentException,
                               DatabaseException

  Configures the lock request timeout value for the transaction.

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

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

  Parameters:
    `timeOut` - The lock request timeout value for this transaction. A value of zero turns off transaction timeouts, meaning that no lock wait time limit is enforced and a deadlocked operation will block indefinitely. We strongly recommend that a large timeout value, rather than a zero value, is used when deadlocks are not expected. That way, a timeout exception will be thrown when an unexpected deadlock occurs.
    `unit` - the `TimeUnit` of the timeOut value. May be null only if timeOut is zero.
  Throws:
    `EnvironmentFailureException` - if an unexpected, internal or environment-wide failure occurs.
    `IllegalStateException` - if the transaction or environment has been closed.
    `IllegalArgumentException` - if timeOut or unit is invalid.
    `DatabaseException`
  Since:
    4.0

### setLockTimeout

    public void setLockTimeout(long timeOut)
                        throws IllegalArgumentException,
                               DatabaseException

  Deprecated. as of 4.0, replaced by `setLockTimeout(long, TimeUnit)`.

  Configures the lock request timeout value for the transaction, with the timeout value specified in microseconds. This method is equivalent to:

      setLockTimeout(long, TimeUnit.MICROSECONDS);

  Throws:
    `IllegalArgumentException`
    `DatabaseException`

### setName

    public void setName(String name)

  Set the user visible name for the transaction.

  Parameters:
    `name` - The user visible name for the transaction.

### getName

    public String getName()

  Get the user visible name for the transaction.

  Returns:
    The user visible name for the transaction.

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`

### isValid

    public boolean isValid()

  Returns whether this `Transaction` is open, valid and can be used. If this method returns false, `abort()` should be called as soon as possible.

  When an `OperationFailureException`, or one of its subclasses, is caught, the `isValid` method should be called to determine whether the `Transaction` can continue to be used, or should be aborted.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2004-2010 Oracle. All rights reserved.