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

pqxx::transactor< TRANSACTION > Class Template Reference

Wrapper for transactions that automatically restarts them on failure. More...

#include <transactor.hxx>

List of all members.

Public Member Functions

 transactor (const PGSTD::string &TName="transactor")
void operator() (TRANSACTION &T)
 Overridable transaction definition; insert your database code here.

void OnAbort (const char[]) throw ()
 Optional overridable function to be called if transaction is aborted.

void OnCommit ()
 Optional overridable function to be called when committing the transaction.

void OnDoubt () throw ()
 Overridable function to be called when "in doubt" about success.

PGSTD::string Name () const
 The transactor's name.


Detailed Description

template<typename TRANSACTION = transaction<read_committed>>
class pqxx::transactor< TRANSACTION >

Wrapper for transactions that automatically restarts them on failure.

Some transactions may be replayed if their connection fails, until they do succeed. These can be encapsulated in a transactor-derived classes. The transactor framework will take care of setting up a backend transaction context for the operation, and of aborting and retrying if its connection goes bad.

The transactor framework also makes it easier for you to do this safely, avoiding typical pitfalls and encouraging programmers to separate their transaction definitions (essentially, business rules implementations) from their higher-level code (application using those business rules). The former go into the transactor-based class.

Pass an object of your transactor-based class to connection_base::perform() to execute the transaction code embedded in it (see the definitions in pqxx/connection_base.hxx).

connection_base::Perform() is actually a template, specializing itself to any transactor type you pass to it. This means you will have to pass it a reference of your object's ultimate static type; runtime polymorphism is not allowed. Hence the absence of virtual methods in transactor. The exact methods to be called at runtime *must* be resolved at compile time.

Your transactor-derived class must define a copy constructor. This will be used to create a "clean" copy of your transactor for every attempt that Perform() makes to run it.


Constructor & Destructor Documentation

template<typename TRANSACTION = transaction<read_committed>>
pqxx::transactor< TRANSACTION >::transactor const PGSTD::string &  TName = "transactor< TRANSACTION >"  )  [explicit]
 


Member Function Documentation

template<typename TRANSACTION = transaction<read_committed>>
PGSTD::string pqxx::transactor< TRANSACTION >::Name  )  const
 

The transactor's name.

template<typename TRANSACTION = transaction<read_committed>>
void pqxx::transactor< TRANSACTION >::OnAbort const  char[]  )  throw ()
 

Optional overridable function to be called if transaction is aborted.

This need not imply complete failure; the transactor will automatically retry the operation a number of times before giving up. OnAbort() will be called for each of the failed attempts. The argument is an error string describing why the transaction failed.

template<typename TRANSACTION = transaction<read_committed>>
void pqxx::transactor< TRANSACTION >::OnCommit  ) 
 

Optional overridable function to be called when committing the transaction.

If your OnCommit() throws an exception, the actual back-end transaction will remain committed, so any changes in the database remain.

template<typename TRANSACTION = transaction<read_committed>>
void pqxx::transactor< TRANSACTION >::OnDoubt  )  throw ()
 

Overridable function to be called when "in doubt" about success.

This may happen if the connection to the backend is lost while attempting to commit. In that case, the backend may have committed the transaction but is unable to confirm this to the frontend; or the backend may have failed completely, causing the transaction to be aborted. The best way to deal with this situation is to wave red flags in the user's face and ask him to investigate. Also, the robusttransaction class is intended to reduce the chances of this error occurring.

template<typename TRANSACTION = transaction<read_committed>>
void pqxx::transactor< TRANSACTION >::operator() TRANSACTION &  T  ) 
 

Overridable transaction definition; insert your database code here.

Will be retried if connection goes bad, but not if an exception is thrown while the connection remains open.

Parameters:
T a dedicated transaction context created to perform this operation. It is generally recommended that a transactor modify only itself and T from inside this operator.


The documentation for this class was generated from the following file:
Generated on Thu Feb 19 22:04:39 2004 for libpqxx by doxygen 1.3.5