Holger's Java API

## com.antelmann.db
Interface TransactionListener

All Known Implementing Classes:
  DBClassStoreCache, DBTransactionStoreAdapter, LoggerTransactionListener, TransactionCounter, TransactionListener.Adapter, UserTransactionListener

    public interface TransactionListener

listens for DBTransaction changes and can potentially intervene upon preparing for a commit. This interface may also be used to provide rudimentary XA support.

Author:
  Holger Antelmann
See Also:
  `DBTransaction`, `DatabaseChangeMonitor`, `DBStoreListener`, `Database`

Nested Class Summary
`static class` `TransactionListener.Adapter` provides convenient empty implementations for all methods

Method Summary
`void` `finishTransaction(DBTransaction transaction)` called before the transaction commits (and before `prepareToCommit(DBTransaction)`), so that the commit at the database level can be prevented by throwing a DatabaseException here.
`void` `prepareToCommit(DBTransaction transaction)` called right before the transaction actually commits and after `finishTransaction(DBTransaction)`.
`void` `transactionAborted(DBTransaction transaction)` called after a database transaction was aborted; the transaction is already inactive.
`void` `transactionBegin(DBTransaction transaction)` called upon beginning a transaction (the transaction is already active)
`void` `transactionCommitted(DBTransaction transaction)` called after a successful database commit; the transaction is already inactive.

Method Detail

### transactionBegin

    void transactionBegin(DBTransaction transaction)

  called upon beginning a transaction (the transaction is already active)

### finishTransaction

    void finishTransaction(DBTransaction transaction)
                           throws DatabaseException

  called before the transaction commits (and before `prepareToCommit(DBTransaction)`), so that the commit at the database level can be prevented by throwing a DatabaseException here. This method can also be used to make some updates on another database or checking on certain data before the transaction is allowed to commit. In other words, this method may effectively veto the commit of a transaction After this call, the transaction is soon either going to be committed or aborted (right after all listeners have been called). As this method runs within the transaction, it is possible to access/update any resources from the database.

  Throws:
    `DatabaseException`

### prepareToCommit

    void prepareToCommit(DBTransaction transaction)

  called right before the transaction actually commits and after `finishTransaction(DBTransaction)`. Any exception thrown is ignored; listeners must not do any lengthy operations here. This may be used for supporting the implementation of a 2-phase-commit.

  Parameters:
    `transaction` - the transaction (being still active) that is about to be committed

### transactionCommitted

    @Warning(value="do not directly start a new transaction when implementing this method")
    void transactionCommitted(DBTransaction transaction)

  called after a successful database commit; the transaction is already inactive. Note that you cannot start a new transaction within the call of this method, since subsequent listeners would not have a chance to react on this transaction end. If the implementation of this method tries to begin a new transaction, a `TransactionException` will be thrown. If you need to access/update resources of this database from this method, start a new thread that opens a new transaction.

### transactionAborted

    @Warning(value="do not directly start a new transaction when implementing this method")
    void transactionAborted(DBTransaction transaction)

  called after a database transaction was aborted; the transaction is already inactive. Note that you cannot to start a new transaction within the call of this method, since subsequent listeners would not have a chance to react on this transaction end. If the implementation of this method tries to begin a new transaction, a `TransactionException` will be thrown. If you need to access/update resources of this database from this method, start a new thread that opens a new transaction.

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