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-2002, 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/connection.h"
00030 #include "pqxx/util.h"
00031 
00032 /* Methods tested in eg. self-test program test1 are marked with "//[t1]"
00033  */
00034 
00035 
00036 // TODO: Any user-friendliness we can add to invoking stored procedures?
00037 
00038 namespace pqxx
00039 {
00040 class Connection;       // See pqxx/connection.h
00041 class Result;           // See pqxx/result.h
00042 class TableStream;      // See pqxx/tablestream.h
00043 
00044 
00045 template<> inline PGSTD::string Classname(const TableStream *) 
00046 { 
00047   return "TableStream"; 
00048 }
00049 
00050 
00052 
00056 class PQXX_LIBEXPORT TransactionItf
00057 {
00058 public:
00059   virtual ~TransactionItf() =0;                                         //[t1]
00060 
00061   void Commit();                                                        //[t1]
00062   void Abort();                                                         //[t10]
00063 
00065   Result Exec(const char[]);                                            //[t1]
00066 
00067   void ProcessNotice(const char Msg[]) { m_Conn.ProcessNotice(Msg); }   //[t1]
00068   void ProcessNotice(PGSTD::string Msg) { m_Conn.ProcessNotice(Msg); }  //[t1]
00069 
00070   PGSTD::string Name() const { return m_Name; }                         //[t1]
00071 
00072 protected:
00075   explicit TransactionItf(Connection &, 
00076                           PGSTD::string Name=PGSTD::string());
00077 
00080   void Begin();
00081 
00083   void End() throw ();
00084 
00086   virtual void DoBegin() =0;
00087   virtual Result DoExec(const char C[]) =0;
00088   virtual void DoCommit() =0;
00089   virtual void DoAbort() =0;
00090 
00091   // For use by implementing class:
00092 
00094   Result DirectExec(const char C[], int Retries, const char OnReconnect[]);
00095   Connection &Conn() const { return m_Conn; }
00096 
00097  
00098 private:
00099   /* A Transaction goes through the following stages in its lifecycle:
00100    *  - nascent: the transaction hasn't actually begun yet.  If our connection 
00101    *    fails at this stage, the Connection may recover and the Transaction can 
00102    *    attempt to establish itself again.
00103    *  - active: the transaction has begun.  Since no commit command has been 
00104    *    issued, abortion is implicit if the connection fails now.
00105    *  - aborted: an abort has been issued; the transaction is terminated and 
00106    *    its changes to the database rolled back.  It will accept no further 
00107    *    commands.
00108    *  - committed: the transaction has completed successfully, meaning that a 
00109    *    commit has been issued.  No further commands are accepted.
00110    *  - in_doubt: the connection was lost at the exact wrong time, and there is
00111    *    no way of telling whether the transaction was committed or aborted.
00112    *
00113    * Checking and maintaining state machine logic is the responsibility of the 
00114    * base class (ie., this one).
00115    */
00116   enum Status 
00117   { 
00118     st_nascent, 
00119     st_active, 
00120     st_aborted, 
00121     st_committed,
00122     st_in_doubt
00123   };
00124 
00125 
00126   friend class Cursor;
00127   int GetUniqueCursorNum() { return m_UniqueCursorNum++; }
00128   void MakeEmpty(Result &R) const { m_Conn.MakeEmpty(R); }
00129 
00130   friend class TableStream;
00131   void RegisterStream(const TableStream *);
00132   void UnregisterStream(const TableStream *) throw ();
00133   void EndCopy() { m_Conn.EndCopy(); }
00134   friend class TableReader;
00135   void BeginCopyRead(PGSTD::string Table) { m_Conn.BeginCopyRead(Table); }
00136   bool ReadCopyLine(PGSTD::string &L) { return m_Conn.ReadCopyLine(L); }
00137   friend class TableWriter;
00138   void BeginCopyWrite(PGSTD::string Table) {m_Conn.BeginCopyWrite(Table);}
00139   void WriteCopyLine(PGSTD::string L) { m_Conn.WriteCopyLine(L); }
00140 
00141   Connection &m_Conn;
00142 
00143   PGSTD::string m_Name;
00144   int m_UniqueCursorNum;
00145   Unique<TableStream> m_Stream;
00146   Status m_Status;
00147   bool m_Registered;
00148 
00149   // Not allowed:
00150   TransactionItf();
00151   TransactionItf(const TransactionItf &);
00152   TransactionItf &operator=(const TransactionItf &);
00153 };
00154 
00155 
00157 
00163 class PQXX_LIBEXPORT in_doubt_error : public PGSTD::runtime_error
00164 {
00165 public:
00166   explicit in_doubt_error(const PGSTD::string &whatarg) : 
00167     PGSTD::runtime_error(whatarg) {}
00168 };
00169 
00170 }
00171 
00172 #endif
00173 

Generated on Sat Aug 10 21:52:38 2002 for libpqxx by doxygen1.2.16