[Zodb-checkins] CVS: StandaloneZODB/Doc - storage.tex:1.7
Fred L. Drake, Jr.
fdrake@acm.org
Tue, 29 Jan 2002 16:41:58 -0500
Update of /cvs-repository/StandaloneZODB/Doc
In directory cvs.zope.org:/tmp/cvs-serv11312
Modified Files:
storage.tex
Log Message:
Minor consistency nits fixed.
Added another request for clarification.
(Barry, Jeremy: search for "\note" to find everything that should be
checked and revised.)
=== StandaloneZODB/Doc/storage.tex 1.6 => 1.7 ===
Versions provide support for long-running transactions. They extend
-transaction semantics, such as atomicity and serializability to
+transaction semantics, such as atomicity and serializability, to
computation that involves many basic transactions, spread over long
periods of time, which may be minutes, or years.
-Versions were motivated by a common problem in web site management,
-but may be useful in other domains as well. Often, a web site must be
+Versions were motivated by a common problem in website management,
+but may be useful in other domains as well. Often, a website must be
changed in such a way that changes, which may require many operations
over a period of time, must not be visible until completed and
approved. Typically this problem is solved through the use of
-\dfn{staging servers}. Essentially, two copies of a web site are
+\dfn{staging servers}. Essentially, two copies of a website are
maintained. Work is performed on a staging server. When work is
completed, the entire site is copied from the staging server to the
production server. This process is too resource intensive and too
monolithic. It is not uncommon for separate unrelated changes to be
-made to a web site and these changes will need to be copied to the
+made to a website and these changes will need to be copied to the
production server independently. This requires an unreasonable amount
of coordination, or multiple staging servers.
ZODB addresses this problem through long-running transactions, called
-\dfn{versions}. Changes made to a Web site can be made to a version
-(of the Web site). The author sees the version of the site that
+\dfn{versions}. Changes made to a website can be made to a version
+(of the website). The author sees the version of the site that
reflects the changes, but people working outside of the version cannot
see the changes. When the changes are completed and approved, they
can be saved, making them visible to others, almost instantaneously.
@@ -72,10 +72,8 @@
The various exceptions that can be raised.
-\begin{classdesc*}{Storage}{}
- An object that implements the storage interface must support the
- following methods.
-\end{classdesc*}
+An object that implements the \class{Storage} interface must support
+the following methods:
\begin{methoddesc}{tpc_begin}{transaction\optional{, tid\optional{,
status}}}
@@ -88,7 +86,7 @@
block and returns immediately without any effect.
The optional \var{tid} argument specifies the timestamp to be used
- for the transaction id and the new object serial numbers. If it is
+ for the transaction ID and the new object serial numbers. If it is
not specified, the implementation chooses the timestamp.
The optional \var{status} argument, which has a default value of
@@ -96,10 +94,10 @@
\end{methoddesc}
\begin{methoddesc}{store}{oid, serial, data, version, transaction}
- Store \var{data}, a Python pickle, for the object id, \var{oid}. A
- Storage need not and often will not write data immediately. If data
- are written, then the storage should be prepared to undo the write
- if a transaction is aborted.
+ Store \var{data}, a Python pickle, for the object ID identified by
+ \var{oid}. A Storage need not and often will not write data
+ immediately. If data are written, then the storage should be
+ prepared to undo the write if a transaction is aborted.
The value of \var{serial} is opaque; it should be the value returned
by the \method{load()} call that read the object. \var{version} is
@@ -117,11 +115,14 @@
\item \code{None}, indicating the data has not been stored yet
\item a string, containing the new serial number for the
object
- \item a sequence of oid, serial number pairs, containing the
+ \item a sequence of object ID, serial number pairs, containing the
new serial numbers for objects updated by earlier
\method{store()} calls that are part of this transaction.
If the serial number is not a string, it is an exception
object that should be raised by the caller.
+ \note{This explanation is confusing; how to tell the
+ sequence of pairs from the exception? Barry, Jeremy, please
+ clarify here.}
\end{itemize}
Several different exceptions can be raised when an error occurs.
@@ -191,7 +192,8 @@
If undo is not supported, then version data may be simply
discarded. If undo is supported, however, then the
\method{abortVersion()} operation must be undoable, which implies
- that version data must be retained.
+ that version data must be retained. Use the \method{supportsUndo()}
+ method to determine if the storage supports the undo operation.
\end{methoddesc}
\begin{methoddesc}{commitVersion}{source, destination, transaction}
@@ -208,7 +210,9 @@
If the storage doesn't support undo, then the old version data may
be discarded. If undo is supported, then this operation must be
- undoable and old transaction data may not be discarded.
+ undoable and old transaction data may not be discarded. Use the
+ \method{supportsUndo()} method to determine if the storage supports
+ the undo operation.
\end{methoddesc}
\begin{methoddesc}{close}{}