[top] / ZODB / interfaces / IConnection
Connection to ZODB for loading and storing objects.
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=False 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.
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
connections
(Attribute)
A mapping from database name to a Connection to that database.
In multi-database use, the Connections of all members of a database collection share the same .connections object.
In single-database use, of course this mapping contains a single entry.
* = required
getDebugInfo()
Returns a tuple with different items for debugging the connection.
Debug information can be added to a connection by using setDebugInfo.
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.
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.
getTransferCounts(clear=False)
Returns the number of objects loaded and stored.
If clear is True, reset the counters.
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
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.
isReadOnly()
Returns True if the storage for this connection is read only.
db()
Returns a handle to the database this connection belongs to.
sync()
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 calling 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.
setDebugInfo(*items)
Add the given items to the debug information of this connection.
add(ob)
Add a new object obj
to the database and assign it an oid.
A persistent object is normally added to the database and assigned an oid when it becomes reachable to an object already in the database. In some cases, it is useful to create a new object and use its oid (_p_oid) in a single transaction.
This method assigns a new oid regardless of whether the object is reachable.
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.
cacheGC()
Reduce cache size to target size.
Call _p_deactivate() on cached objects until the cache size falls under the target size.
invalidateCache()
Invalidate the connection cache
This invalidates all objects in the cache. If the connection is open, subsequent reads will fail until a new transaction begins or until the connection os reopned.
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.
get_connection(database_name)
Return a Connection for the named database.
This is intended to be called from an open Connection associated with a multi-database. In that case, database_name must be the name of a database within the database collection (probably the name of a different database than is associated with the calling Connection instance, but it's fine to use the name of the calling Connection object's database). A Connection for the named database is returned. If no connection to that database is already open, a new Connection is opened. So long as the multi-database remains open, passing the same name to get_connection() multiple times returns the same Connection object each time.
getVersion()
Returns the version this connection is attached to.
root()
Return the database root object.
The root is a persistent.mapping.PersistentMapping.
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`
There are no specific adapters registered for this interface.
There are no extended adapters registered for this interface.
zope.viewlet.metaconfigure.JavaScriptViewlet
(name: boston.js)
zope.viewlet.manager.<ViewletManager providing IJavaScript>
(name: zope.app.boston.IJavaScript)
zope.viewlet.viewlet.SimpleViewletClass from /opt/zope/sr/apidoc/src/zope/app/boston/viewlets/toolbar/viewlet.pt
(name: toolbar)
zope.traversing.namespace.lang
(name: lang)
zope.viewlet.manager.<ViewletManager providing ICSS>
(name: zope.app.boston.ICSS)
zope.traversing.namespace.acquire
(name: acquire)
zope.traversing.namespace.acquire
(name: acquire)
zope.traversing.namespace.acquire
(name: acquire)
zope.traversing.namespace.acquire
(name: acquire)
zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace
(name: annotations)
zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace
(name: annotations)
zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace
(name: annotations)
zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace
(name: annotations)
zope.viewlet.metaconfigure.CSSViewlet
(name: xmltree.css)
zope.app.pagetemplate.urlquote.URLQuote
(name: url)
zope.viewlet.viewlet.SimpleViewletClass from /opt/zope/sr/apidoc/src/zope/app/boston/viewlets/xmltree/xmltree.pt
(name: xmltree)
zope.viewlet.metaconfigure.CSSViewlet
(name: skin.css)
zope.app.preference.preference.preferencesNamespace
(name: preferences)
zope.app.preference.default.DefaultPreferences
(name: preferences)
zope.traversing.namespace.attr
(name: attribute)
zope.traversing.namespace.attr
(name: attribute)
zope.traversing.namespace.attr
(name: attribute)
zope.traversing.namespace.attr
(name: attribute)
zope.viewlet.manager.<ViewletManager providing IHead>
(name: zope.app.boston.IHead)
zope.app.component.back35.RegistrationManagerNamespace
(name: registrations)
zope.viewlet.manager.<ViewletManager providing ILeft>
(name: zope.app.boston.ILeft)
zope.traversing.namespace.resource
(name: resource)
zope.traversing.namespace.resource
(name: resource)
zope.traversing.namespace.resource
(name: resource)
zope.traversing.namespace.resource
(name: resource)
zope.traversing.namespace.etc
(name: etc)
zope.traversing.namespace.etc
(name: etc)
zope.traversing.namespace.etc
(name: etc)
zope.traversing.namespace.etc
(name: etc)
zope.traversing.namespace.etc
(name: etc)
zope.app.apidoc.apidoc.apidocNamespace
(name: apidoc)
zope.app.apidoc.apidoc.apidocNamespace
(name: apidoc)
zope.app.apidoc.apidoc.apidocNamespace
(name: apidoc)
zope.app.apidoc.apidoc.apidocNamespace
(name: apidoc)
zope.traversing.namespace.acquire
(name: acquire)
zope.traversing.namespace.lang
(name: lang)
zope.traversing.namespace.lang
(name: lang)
zope.traversing.namespace.lang
(name: lang)
zope.traversing.namespace.lang
(name: lang)
zope.traversing.namespace.item
(name: item)
zope.traversing.namespace.item
(name: item)
zope.traversing.namespace.item
(name: item)
zope.traversing.namespace.item
(name: item)
zope.traversing.namespace.item
(name: item)
zope.viewlet.metaconfigure.JavaScriptViewlet
(name: xmltree)
zope.viewlet.metaconfigure.CSSViewlet
(name: toolbar-css)
zope.traversing.namespace.adapter
(name: adapter)
zope.app.apidoc.apidoc.apidocNamespace
(name: apidoc)
zope.traversing.namespace.vh
(name: vh)
zope.traversing.namespace.vh
(name: vh)
zope.traversing.namespace.vh
(name: vh)
zope.traversing.namespace.vh
(name: vh)
zope.app.onlinehelp.helpNamespace
(name: help)
zope.app.onlinehelp.helpNamespace
(name: help)
zope.app.onlinehelp.helpNamespace
(name: help)
zope.app.onlinehelp.helpNamespace
(name: help)
zope.app.onlinehelp.helpNamespace
(name: help)
zope.traversing.namespace.adapter
(name: adapter)
zope.traversing.namespace.adapter
(name: adapter)
zope.traversing.namespace.adapter
(name: adapter)
zope.traversing.namespace.adapter
(name: adapter)
zope.traversing.namespace.debug
(name: debug)
zope.traversing.namespace.debug
(name: debug)
zope.traversing.namespace.debug
(name: debug)
zope.traversing.namespace.debug
(name: debug)
zope.app.pagetemplate.talesapi.ZopeTalesAPI
(name: zope)
zope.traversing.namespace.attr
(name: attribute)
zope.app.preference.preference.preferencesNamespace
(name: preferences)
zope.app.preference.preference.preferencesNamespace
(name: preferences)
zope.app.preference.preference.preferencesNamespace
(name: preferences)
zope.app.preference.preference.preferencesNamespace
(name: preferences)
zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace
(name: annotations)
zope.traversing.namespace.view
(name: view)
zope.traversing.namespace.view
(name: view)
zope.traversing.namespace.view
(name: view)
zope.traversing.namespace.view
(name: view)
zope.formlib.namedtemplate.NamedTemplatePathAdapter
(name: template)
zope.viewlet.manager.<ViewletManager providing IToolBar>
(name: zope.app.boston.IToolBar)
zope.viewlet.metaconfigure.CSSViewlet
(name: widget.css)
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.
There are no views available.