[Zope3-checkins] CVS: Zope3/lib/python/Persistence - IPersistent.py:1.4

[Jim Fulton]

Update of /cvs-repository/Zope3/lib/python/Persistence
In directory cvs.zope.org:/tmp/cvs-serv27849

Modified Files:
	IPersistent.py 
Log Message:
Added a detailed description of the state model to the interface doc
string.


=== Zope3/lib/python/Persistence/IPersistent.py 1.3 => 1.4 ===
--- Zope3/lib/python/Persistence/IPersistent.py:1.3	Sun Jun 23 12:44:37 2002
+++ Zope3/lib/python/Persistence/IPersistent.py	Thu Oct  3 10:18:42 2002
@@ -21,10 +21,103 @@
 class IPersistent(Interface):
     """Python persistence interface
 
+    A persistent object can eb in one of several states:
+
+    - Unsaved
+
+      The object has been created but not saved in a data manager.
+
+      In this state, the _p_changed attribute is non-None and false
+      and the _p_jar attribute is None.
+
+    - Saved
+
+      The object has been saved and has not been changed since it was saved.
+
+      In this state, the _p_changed attribute is non-None and false
+      and the _p_jar attribute is set to a data manager.
+
+    - Sticky
+
+      This state is identical to the up-to-date state except that the
+      object cannot transition to the ghost state. This is a special
+      state used by C methods of persistent objects to make sure that
+      state is not unloaded in the middle of computation. 
+
+      In this state, the _p_changed attribute is non-None and false
+      and the _p_jar attribute is set to a data manager.
+
+      There is, currently, no official way to detect whether an object
+      is in the sticky state.
+
+    - Changed
+
+      The object has been changed.
+
+      In this state, the _p_changed attribute is true
+      and the _p_jar attribute is set to a data manager.
+
+    - Ghost
+
+      the object is in memory but it's state has not been loaded from
+      the database (or has been unloaded).  In this state, the object
+      doesn't contain any data.
+
+    The following state transactions are possible:
+
+    - Unsaved -> Saved
+
+      This transition occurs when an object is saved in the
+      database. This usually happens when an unsaved object is added
+      to (e.g. as an attribute ot item of) a saved (or changed) object
+      and the transaction is committed.
+
+    - Saved  -> Changed
+      Sticky -> Changed
+
+      This transition occurs when someone sets an attribute or sets
+      _p_changed to a true value on an up-to-date or sticky
+      object. When the transition occurs, the persistent object is
+      required to call the register method on it's data manager,
+      passing itself as the only argument.
+
+    - Saved -> Sticky
+
+      This transition occurs when C code marks the object as sticky to
+      prevent it's deactivation and transition to the ghost state.
+
+    - Saved -> Ghost
+
+      This transition occurs when an saved object is deactivated, by:
+      calling _p_deactivate, setting _p_changed to None, or deleting
+      _p_changed.
+
+    - Sticky -> Saved
+
+      This transition occurs when C code unmarks the object as sticky to
+      allow it's deactivation and transition to the ghost state.
+
+    - Changed -> Saved
+
+      This transition occurs when a transaction is committed.
+      The data manager affects the transaction by setting _p_changed
+      to a true value.
+
+    - Changed -> Ghost
+
+      This transition occurs when a transaction is aborted.
+      The data manager affects the transaction by deleting _p_changed.
+
+    - Ghost -> Saved
+
+      This transition occurs when an attribute or operation of a ghost
+      is accessed and the object's state is loaded from the database.
+
     Note that there is a separate C API that is not included here.
-    The C API requires a specific data layout and defines an
-    additional state, 'sticky' that is used to pevent object
-    deactivation while in C routines.
+    The C API requires a specific data layout and defines the sticky
+    state that is used to pevent object deactivation while in C
+    routines.
+
     """
 
     _p_jar=Attribute(
@@ -49,7 +142,7 @@
 
         None -- The object is a ghost. It is not active.
 
-        false -- The object is up to date (or has never been saved).
+        false -- The object is saved (or has never been saved).
 
         true -- The object has been modified.