[Zope3-checkins] CVS: Zope3/src/transaction - interfaces.py:1.5.50.4

[Jim Fulton]

Update of /cvs-repository/Zope3/src/transaction
In directory cvs.zope.org:/tmp/cvs-serv30433

Modified Files:
      Tag: zope3-zodb3-devel-branch
	interfaces.py 
Log Message:
Added some additional details.


=== Zope3/src/transaction/interfaces.py 1.5.50.3 => 1.5.50.4 ===
--- Zope3/src/transaction/interfaces.py:1.5.50.3	Thu Jan 22 14:32:09 2004
+++ Zope3/src/transaction/interfaces.py	Thu Jan 22 14:42:53 2004
@@ -29,7 +29,7 @@
     - Probably want separate abort methods for use in and out of
       two-phase commit.
 
-    - The savepoint api needs some more thought.
+    - The savepoint api may need some more thought.
     
     """
 
@@ -42,6 +42,9 @@
 
         The data manager must raise an exception if it is not prepared
         to commit the transaction after executing prepare().
+
+        The transaction must match that used for preceeding
+        savepoints, if any.
         """
         
         # This is equivalent to zodb3's tpc_begin, commit, and
@@ -50,14 +53,23 @@
     def abort(transaction):
         """Abort changes made by transaction
 
-        Call's to this method may or may not be preceeded by prepare calls.
+        This may be called before two-phase commit or in the second
+        phase of two-phase commit.
+
+        The transaction must match that used for preceeding
+        savepoints, if any.
+
         """
 
         # This is equivalent to *both* zodb3's abort and tpc_abort
         # calls. This should probably be split into 2 methods.
 
     def commit(transaction):
-        """Commit changes made by transaction.
+        """Finish two-phase commit
+
+        The prepare method must be called, with the same transaction,
+        before calling commit.
+        
         """
 
         # This is equivalent to zodb3's tpc_finish
@@ -68,13 +80,21 @@
         Should return an object implementing IRollback that can be used
         to rollback to the savepoint.
         
+        Note that (unlike zodb3) this doesn't use a 2-phase commit
+        protocol.  If this call fails, or if a rollback call on the
+        result fails, the (containing) transaction should be
+        aborted.  Aborting the containing transaction is *not* the
+        responsibility of the data manager, however.
+
+        An implementation that doesn't support savepoints should
+        implement this method by returning a rollback implementation
+        that always raises an error when it's rollback method is
+        called. The savepoing method shouldn't raise an error. This
+        way, transactions that create savepoints can proceed as long
+        as an attempt is never made to roll back a savepoint.
+
         """
 
-        # Note that (unlike zodb3)this doesn't use a 2-phase commit
-        # protocol.  If this call fails, or if a rollback call on the
-        # result fails, the (containing) transaction should be
-        # aborted.  Aborting the containing transaction is *not* the
-        # responsibility of the data manager, however.
 
 class IRollback(Interface):