[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}{}