Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | 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 exec (const std::ostringstream &query)
 Execute a query.

pqxx::result exec (const query &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 exec_noresult (const std::ostringstream &query)
 Execute a query without seeing the result set.

pqxx::result::size_type exec_noresult (const query &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.

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

pqxx::result::size_type perform (const query &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.

void set_checkpoint (bool checkpoint_exists=true)
 Set the transaction checkpoint status.

bool get_checkpoint () const
 Get the transaction checkpoint status.

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

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

SigC::Signal1< void, pqxxobject::transaction & > & signal_refresh ()
 Signal emitted on transaction commit or 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 rollback)
 Abort a transaction.

void _abort (bool rollback)
 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.

SigC::Signal1< void, pqxxobject::transaction & > m_signal_refresh
 The refresh signal.

state m_state
 The transaction state.

unsigned int m_recursion_level
 The recursion level (depth).

bool m_checkpoint
 The checkpoint state.


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 84 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 88 of file transaction.h.


Constructor & Destructor Documentation

transaction::transaction pqxx::connection &  conn,
pqxx::transaction<> *&  tran
[explicit]
 

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 81 of file transaction.cc.

transaction::~transaction  )  [virtual]
 

The destructor.

Definition at line 91 of file transaction.cc.


Member Function Documentation

void transaction::_abort bool  rollback  )  [protected]
 

Abort a transaction.

This method does the actual work.

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

Definition at line 413 of file transaction.cc.

References begin(), commit(), end(), m_signal_abort, m_signal_commit, m_signal_refresh, 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 316 of file transaction.cc.

References m_connection, 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 365 of file transaction.cc.

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

Referenced by commit().

void transaction::_end  )  [protected]
 

End a transaction.

This method does the actual work.

Definition at line 328 of file transaction.cc.

References m_recursion_level, and STATE_NONE.

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

void transaction::abort bool  rollback  )  [protected]
 

Abort a transaction.

This method is just a stub for _abort().

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

Definition at line 391 of file transaction.cc.

References _abort(), _end(), end(), m_recursion_level, 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 310 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 126 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 343 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 304 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 148 of file transaction.cc.

References _end(), and m_recursion_level.

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

pqxx::result transaction::exec const query 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 203 of file transaction.cc.

References exec(), and pqxxobject::query::str().

pqxx::result transaction::exec const std::ostringstream &  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 197 of file transaction.cc.

References exec().

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 174 of file transaction.cc.

References describe_status(), and STATE_EXECUTING.

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

pqxx::result::size_type transaction::exec_noresult const query 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 241 of file transaction.cc.

References exec_noresult(), and pqxxobject::query::str().

pqxx::result::size_type transaction::exec_noresult const std::ostringstream &  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 235 of file transaction.cc.

References exec_noresult().

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 209 of file transaction.cc.

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

Referenced by exec_noresult(), and perform().

bool transaction::get_checkpoint  )  const
 

Get the transaction checkpoint status.

Returns:
true if a checkpoint object exists, otherwise false.

Definition at line 102 of file transaction.cc.

Referenced by pqxxobject::row< Row >::begin_impl(), and pqxxobject::row_base::unset_checkpoint().

pqxx::result::size_type transaction::perform const query 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 296 of file transaction.cc.

References perform(), and pqxxobject::query::str().

pqxx::result::size_type transaction::perform const std::ostringstream &  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 288 of file transaction.cc.

References 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 247 of file transaction.cc.

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

Referenced by perform().

void transaction::set_checkpoint bool  checkpoint_exists = true  ) 
 

Set the transaction checkpoint status.

The checkpoint status should be set to true immediately after a checkpoint object has been created, and set back to false immediately after control returns to the function that set it to true in the first place. This should be taken care of by row_base.

Parameters:
checkpoint_exists set to true if a checkpoint object exists, otherwise false.

Definition at line 96 of file transaction.cc.

Referenced by pqxxobject::row_base::unset_checkpoint().

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 their row_base::abort will be called on transaction completion.

Returns:
the signal.

Definition at line 114 of file transaction.cc.

References m_signal_abort.

Referenced by pqxxobject::row_base::connect_safe_signal_handlers(), and pqxxobject::row_base::connect_signal_handlers().

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 their row_base::commit will be called on transaction completion.

Returns:
the signal.

Definition at line 108 of file transaction.cc.

References m_signal_commit.

Referenced by pqxxobject::row_base::connect_safe_signal_handlers(), and pqxxobject::row_base::connect_signal_handlers().

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

Signal emitted on transaction commit or abort.

All rows that are affected by a transaction are registered with this signal automatically, and their row_base::refresh will be called on transaction completion.

Returns:
the signal.

Definition at line 120 of file transaction.cc.

References m_signal_refresh.

Referenced by pqxxobject::row_base::connect_signal_handlers().


Member Data Documentation

bool pqxxobject::transaction::m_checkpoint [protected]
 

The checkpoint state.

Set to true if a checkpoint object exists for the current object heirarchy, otherwise false.

Definition at line 421 of file transaction.h.

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

A reference to a PostgreSQL database connection object.

Definition at line 395 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 414 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 402 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 400 of file transaction.h.

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

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

The refresh signal.

Definition at line 404 of file transaction.h.

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

state pqxxobject::transaction::m_state [protected]
 

The transaction state.

Definition at line 407 of file transaction.h.

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

A reference to a pointer to a PostgreSQL transaction object.

Definition at line 397 of file transaction.h.


The documentation for this class was generated from the following files:
Generated on Sat May 22 18:34:02 2004 for pqxxobject API Reference by doxygen 1.3.6-20040222