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::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.

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

transaction::~transaction  )  [virtual]
 

The destructor.

Definition at line 90 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 372 of file transaction.cc.

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

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

References m_checkpoint, m_recursion_level, m_state, m_transaction, 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 350 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 269 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 125 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 302 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 263 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 147 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 173 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 196 of file transaction.cc.

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

Referenced by perform().

bool transaction::get_checkpoint  )  const
 

Get the transaction checkpoint status.

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

Definition at line 101 of file transaction.cc.

References m_checkpoint.

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

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

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

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

References m_checkpoint.

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 113 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 107 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 119 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 330 of file transaction.h.

Referenced by _end(), get_checkpoint(), and set_checkpoint().

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

A reference to a PostgreSQL database connection object.

Definition at line 304 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 323 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 311 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 309 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 313 of file transaction.h.

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

state pqxxobject::transaction::m_state [protected]
 

The transaction state.

Definition at line 316 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 306 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 Thu Apr 1 10:37:57 2004 for pqxx-object API Reference by doxygen 1.3.5