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

transaction_base.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  *
00003  *   FILE
00004  *      pqxx/transaction_base.h
00005  *
00006  *   DESCRIPTION
00007  *      common code and definitions for the transaction classes.
00008  *   pqxx::transaction_base defines the interface for any abstract class that
00009  *   represents a database transaction
00010  *
00011  * Copyright (c) 2001-2003, Jeroen T. Vermeulen <jtv@xs4all.nl>
00012  *
00013  * See COPYING for copyright license.  If you did not receive a file called
00014  * COPYING with this source code, please notify the distributor of this mistake,
00015  * or contact the author.
00016  *
00017  *-------------------------------------------------------------------------
00018  */
00019 #ifndef PQXX_TRANSACTION_BASE_H
00020 #define PQXX_TRANSACTION_BASE_H
00021 
00022 
00023 /* End-user programs need not include this file, unless they define their own
00024  * transaction classes.  This is not something the typical program should want
00025  * to do.
00026  *
00027  * However, reading this file is worthwhile because it defines the public
00028  * interface for the available transaction classes such as transaction and 
00029  * nontransaction.
00030  */
00031 
00032 #include "pqxx/connection_base.h"
00033 #include "pqxx/isolation.h"
00034 #include "pqxx/result.h"
00035 
00036 /* Methods tested in eg. self-test program test1 are marked with "//[t1]"
00037  */
00038 
00039 
00040 namespace pqxx
00041 {
00042 class connection_base;  // See pqxx/connection_base.h
00043 class result;           // See pqxx/result.h
00044 class tablestream;      // See pqxx/tablestream.h
00045 
00046 
00048 template<> inline PGSTD::string Classname(const tablestream *) 
00049 { 
00050   return "tablestream"; 
00051 }
00052 
00053 
00055 
00063 class PQXX_LIBEXPORT transaction_base
00064 {
00065   // TODO: Move commit policy (robust, default, normal) out of inheritance tree
00066   // TODO: Support read-only transactions (no retry, not for nontransaction)
00067   // TODO: Retry non-serializable transaction w/update only on broken_connection
00068 public:
00070   typedef isolation_traits<read_committed> isolation_tag;
00071 
00072   virtual ~transaction_base() =0;                                       //[t1]
00073 
00075 
00087   void Commit();                                                        //[t1]
00088 
00090 
00093   void Abort();                                                         //[t10]
00094 
00096 
00100   result Exec(const char Query[], 
00101               const PGSTD::string &Desc=PGSTD::string());               //[t1]
00102 
00104 
00111   result Exec(const PGSTD::string &Query,
00112               const PGSTD::string &Desc=PGSTD::string())                //[t2]
00113         { return Exec(Query.c_str(), Desc); }
00114 
00116   void ProcessNotice(const char Msg[]) const                            //[t14]
00117         { m_Conn.ProcessNotice(Msg); }
00119   void ProcessNotice(const PGSTD::string &Msg) const                    //[t14]
00120         { m_Conn.ProcessNotice(Msg); }
00121 
00122   PGSTD::string Name() const { return m_Name; }                         //[t1]
00123 
00125   connection_base &Conn() const { return m_Conn; }                      //[t4]
00126 
00128 
00136   void SetVariable(const PGSTD::string &Var, const PGSTD::string &Value);//[]
00137 
00138 
00139 protected:
00142   explicit transaction_base(connection_base &, 
00143                           const PGSTD::string &TName=PGSTD::string());
00144 
00147   void Begin();
00148 
00150   void End() throw ();
00151 
00153   virtual void DoBegin() =0;
00155   virtual result DoExec(const char Query[]) =0;
00157   virtual void DoCommit() =0;
00159   virtual void DoAbort() =0;
00160 
00161   // For use by implementing class:
00162 
00164   result DirectExec(const char C[], int Retries, const char OnReconnect[]);
00165  
00166 private:
00167   /* A transaction goes through the following stages in its lifecycle:
00168    *  - nascent: the transaction hasn't actually begun yet.  If our connection 
00169    *    fails at this stage, it may recover and the transaction can attempt to
00170    *    establish itself again.
00171    *  - active: the transaction has begun.  Since no commit command has been 
00172    *    issued, abortion is implicit if the connection fails now.
00173    *  - aborted: an abort has been issued; the transaction is terminated and 
00174    *    its changes to the database rolled back.  It will accept no further 
00175    *    commands.
00176    *  - committed: the transaction has completed successfully, meaning that a 
00177    *    commit has been issued.  No further commands are accepted.
00178    *  - in_doubt: the connection was lost at the exact wrong time, and there is
00179    *    no way of telling whether the transaction was committed or aborted.
00180    *
00181    * Checking and maintaining state machine logic is the responsibility of the 
00182    * base class (ie., this one).
00183    */
00184   enum Status 
00185   { 
00186     st_nascent, 
00187     st_active, 
00188     st_aborted, 
00189     st_committed,
00190     st_in_doubt
00191   };
00192 
00193 
00194   friend class Cursor;
00195   int GetUniqueCursorNum() { return m_UniqueCursorNum++; }
00196   void MakeEmpty(result &R) const { m_Conn.MakeEmpty(R); }
00197 
00198   friend class tablestream;
00199   void RegisterStream(tablestream *);
00200   void UnregisterStream(tablestream *) throw ();
00201   void EndCopy() { m_Conn.EndCopy(); }
00202   friend class tablereader;
00203   void BeginCopyRead(const PGSTD::string &Table) 
00204         { m_Conn.BeginCopyRead(Table); }
00205   bool ReadCopyLine(PGSTD::string &L) { return m_Conn.ReadCopyLine(L); }
00206   friend class tablewriter;
00207   void BeginCopyWrite(const PGSTD::string &Table) 
00208         { m_Conn.BeginCopyWrite(Table); }
00209   void WriteCopyLine(const PGSTD::string &L) { m_Conn.WriteCopyLine(L); }
00210 
00211   connection_base &m_Conn;
00212 
00213   PGSTD::string m_Name;
00214   int m_UniqueCursorNum;
00215   unique<tablestream> m_Stream;
00216   Status m_Status;
00217   bool m_Registered;
00218   mutable PGSTD::map<PGSTD::string, PGSTD::string> m_Vars;
00219 
00220   // Not allowed:
00221   transaction_base();
00222   transaction_base(const transaction_base &);
00223   transaction_base &operator=(const transaction_base &);
00224 };
00225 
00226 
00227 }
00228 
00229 #endif
00230 

Generated on Sat Jun 7 00:49:34 2003 for libpqxx by doxygen1.3-rc3