IBPP::Transaction

The IBPP::Transaction Interface represents a transaction (!). Along with IBPP::Database and IBPP::Statement, it is the core of IBPP. You need at least one instance of each to do anything against the data stored in a database.

Definition

See the file ibpp.h for an up-to-date definition of the interface. Lookup the ITransaction class.

Like the other building blocks of IBPP, the actual interface class is a pure virtual class (here named IBPP::ITransaction). This is the closest thing in C++ to a pure interface concept. The real working object 'behind' (IBPP internals) is derived from this 'contract' class. As long as the signature of this ITransaction class does not change, your code is binary compatible with IBPP, even if internal details of the real work-class behind have changed.

As with other IBPP building blocks, you cannot instantiate this class by yourself (due to its pure virtual methods). You also can't derive your own class from this one, due to the protected constructor and destructor. You have to get an instance from IBPP through the corresponding Factory function call.

TransactionFactory

Transaction TransactionFactory(Database db, TAM am = amWrite,
                   TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0))

The TransactionFactory is used to build and get access to a Transaction object.

Thanks to its default arguments, you can really easily setup the most common transaction models of Firebird : a write transaction, in complete isolation mode (concurrency), waiting on lock resolutions, and without any other special attributes.

TAM : Transaction Access Modes

The TAM enumeration offers amWrite and amRead constants to define the type of transaction (for writing/reading or for reading).

TIL : Transaction Isolation Level

The TIL enumeration offers ilConcurrency, ilReadDirty, ilReadCommitted, ilConsistency constants to define the type of transaction isolation level.

TLR : Transaction Lock Resolution

The TLR enumeration offers lrWait and lrNoWait constants to define the type of transaction lock resolution to apply.

TFF : Transaction Factory Flags

The TFF enumeration offers tfIgnoreLimbo, tfAutoCommit, tfNoAutoUndo constants to apply advanced transaction configuration options to the transaction object. This is an advanced topic and should make sure to read related documentation material of Firebird before using these techniques (which are most often absolutely not required, nor generally recommended).

Multi-databases transactions

This is often named 'distributed two-phases commit' transactions. Though often tied to a single database attachment, a transaction can really span two or more database attachments. Queries and updates can be issued against all those databases, separately, and then the work committed once for all the databases, in an all-or-nothing way accross all the databases. To support this behaviour, IBPP offers the AttachDatabase method, to add one or multiple databases to an existing transaction object.

Methods

void Start()

Starts the transaction, as defined by the parameters used in the TransactionFactory call.

bool Started()

Returns true if the Transaction object is currently started (and not yet rollbacked or committed).

void Commit

Commit the started transaction. Its state becomes Started() == false.

void CommitRetain

Commit the started transaction, retaining it. This means the work up here is committed but the transaction context is still live (Started() == true).

void Rollback()

Rollbacks the transaction, undoing its work. Its state becomes Started() == false.

void AddReservation(Database db, const std::string& table, TTR tr)

Permits to add a table reservation request to a transaction object, before calling Start(). When reserving a table, you need to specify its name and a table reservation mode. See the TTR enumeration below.

TTR : Transaction Table Reservation

The TTR enumeration offers trSharedWrite, trSharedRead, trProtectedWrite, trProtectedRead constants to define the type of table reservation to add to the transaction object. This is an advanced topic and should make sure to read related documentation material of Firebird before using these techniques (which are most often absolutely not required, nor generally recommended).

void AttachDatabase(Database db, TAM am = amWrite, TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) = 0)

Used to 'attach' an additional existing and connected database object to this transaction object. Setting up multi-databases transactions is that simple.

void DetachDatabase(Database db)

Used to detach a database from a multi-databases transaction. You can only do so when the transaction is not started.

reference/transaction.txt · Last modified: 2011/03/08 19:46 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki