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

transactionitf.h

Go to the documentation of this file.
00001 /*-------------------------------------------------------------------------
00002  *
00003  *   FILE
00004  *      pqxx/transactionitf.h
00005  *
00006  *   DESCRIPTION
00007  *      common code and definitions for the transaction classes.
00008  *   pqxx::TransactionItf 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  *-------------------------------------------------------------------------
00014  */
00015 #ifndef PQXX_TRANSACTIONITF_H
00016 #define PQXX_TRANSACTIONITF_H
00017 
00018 
00019 /* End-user programs need not include this file, unless they define their own
00020  * transaction classes.  This is not something the typical program should want
00021  * to do.
00022  *
00023  * However, reading this file is worthwhile because it defines the public
00024  * interface for the available transaction classes such as Transaction and 
00025  * NonTransaction.
00026  */
00027 
00028 
00029 #include "pqxx/connectionitf.h"
00030 #include "pqxx/result.h"
00031 
00032 /* Methods tested in eg. self-test program test1 are marked with "//[t1]"
00033  */
00034 
00035 
00036 namespace pqxx
00037 {
00038 class ConnectionItf;    // See pqxx/connectionitf.h
00039 class Result;           // See pqxx/result.h
00040 class TableStream;      // See pqxx/tablestream.h
00041 
00042 
00043 template<> inline PGSTD::string Classname(const TableStream *) 
00044 { 
00045   return "TableStream"; 
00046 }
00047 
00048 
00050 
00058 class PQXX_LIBEXPORT TransactionItf
00059 {
00060 public:
00061   virtual ~TransactionItf() =0;                                         //[t1]
00062 
00064 
00076   void Commit();                                                        //[t1]
00077 
00079 
00082   void Abort();                                                         //[t10]
00083 
00085 
00089   Result Exec(const char Query[], 
00090               const PGSTD::string &Desc=PGSTD::string());               //[t1]
00091 
00093 
00100   Result Exec(const PGSTD::string &Query,
00101               const PGSTD::string &Desc=PGSTD::string())                //[t2]
00102         { return Exec(Query.c_str(), Desc); }
00103 
00105   void ProcessNotice(const char Msg[]) const                            //[t14]
00106         { m_Conn.ProcessNotice(Msg); }
00108   void ProcessNotice(const PGSTD::string &Msg) const                    //[t14]
00109         { m_Conn.ProcessNotice(Msg); }
00110 
00111   PGSTD::string Name() const { return m_Name; }                         //[t1]
00112 
00114   ConnectionItf &Conn() const { return m_Conn; }                        //[t4]
00115 
00117 
00125   void SetVariable(const PGSTD::string &Var, const PGSTD::string &Value);//[]
00126 
00127 
00128 protected:
00131   explicit TransactionItf(ConnectionItf &, 
00132                           const PGSTD::string &TName=PGSTD::string());
00133 
00136   void Begin();
00137 
00139   void End() throw ();
00140 
00142   virtual void DoBegin() =0;
00143   virtual Result DoExec(const char Query[]) =0;
00144   virtual void DoCommit() =0;
00145   virtual void DoAbort() =0;
00146 
00147   // For use by implementing class:
00148 
00150   Result DirectExec(const char C[], int Retries, const char OnReconnect[]);
00151  
00152 private:
00153   /* A Transaction goes through the following stages in its lifecycle:
00154    *  - nascent: the transaction hasn't actually begun yet.  If our connection 
00155    *    fails at this stage, it may recover and the Transaction can attempt to
00156    *    establish itself again.
00157    *  - active: the transaction has begun.  Since no commit command has been 
00158    *    issued, abortion is implicit if the connection fails now.
00159    *  - aborted: an abort has been issued; the transaction is terminated and 
00160    *    its changes to the database rolled back.  It will accept no further 
00161    *    commands.
00162    *  - committed: the transaction has completed successfully, meaning that a 
00163    *    commit has been issued.  No further commands are accepted.
00164    *  - in_doubt: the connection was lost at the exact wrong time, and there is
00165    *    no way of telling whether the transaction was committed or aborted.
00166    *
00167    * Checking and maintaining state machine logic is the responsibility of the 
00168    * base class (ie., this one).
00169    */
00170   enum Status 
00171   { 
00172     st_nascent, 
00173     st_active, 
00174     st_aborted, 
00175     st_committed,
00176     st_in_doubt
00177   };
00178 
00179 
00180   friend class Cursor;
00181   int GetUniqueCursorNum() { return m_UniqueCursorNum++; }
00182   void MakeEmpty(Result &R) const { m_Conn.MakeEmpty(R); }
00183 
00184   friend class TableStream;
00185   void RegisterStream(TableStream *);
00186   void UnregisterStream(TableStream *) throw ();
00187   void EndCopy() { m_Conn.EndCopy(); }
00188   friend class TableReader;
00189   void BeginCopyRead(const PGSTD::string &Table) 
00190         { m_Conn.BeginCopyRead(Table); }
00191   bool ReadCopyLine(PGSTD::string &L) { return m_Conn.ReadCopyLine(L); }
00192   friend class TableWriter;
00193   void BeginCopyWrite(const PGSTD::string &Table) 
00194         { m_Conn.BeginCopyWrite(Table); }
00195   void WriteCopyLine(const PGSTD::string &L) { m_Conn.WriteCopyLine(L); }
00196 
00197   ConnectionItf &m_Conn;
00198 
00199   PGSTD::string m_Name;
00200   int m_UniqueCursorNum;
00201   Unique<TableStream> m_Stream;
00202   Status m_Status;
00203   bool m_Registered;
00204   mutable PGSTD::map<PGSTD::string, PGSTD::string> m_Vars;
00205 
00206   // Not allowed:
00207   TransactionItf();
00208   TransactionItf(const TransactionItf &);
00209   TransactionItf &operator=(const TransactionItf &);
00210 };
00211 
00212 
00213 }
00214 
00215 #endif
00216 

Generated on Sun May 4 06:03:42 2003 for libpqxx by doxygen1.3-rc3