head	1.1;
access;
symbols
	REL7_3_STABLE:1.1.0.2;
locks; strict;
comment	@# @;


1.1
date	2002.08.10.21.03.36;	author jtv;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Added Ray Dassen's Debian stuff, autoconf updates, and .cvsignore files;
added doxygen-generated reference documentation
@
text
@<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>pqxx::Transactor class Reference</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.2.16 -->
<center>
<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="namespaces.html">Namespace List</a> &nbsp; <a class="qindex" href="hierarchy.html">Class Hierarchy</a> &nbsp; <a class="qindex" href="classes.html">Alphabetical List</a> &nbsp; <a class="qindex" href="annotated.html">Compound List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="namespacemembers.html">Namespace Members</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; <a class="qindex" href="globals.html">File Members</a> &nbsp; </center>
<hr><h1>pqxx::Transactor  Class Reference</h1>Wrapper for transactions that automatically restarts them on failure. 
<a href="#_details">More...</a>
<p>
<code>#include &lt;<a class="el" href="transactor_8h-source.html">transactor.h</a>&gt;</code>
<p>
<a href="classpqxx_1_1Transactor-members.html">List of all members.</a><table border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><h2>Public Types</h2></td></tr>
<tr><td nowrap align=right valign=top>typedef <a class="el" href="classpqxx_1_1Transaction.html">Transaction</a>&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#s0">argument_type</a></td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Define transaction class to use as a wrapper for this code.</em> <a href="#s0"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>typedef void&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#s1">result_type</a></td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Required to make <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> adaptable.</em> <a href="#s1"></a><em></em></font><br><br></td></tr>
<tr><td colspan=2><br><h2>Public Methods</h2></td></tr>
<tr><td nowrap align=right valign=top>&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a0">Transactor</a> (PGSTD::string TName="AnonymousTransactor")</td></tr>
<tr><td nowrap align=right valign=top>void&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a1">operator()</a> (<a class="el" href="classpqxx_1_1Transactor.html#s0">argument_type</a> &amp;T)</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Overridable transaction definition.</em> <a href="#a1"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a2">OnAbort</a> (const char[])  throw ()</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Overridable function to be called if transaction is aborted.</em> <a href="#a2"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a3">OnCommit</a> ()</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>Overridable function to be called when committing the transaction.</em> <a href="#a3"></a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a4">OnDoubt</a> ()  throw ()</td></tr>
<tr><td nowrap align=right valign=top>PGSTD::string&nbsp;</td><td valign=bottom><a class="el" href="classpqxx_1_1Transactor.html#a5">Name</a> () const</td></tr>
<tr><td>&nbsp;</td><td><font size=-1><em>The <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>'s name.</em> <a href="#a5"></a><em></em></font><br><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
Wrapper for transactions that automatically restarts them on failure.
<p>
Some transactions may be replayed if their connection fails, until they do  succeed. These can be encapsulated in a <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>-derived classes. The  <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> framework will take care of setting up a backend transaction  context for the operation, and of aborting and retrying if its connection  goes bad.
<p>
The <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> 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 <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>-based class.
<p>
Pass an object of your <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>-based class to <a class="el" href="classpqxx_1_1Connection.html#a4">Connection::Perform</a>() to execute the transaction code embedded in it (see <a class="el" href="connection_8h.html">pqxx/connection.h</a>).
<p>
<a class="el" href="classpqxx_1_1Connection.html#a4">Connection::Perform</a>() is actually a template, specializing itself to any <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> 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 <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>. The exact methods to be called at runtime *must* be resolved at compile time.
<p>
Your <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>-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. 
<p>
<hr><h2>Member Typedef Documentation</h2>
<a name="s0" doxytag="pqxx::Transactor::argument_type"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> typedef <a class="el" href="classpqxx_1_1Transaction.html">Transaction</a> pqxx::Transactor::argument_type
      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Define transaction class to use as a wrapper for this code.
<p>
Select the quality of service for your transactor by overriding this in your derived class.     </td>
  </tr>
</table>
<a name="s1" doxytag="pqxx::Transactor::result_type"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> typedef void pqxx::Transactor::result_type
      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Required to make <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> adaptable.
<p>
    </td>
  </tr>
</table>
<hr><h2>Constructor &amp; Destructor Documentation</h2>
<a name="a0" doxytag="pqxx::Transactor::Transactor"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> pqxx::Transactor::Transactor </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">PGSTD::string&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp; <em>TName</em> = "AnonymousTransactor"          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap><code> [explicit]</code></td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
    </td>
  </tr>
</table>
<hr><h2>Member Function Documentation</h2>
<a name="a5" doxytag="pqxx::Transactor::Name"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> PGSTD::string pqxx::Transactor::Name </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp;          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap> const</td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
The <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a>'s name.
<p>
    </td>
  </tr>
</table>
<a name="a2" doxytag="pqxx::Transactor::OnAbort"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> void pqxx::Transactor::OnAbort </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top">const&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp; <em>char</em>[]          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap>  throw ()</td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Overridable function to be called if transaction is aborted.
<p>
This need not imply complete failure; the <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> will automatically retry the operation a number of times before giving up. <a class="el" href="classpqxx_1_1Transactor.html#a2">OnAbort</a>() will be called for each of the failed attempts. The Reason argument is an error string describing why the transaction  failed.     </td>
  </tr>
</table>
<a name="a3" doxytag="pqxx::Transactor::OnCommit"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> void pqxx::Transactor::OnCommit </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp;          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap></td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Overridable function to be called when committing the transaction.
<p>
If your <a class="el" href="classpqxx_1_1Transactor.html#a3">OnCommit</a>() throws an exception, the actual back-end transaction will remain committed, so any changes in the database remain.     </td>
  </tr>
</table>
<a name="a4" doxytag="pqxx::Transactor::OnDoubt"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> void pqxx::Transactor::OnDoubt </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp;          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap>  throw ()</td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
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 <a class="el" href="classpqxx_1_1RobustTransaction.html">RobustTransaction</a> class is intended to reduce the chances of this error occurring.     </td>
  </tr>
</table>
<a name="a1" doxytag="pqxx::Transactor::operator()"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
  <tr>
    <td class="md">
      <table cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td class="md" nowrap valign="top"> void pqxx::Transactor::operator() </td>
          <td class="md" valign="top">(&nbsp;</td>
          <td class="md" nowrap valign="top"><a class="el" href="classpqxx_1_1Transactor.html#s0">argument_type</a> &amp;&nbsp;</td>
          <td class="mdname1" valign="top" nowrap>&nbsp; <em>T</em>          </td>
          <td class="md" valign="top">)&nbsp;</td>
          <td class="md" nowrap></td>
        </tr>

      </table>
    </td>
  </tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
  <tr>
    <td>
      &nbsp;
    </td>
    <td>

<p>
Overridable transaction definition.
<p>
Will be retried if connection goes bad, but not if an exception is thrown  while the connection remains open. <dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>T</em>&nbsp;</td><td>
a dedicated transaction context created to perform this  operation. It is generally recommended that a <a class="el" href="classpqxx_1_1Transactor.html">Transactor</a> modify only  itself and T from inside this operator. </td></tr>
</table>
</dl>    </td>
  </tr>
</table>
<hr>The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="transactor_8h-source.html">transactor.h</a></ul>
<hr><address align="right"><small>Generated on Sat Aug 10 21:52:40 2002 for libpqxx by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border=0 
width=110 height=53></a>1.2.16 </small></address>
</body>
</html>
@
