Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

pqxxobject::transaction Class Reference

Database transaction convenience wrapper. More...

#include <transaction.h>

List of all members.

Public Types

enum  state {
  STATE_NONE, STATE_ABORTED, STATE_COMMITTED, STATE_EXECUTING,
  STATE_ABORTING, STATE_COMMITTING
}
 The transaction state. More...


Public Member Functions

 transaction (pqxx::connection &conn, pqxx::transaction<> *&tran)
 The constructor.

virtual ~transaction ()
 The destructor.

void begin (const std::string &name)
 Begin a new transaction.

pqxx::result exec (const std::string &query)
 Execute a query.

pqxx::result::size_type exec_noresult (const std::string &query)
 Execute a query without seeing the result set.

pqxx::result::size_type perform (const std::string &query, pqxx::result::size_type min_rows, pqxx::result::size_type max_rows)
 Execute a query and automatically commit or abort the changes.

void commit ()
 Commit a transaction to the database.

void abort ()
 Abort a transaction.

SigC::Signal1< void, pqxxobject::transaction & > & signal_commit ()
 Signal emitted on transaction commit.

SigC::Signal1< void, pqxxobject::transaction & > & signal_abort ()
 Signal emitted on transaction abort.


Protected Member Functions

void end ()
 End a transaction.

void _begin (const std::string &name)
 Begin a transaction.

void _end ()
 End a transaction.

void commit (bool refresh)
 Commit a transaction.

void _commit (bool refresh)
 Commit a transaction.

void abort (bool refresh)
 Abort a transaction.

void _abort (bool refresh)
 Abort a transaction.


Protected Attributes

pqxx::connection & m_connection
 A reference to a PostgreSQL database connection object.

pqxx::transaction *& m_transaction
 A reference to a pointer to a PostgreSQL transaction object.

SigC::Signal1< void, pqxxobject::transaction & > m_signal_commit
 The commit signal.

SigC::Signal1< void, pqxxobject::transaction & > m_signal_abort
 The abort signal.

state m_state
 The transaction state.

unsigned int m_recursion_level
 The recursion level (depth).


Detailed Description

Database transaction convenience wrapper.

This class provides methods to simplify database access for classes which perform any sort of database interaction. Methods are provided to begin and end transactions, and commit and abort transactions.

The transaction class supports recursion. This means that the transaction object may be passed to functions and class methods other than the owner. Each user of the transaction object must ensure that they use the object correctly:

 void function(transaction& tran)
 {
   bool error;
   tran.begin("function");
 
   [...]
 
   if (error)
     tran.commit();
   else
     tran.abort();
 }
Each function must start by calling the begin() method and end by calling the commit() or abort() method. The number of begin() calls must match the number of commit() or abort() calls exactly. These are used to keep track of the recursion depth; the commit operation will only take effect at the top level, but an abort will cause the whole transaction to be aborted at all levels.

Definition at line 83 of file transaction.h.


Member Enumeration Documentation

enum pqxxobject::transaction::state
 

The transaction state.

Enumeration values:
STATE_NONE  No transaction is in progress.
STATE_ABORTED  The current transaction is aborted.
STATE_COMMITTED  The current transaction is committed.
STATE_EXECUTING  The current transaction is executing.
STATE_ABORTING  The transaction is in the process of aborting.
STATE_COMMITTING  The transaction is in the process of committing.

Definition at line 87 of file transaction.h.


Constructor & Destructor Documentation

transaction::transaction pqxx::connection &  conn,
pqxx::transaction<> *&  tran
 

The constructor.

Parameters:
conn a reference to a PostgreSQL database connection object.
tran a pointer to a PostgreSQL transaction object. It should initially be set to NULL.

Definition at line 80 of file transaction.cc.

transaction::~transaction  )  [virtual]
 

The destructor.

Definition at line 89 of file transaction.cc.


Member Function Documentation

void transaction::_abort bool  refresh  )  [protected]
 

Abort a transaction.

This method does the actual work.

Parameters:
refresh true to refresh affected rows on abort, otherwise false.

Definition at line 322 of file transaction.cc.

References begin(), commit(), end(), m_signal_abort, m_signal_commit, m_state, m_transaction, STATE_ABORTED, and STATE_ABORTING.

Referenced by abort().

void transaction::_begin const std::string &  name  )  [protected]
 

Begin a transaction.

This method does the actual work.

Parameters:
name the name to give the transaction. This may be zero length, but will be shown on error messages relating to the transaction.

Definition at line 241 of file transaction.cc.

References m_connection, m_state, m_transaction, and STATE_EXECUTING.

Referenced by begin().

void transaction::_commit bool  refresh  )  [protected]
 

Commit a transaction.

This method does the actual work.

Parameters:
refresh true to refresh affected rows on commit, otherwise false.

Definition at line 283 of file transaction.cc.

References begin(), commit(), end(), m_signal_abort, m_signal_commit, m_state, m_transaction, STATE_COMMITTED, and STATE_COMMITTING.

Referenced by commit().

void transaction::_end  )  [protected]
 

End a transaction.

This method does the actual work.

Definition at line 251 of file transaction.cc.

References m_recursion_level, m_state, m_transaction, and STATE_NONE.

Referenced by abort(), begin(), commit(), end(), and perform().

void transaction::abort bool  refresh  )  [protected]
 

Abort a transaction.

This method is just a stub for _abort().

Parameters:
refresh true to refresh affected rows on abort, otherwise false.

Definition at line 302 of file transaction.cc.

References _abort(), _end(), end(), m_recursion_level, m_state, and STATE_ABORTING.

void transaction::abort  ) 
 

Abort a transaction.

This method should be called after an error, to revert any changes. The changes will be rolled back to their state at the start of the transaction as a single operation. After calling this method, the transaction may no longer be used.

On abort, the signal_abort signal is emitted.

Definition at line 235 of file transaction.cc.

Referenced by pqxxobject::table< Row >::find_many(), pqxxobject::table< Row >::find_one(), and perform().

void transaction::begin const std::string &  name  ) 
 

Begin a new transaction.

This method should be called at the start of any database operation. If a transaction does not yet exist it will be created (when called at the top level), otherwise this method has no effect other than counting the recursion depth.

Parameters:
name the name to give the transaction. This may be zero length, but will be shown on error messages relating to the transaction.

Definition at line 106 of file transaction.cc.

References _begin(), _end(), and m_recursion_level.

Referenced by _abort(), _commit(), pqxxobject::table< Row >::find_many(), pqxxobject::table< Row >::find_one(), and perform().

void transaction::commit bool  refresh  )  [protected]
 

Commit a transaction.

This method is just a stub for _commit().

Parameters:
refresh true to refresh affected rows on commit, otherwise false.

Definition at line 263 of file transaction.cc.

References _commit(), _end(), end(), and m_recursion_level.

void transaction::commit  ) 
 

Commit a transaction to the database.

This method should be called after the successful completion of one, or a series of, successful database operations. The changes will be committed to the database as one single operation. After calling this method, the transaction may no longer be used.

This method only commits the transaction when called at the top level, otherwise it has no effect.

On commit, the signal_commit signal is emitted.

Definition at line 229 of file transaction.cc.

Referenced by _abort(), _commit(), pqxxobject::table< Row >::find_many(), pqxxobject::table< Row >::find_one(), and perform().

void transaction::end  )  [protected]
 

End a transaction.

This method should be called at the end of any database operation. The transaction will be deleted (when called at the top level), otherwise this method has no effect other than counting the recursion depth. This method has no effect when not running in auto-commit mode.

Definition at line 124 of file transaction.cc.

References _end(), and m_recursion_level.

Referenced by _abort(), _commit(), abort(), and commit().

pqxx::result transaction::exec const std::string &  query  ) 
 

Execute a query.

This method should be called to run an SQL statement on the database server.

Parameters:
query the SQL statement to run.
Returns:
the result set.

Definition at line 148 of file transaction.cc.

References describe_status(), m_state, m_transaction, and STATE_EXECUTING.

Referenced by exec_noresult(), pqxxobject::table< Row >::find_many(), and pqxxobject::table< Row >::find_one().

