Holger's Java API

## com.antelmann.db
Interface DBTransaction

All Known Implementing Classes:
  AbstractDBTransaction, SQLTransaction

    public interface DBTransaction

a transaction controlls access to all resources of a Database through DBClassStore instances. A Thread accessing resources must own the monitor on the active transaction. To ensure thread-save consistency on a transaction, a thread must maintain ownership over the transaction throughout the duration of a transaction.

Author:
  Holger Antelmann
See Also:
  `Database`, `TransactionListener`

Method Summary
`void` `abort()` aborts this transaction; requires ownership of this instance.
`boolean` `addTransactionListener(TransactionListener listener)`
`void` `begin()` sets the transaction to active and allows access to the Resources provided that the calling thread holds the lock on this instance.
`void` `commit()` commits all data within the transaction scope to the underlying database; requires ownership of this instance.
`Database<?>` `getDatabase()` gives access to the associated Database
`TransactionListener[]` `getTransactionListeners()`
`boolean` `isActive()` if true, a transaction is currently in progress and has not been committed or aborted, yet.
`boolean` `isReadOnly()` informs whether the currently running transaction is configured to be read-only.
`boolean` `removeTransactionListener(TransactionListener listener)`
`void` `setNextToReadOnly(boolean flag)` allows to configure the next transaction to be read-only.

Method Detail

### addTransactionListener

    boolean addTransactionListener(TransactionListener listener)

### removeTransactionListener

    boolean removeTransactionListener(TransactionListener listener)

### getTransactionListeners

    TransactionListener[] getTransactionListeners()

### getDatabase

    Database<?> getDatabase()

  gives access to the associated Database

### begin

    void begin()
               throws TransactionException

  sets the transaction to active and allows access to the Resources provided that the calling thread holds the lock on this instance.

  Throws:
    `TransactionException` - if the transaction is already active or if the transaction is in transition
  See Also:
    `TransactionListener.transactionAborted(DBTransaction)`, `TransactionListener.transactionCommitted(DBTransaction)`

### commit

    void commit()
                throws TransactionException,
                       DatabaseException

  commits all data within the transaction scope to the underlying database; requires ownership of this instance.

  Throws:
    `TransactionException` - if the transaction is already active
    `DatabaseException` - if the transaction could not be committed to the underlying service

### abort

    void abort()
               throws TransactionException,
                      DatabaseException

  aborts this transaction; requires ownership of this instance.

  Throws:
    `TransactionException` - if the transaction is already active
    `DatabaseException` - if the transaction could not be aborted from the underlying service

### isActive

    boolean isActive()

  if true, a transaction is currently in progress and has not been committed or aborted, yet. Access to resources is only save if this method returns true and the calling thread holds the lock on this instance. In order to rely on the return value after the method returns, an ownership of the calling thread on this DBTransaction is required.

### isReadOnly

    boolean isReadOnly()

  informs whether the currently running transaction is configured to be read-only. If there is no active transaction, the return value will determine whether the next transaction to be started is going to be read-only. This setting only applies for the current/next transaction, not for subsequent ones. Some given database implementation may, however, configure every transaction to be read-only (or read-write) while altering this setting may not be supported. `setNextToReadOnly(boolean)`

### setNextToReadOnly

    void setNextToReadOnly(boolean flag)
                           throws TransactionException,
                                  UnsupportedOperationException

  allows to configure the next transaction to be read-only. This call must be repeated before every transaction that is to be read-only, as after each commit/abort this setting is reset to false.

  Parameters:
    `flag` - if true, the next transaction will run read-only; if false, the next transaction will be read-write
  Throws:
    `TransactionException` - if a transaction is currently active
    `UnsupportedOperationException`
  See Also:
    `isReadOnly()`

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads