- Various interface cleanups. ZODB.Connection.Connection is now completely

   documented in an interface.

 - The IDataManager, IDataManagerOrignal and IResourceManager cludge was
   cleaned up to be only IDataManager now which reflects the current 
   situation.

branches/pycon-multidb/src/ZODB/BaseStorage.py

@@ -252,6 +252,12 @@ class BaseStorage(UndoLogCompatible):
         pass
 
     def tpc_finish(self, transaction, f=None):
+        # It's important that the storage calls the function we pass
+        # while it still has its lock.  We don't want another thread
+        # to be able to read any updated data until we've had a chance
+        # to send an invalidation message to all of the other
+        # connections!
+
         self._lock_acquire()
         try:
             if transaction is not self._transaction:

branches/pycon-multidb/src/ZODB/DB.py

@@ -581,7 +581,7 @@ class DB(object):
         def get_info(c):
             # `result`, `time` and `version` are lexically inherited.
             o = c._opened
-            d = c._debug_info
+            d = c.getDebugInfo()
             if d:
                 if len(d) == 1:
                     d = d[0]

branches/pycon-multidb/src/ZODB/TmpStore.py

@@ -61,6 +61,9 @@ class TmpStore:
         serial = h[:8]
         return self._file.read(size), serial
 
+    def sortKey(self):
+        return self._storage.sortKey()
+
     # TODO: clarify difference between self._storage & self._db._storage
 
     def modifiedInVersion(self, oid):

branches/pycon-multidb/src/ZODB/interfaces.py

@@ -19,11 +19,118 @@ $Id$
 from zope.interface import Interface, Attribute
 
 class IConnection(Interface):
-    """ZODB connection.
+    """Connection to ZODB for loading and storing objects.
 
-    TODO: This interface is incomplete.
+    The Connection object serves as a data manager.  The root() method
+    on a Connection returns the root object for the database.  This
+    object and all objects reachable from it are associated with the
+    Connection that loaded them.  When a transaction commits, it uses
+    the Connection to store modified objects.
+
+    Typical use of ZODB is for each thread to have its own
+    Connection and that no thread should have more than one Connection
+    to the same database.  A thread is associated with a Connection by
+    loading objects from that Connection.  Objects loaded by one
+    thread should not be used by another thread.
+
+    A Connection can be associated with a single version when it is
+    created.  By default, a Connection is not associated with a
+    version; it uses non-version data.
+
+    Each Connection provides an isolated, consistent view of the
+    database, by managing independent copies of objects in the
+    database.  At transaction boundaries, these copies are updated to
+    reflect the current state of the database.
+
+    You should not instantiate this class directly; instead call the
+    open() method of a DB instance.
+
+    In many applications, root() is the only method of the Connection
+    that you will need to use.
+
+    Synchronization
+    ---------------
+
+    A Connection instance is not thread-safe.  It is designed to
+    support a thread model where each thread has its own transaction.
+    If an application has more than one thread that uses the
+    connection or the transaction the connection is registered with,
+    the application should provide locking.
+
+    The Connection manages movement of objects in and out of object
+    storage.
+
+    TODO:  We should document an intended API for using a Connection via
+    multiple threads.
+
+    TODO:  We should explain that the Connection has a cache and that
+    multiple calls to get() will return a reference to the same
+    object, provided that one of the earlier objects is still
+    referenced.  Object identity is preserved within a connection, but
+    not across connections.
+
+    TODO:  Mention the database pool.
+
+    A database connection always presents a consistent view of the
+    objects in the database, although it may not always present the
+    most current revision of any particular object.  Modifications
+    made by concurrent transactions are not visible until the next
+    transaction boundary (abort or commit).
+
+    Two options affect consistency.  By default, the mvcc and synch
+    options are enabled by default.
+
+    If you pass mvcc=True to db.open(), the Connection will never read
+    non-current revisions of an object.  Instead it will raise a
+    ReadConflictError to indicate that the current revision is
+    unavailable because it was written after the current transaction
+    began.
+
+    The logic for handling modifications assumes that the thread that
+    opened a Connection (called db.open()) is the thread that will use
+    the Connection.  If this is not true, you should pass synch=False
+    to db.open().  When the synch option is disabled, some transaction
+    boundaries will be missed by the Connection; in particular, if a
+    transaction does not involve any modifications to objects loaded
+    from the Connection and synch is disabled, the Connection will
+    miss the transaction boundary.  Two examples of this behavior are
+    db.undo() and read-only transactions.
+
+    Groups of methods:
+
+        User Methods:
+            root, get, add, close, db, sync, isReadOnly, cacheGC, cacheFullSweep, 
+            cacheMinimize, getVersion, modifiedInVersion
+
+        Experimental Methods: 
+            onCloseCallbacks
+
+        Database Invalidation Methods:
+            invalidate
+
+        Other Methods: exchange, getDebugInfo, setDebugInfo, 
+            getTransferCounts
     """
 
+    def __init__(version='', cache_size=400,
+                 cache_deactivate_after=None, mvcc=True, txn_mgr=None,
+                 synch=True):
+        """Create a new Connection.
+
+        A Connection instance should by instantiated by the DB
+        instance that it is connected to.
+
+        Parameters:
+        version: the "version" that all changes will be made in, defaults 
+            to no version.
+        cache_size: the target size of the in-memory object cache, measured 
+            in objects.
+        mvcc: boolean indicating whether MVCC is enabled
+        txn_mgr: transaction manager to use. None means used the default 
+            transaction manager.
+        synch: boolean indicating whether Connection should register for 
+            afterCompletion() calls.
+        """
 
     def add(ob):
         """Add a new object 'obj' to the database and assign it an oid.
@@ -39,8 +146,108 @@ class IConnection(Interface):
         The object is added when the transaction commits.  The object
         must implement the IPersistent interface and must not
         already be associated with a Connection.
+
+        Parameters:
+        obj: a Persistent object
+
+        Raises TypeError if obj is not a persistent object.
+
+        Raises InvalidObjectReference if obj is already associated with another
+        connection.
+
+        Raises ConnectionStateError if the connection is closed.
+        """
+
+    def get(oid):
+        """Return the persistent object with oid 'oid'.
+
+        If the object was not in the cache and the object's class is
+        ghostable, then a ghost will be returned.  If the object is
+        already in the cache, a reference to the cached object will be
+        returned.
+
+        Applications seldom need to call this method, because objects
+        are loaded transparently during attribute lookup.
+
+        Parameters:
+        oid: an object id
+
+        Raises KeyError if oid does not exist.  
+        
+            It is possible that an
+            object does not exist as of the current transaction, but
+            existed in the past.  It may even exist again in the
+            future, if the transaction that removed it is undone.
+
+        Raises ConnectionStateError if the connection is closed.
+        """
+
+    def cacheMinimize():
+        """Deactivate all unmodified objects in the cache.
+
+        Call _p_deactivate() on each cached object, attempting to turn
+        it into a ghost.  It is possible for individual objects to
+        remain active.
+        """
+
+    def cacheGC():
+        """Reduce cache size to target size.
+
+        Call _p_deactivate() on cached objects until the cache size
+        falls under the target size.
         """
 
+    def onCloseCallback(f):
+        """Register a callable, f, to be called by close().
+
+        f will be called with no arguments before the Connection is closed.
+
+        Parameters:
+        f: method that will be called on `close`
+        """
+
+    def close():
+        """Close the Connection.
+
+        When the Connection is closed, all callbacks registered by
+        onCloseCallback() are invoked and the cache is garbage collected.
+
+        A closed Connection should not be used by client code.  It can't load
+        or store objects.  Objects in the cache are not freed, because
+        Connections are re-used and the cache is expected to be useful to the
+        next client.
+        """
+
+    def db():
+        """Returns a handle to the database this connection belongs to."""
+
+    def isReadOnly():
+        """Returns True if the storage for this connection is read only."""
+
+    def invalidate(tid, oids):
+        """Notify the Connection that transaction 'tid' invalidated oids.
+
+        When the next transaction boundary is reached, objects will be
+        invalidated.  If any of the invalidated objects are accessed by the
+        current transaction, the revision written before Connection.tid will be
+        used.
+
+        The DB calls this method, even when the Connection is closed.
+
+        Parameters:
+        tid: the storage-level id of the transaction that committed
+        oids: oids is a set of oids, represented as a dict with oids as keys.
+        """
+
+    def root():
+        """Return the database root object.
+
+        The root is a persistent.mapping.PersistentMapping.
+        """
+
+    def getVersion():
+        """Returns the version this connection is attached to."""
+
     # Multi-database support.
 
     connections = Attribute("""\
@@ -114,3 +321,32 @@ class IDatabase(Interface):
         entry.
         """)
 
+    def sync(self):
+        """Manually update the view on the database.
+
+        This includes aborting the current transaction, getting a fresh and
+        consistent view of the data (synchronizing with the storage if possible)
+        and call cacheGC() for this connection.
+        
+        This method was especially useful in ZODB 3.2 to better support
+        read-only connections that were affected by a couple of problems.  
+        """
+
+    # Debug information
+
+    def getDebugInfo():
+        """Returns a tuple with different items for debugging the connection. 
+
+        Debug information can be added to a connection by using setDebugInfo.
+        """
+
+    def setDebugInfo(*items):
+        """Add the given items to the debug information of this connection."""
+
+    def getTransferCounts(clear=False):
+        """Returns the number of objects loaded and stored.
+
+        If clear is True, reset the counters.
+        """
+
+

branches/pycon-multidb/src/persistent/interfaces.py

@@ -257,18 +257,35 @@ class IPersistentDataManager(Interface):
     def setstate(object):
         """Load the state for the given object.
 
-        The object should be in the ghost state.
-        The object's state will be set and the object will end up
-        in the saved state.
+        The object should be in the ghost state. The object's state will be
+        set and the object will end up in the saved state.
 
         The object must provide the IPersistent interface.
         """
 
+    def oldstate(obj, tid):
+        """Return copy of 'obj' that was written by transaction 'tid'.
+
+        The returned object does not have the typical metadata (_p_jar, _p_oid,
+        _p_serial) set. I'm not sure how references to other peristent objects
+        are handled.
+
+        Parameters
+        obj: a persistent object from this Connection.
+        tid: id of a transaction that wrote an earlier revision.
+
+        Raises KeyError if tid does not exist or if tid deleted a revision of 
+            obj. 
+        """
+
     def register(object):
         """Register an IPersistent with the current transaction.
 
         This method must be called when the object transitions to
         the changed state.
+
+        A subclass could override this method to customize the default
+        policy of one transaction manager for each thread.
         """
 
     def mtime(object):