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

[Fred L. Drake, Jr.]

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

Modified Files:
      Tag: zope3-zodb3-devel-branch
	interfaces.py 
Log Message:
checking in so jim can edit


=== Zope3/src/transaction/interfaces.py 1.5.50.2 => 1.5.50.3 ===
--- Zope3/src/transaction/interfaces.py:1.5.50.2	Fri Jan 16 10:43:29 2004
+++ Zope3/src/transaction/interfaces.py	Thu Jan 22 14:32:09 2004
@@ -18,23 +18,75 @@
     """Data management interface for storing objects transactionally
 
     This is currently implemented by ZODB database connections.
+
+    XXX This exists to document ZODB4 behavior, to help create some
+    backward-compatability support for Zope 3.  New classes shouldn't
+    implement this. They should implement ZODB.interfaces.IDataManager
+    for now. Our hope is that there will eventually be an interface
+    like this or that this interface will evolve and become the
+    standard interface. There are some issues to be resolved first, like:
+
+    - Probably want separate abort methods for use in and out of
+      two-phase commit.
+
+    - The savepoint api needs some more thought.
+    
     """
 
     def prepare(transaction):
-        """Begin two-phase commit of a transaction.
+        """Perform the first phase of a 2-phase commit
+
+        The data manager prepares for commit any changes to be made
+        persistent.  A normal return from this method indicated that
+        the data manager is ready to commit the changes.
 
         The data manager must raise an exception if it is not prepared
         to commit the transaction after executing prepare().
         """
+        
+        # This is equivalent to zodb3's tpc_begin, commit, and
+        # tpc_vote combined.
 
     def abort(transaction):
-        """Abort changes made by transaction."""
+        """Abort changes made by transaction
+
+        Call's to this method may or may not be preceeded by prepare calls.
+        """
+
+        # 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."""
+        """Commit changes made by transaction.
+        """
+
+        # This is equivalent to zodb3's tpc_finish
 
     def savepoint(transaction):
         """Do tentative commit of changes to this point.
 
-        Should return an object implementing IRollback
+        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.
+
+class IRollback(Interface):
+
+    def rollback():
+        """Rollback changes since savepoint.
+
+        IOW, rollback to the last savepoint.
+
+        It is an error to rollback to a savepoint if:
+
+        - An earlier savepoint within the same transaction has been
+          rolled back to, or
+
+        - The transaction has ended.
         """