[Zodb-checkins] CVS: StandaloneZODB/Doc - storage.tex:1.6

[Fred L. Drake, Jr.]

Update of /cvs-repository/StandaloneZODB/Doc
In directory cvs.zope.org:/tmp/cvs-serv6969

Modified Files:
	storage.tex 
Log Message:
Extract more information from the Object Domain model.

=== StandaloneZODB/Doc/storage.tex 1.5 => 1.6 ===
 
 
+\section{Concepts}
+
+\subsection{Versions}
+
+Versions provide support for long-running transactions.  They extend
+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
+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
+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
+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
+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.
+
+Versions require support from storage managers. Version support is an
+optional feature of storage managers and support in a particular
+database will depend on support in the underlying storage manager.
+
+
 \section{Storage Interface}
 
 General issues:
@@ -35,8 +70,6 @@
 
 Concurrency and transactions.
 
-Versions.
-
 The various exceptions that can be raised.
 
 \begin{classdesc*}{Storage}{}
@@ -196,7 +229,14 @@
   \note{This is not defined for \class{ZODB.BaseStorage}.}
 \end{methoddesc}
 
+\begin{methoddesc}{getName}{}
+  Returns the name of the store.  The format and interpretation of
+  this name is storage dependent.  It could be a file name, a database
+  name, etc.
+\end{methoddesc}
+
 \begin{methoddesc}{getSize}{}
+  An approximate size of the database, in bytes.
 \end{methoddesc}
 
 \begin{methoddesc}{getSerial}{oid}
@@ -205,6 +245,8 @@
 \end{methoddesc}
 
 \begin{methoddesc}{load}{oid, version}
+  Returns the pickle data and serial number for the object identified
+  by \var{oid} in the version \var{version}.
 \end{methoddesc}
 
 \begin{methoddesc}{loadSerial}{oid, serial}
@@ -213,6 +255,9 @@
 \end{methoddesc}
 
 \begin{methoddesc}{modifiedInVersion}{oid}
+  Returns the version that the object with identifier \var{oid} was
+  modified in, or an empty string if the object was not modified in a
+  version.
 \end{methoddesc}
 
 \begin{methoddesc}{isReadOnly}{}
@@ -242,9 +287,26 @@
 \end{methoddesc}
 
 \begin{methoddesc}{undo}{transaction_id}
-\end{methoddesc}
-
-\begin{methoddesc}{undoLog}{first, last\optional{, filter}}
+   Undo the transaction corresponding to the transaction ID given by
+   \var{transaction_id}.  If the transaction cannot be undone, then
+   \exception{UndoError} is raised.  On success, returns a sequence of
+   object IDs that were affected.
+\end{methoddesc}
+
+\begin{methoddesc}{undoLog}{\optional{first\optional{,
+                            last\optional{, filter}}}}
+  Returns a sequence of \class{TransactionDescription} objects for
+  undoable transactions.  \var{first} gives the index of the first
+  transaction to be retured, with \code{0} (the default) being the
+  most recent.
+
+  \note{\var{last} is confusing; can Barry or Jeremy try to explain
+  this?}
+
+  If \var{filter} is provided and not \code{None}, it must be a
+  function which accepts a \class{TransactionDescription} object as a
+  parameter and returns true if the entry should be reported.  If
+  omitted or \code{None}, all entries are reported.
 \end{methoddesc}
 
 \begin{methoddesc}{versionEmpty}{version}
@@ -259,6 +321,17 @@
 
 \begin{methoddesc}{history}{oid\optional{, version\optional{,
                             size\optional{, filter}}}}
+  Return a sequence of \class{HistoryEntry} objects.  The information
+  provides a log of the changes made to the object.  Data are reported
+  in reverse chronological order.  If \var{version} is given, history
+  information is given with respect to the specified version, or only
+  the non-versioned changes if the empty string is given.  By default,
+  all changes are reported.  The number of history entries reported is
+  constrained by \var{size}, which defaults to \code{1}.  If
+  \var{filter} is provided and not \code{None}, it must be a function
+  which accepts a \class{HistoryEntry} object as a parameter and
+  returns true if the entry should be reported.  If omitted or
+  \code{None}, all entries are reported.
 \end{methoddesc}
 
 \begin{methoddesc}{pack}{t, referencesf}
@@ -288,11 +361,33 @@
   \note{This is not defined for \class{ZODB.BaseStorage}.}
 \end{methoddesc}
 
+\begin{methoddesc}{registerDB}{db, limit}
+  Register a database \var{db} for distributed storage invalidation
+  messages.  The maximum number of objects to invalidate is given by
+  \var{limit}.  If more objects need to be invalidated than this
+  limit, then all objects are invalidated.  This argument may be
+  \code{None}, in which case no limit is set.  Non-distributed
+  storages should treat this is a null operation.  Storages should
+  work correctly even if this method is not called.
+\end{methoddesc}
+
 
 \section{ZODB.BaseStorage Implementation}
 
 \section{Notes for Storage Implementors}
 
+
 \section{Distributed Storage Interface}
+
+Distributed storages support use with multiple application processes.
+
+Distributed storages have a storage instance per application and some
+sort of central storage server that manages data on behalf of the
+individual storage instances.
+
+When a process changes an object, the object must be invaidated in all
+other processes using the storage.  The central storage sends a
+notification message to the other storage instances, which, in turn,
+send invalidation messages to their respective databases.
 
 \end{document}