pqxx::result::size_type transaction::exec_noresult const std::string &  query  ) 
 

Execute a query without seeing the result set.

This method should be called to run an SQL statement on the database server. Use exec_query if access to the result set is required.

Parameters:
query the SQL statement to run.
Returns:
the number of rows the query affected.

Definition at line 167 of file transaction.cc.

References describe_status(), exec(), m_state, and STATE_EXECUTING.

Referenced by perform().

pqxx::result::size_type transaction::perform const std::string &  query,
pqxx::result::size_type  min_rows,
pqxx::result::size_type  max_rows
 

Execute a query and automatically commit or abort the changes.

This method should be called to run an SQL statement on the database server. Unlike exec_query(), this method frees the result set automatically. Use exec_query if access to the result set is required. The transaction will be committed or aborted depending on if the number of affected rows fell in the specified range. Note that this is the same as if commit() or abort() were called manually, so the transaction will not actually be committed. commit() or abort() must still be called to end the transaction block.

Parameters:
query the SQL statement to run.
min_rows the minimum number of rows to be altered. If the number of rows is greater than or equal to this number, the transaction is committed or else it is aborted. If set to 0, the operation will always be committed.
max_rows the maximum number of rows to be altered. If the number of rows is less that or equal to this number, the transaction is committed or else it is aborted. If set to 0, the operation will always be committed.
Returns:
the number of rows the query affected.

Definition at line 189 of file transaction.cc.

References _end(), abort(), begin(), commit(), describe_status(), exec_noresult(), m_state, and STATE_EXECUTING.

SigC::Signal1< void, pqxxobject::transaction & > & transaction::signal_abort  ) 
 

Signal emitted on transaction abort.

All rows that are affected by a transaction are registered with this signal automatically, and will be refreshed using row_base::refresh() on transaction abort.

Returns:
the signal.

Definition at line 100 of file transaction.cc.

References m_signal_abort.

Referenced by pqxxobject::row_base::insert(), and pqxxobject::row_base::update().

SigC::Signal1< void, pqxxobject::transaction & > & transaction::signal_commit  ) 
 

Signal emitted on transaction commit.

All rows that are affected by a transaction are registered with this signal automatically, and will be refreshed using row_base::refresh() on transaction completion.

Returns:
the signal.

Definition at line 94 of file transaction.cc.

References m_signal_commit.

Referenced by pqxxobject::row_base::insert(), and pqxxobject::row_base::update().


Member Data Documentation

pqxx::connection& pqxxobject::transaction::m_connection [protected]
 

A reference to a PostgreSQL database connection object.

Definition at line 277 of file transaction.h.

Referenced by _begin().

unsigned int pqxxobject::transaction::m_recursion_level [protected]
 

The recursion level (depth).

0 means no transaction, 1 is the top level and > 1 are recursive transactions.

Definition at line 294 of file transaction.h.

Referenced by _end(), abort(), begin(), commit(), and end().

SigC::Signal1<void, pqxxobject::transaction&> pqxxobject::transaction::m_signal_abort [protected]
 

The abort signal.

Definition at line 284 of file transaction.h.

Referenced by _abort(), _commit(), and signal_abort().

SigC::Signal1<void, pqxxobject::transaction&> pqxxobject::transaction::m_signal_commit [protected]
 

The commit signal.

Definition at line 282 of file transaction.h.

Referenced by _abort(), _commit(), and signal_commit().

state pqxxobject::transaction::m_state [protected]
 

The transaction state.

Definition at line 287 of file transaction.h.

Referenced by _abort(), _begin(), _commit(), _end(), abort(), exec(), exec_noresult(), and perform().

pqxx::transaction*& pqxxobject::transaction::m_transaction [protected]
 

A reference to a pointer to a PostgreSQL transaction object.

Definition at line 279 of file transaction.h.

Referenced by _abort(), _begin(), _commit(), _end(), and exec().


The documentation for this class was generated from the following files:
Generated on Wed Jan 28 21:22:50 2004 for pqxx-object API Reference by doxygen 1.3.4