[Zope-CVS] CVS: Products/Transience/help - TransienceInterfaces.py:1.1 Transience.stx:1.3

Matthew T. Kromer matt@zope.com
Fri, 2 Nov 2001 15:44:23 -0500


Update of /cvs-repository/Products/Transience/help
In directory cvs.zope.org:/tmp/cvs-serv12259/help

Modified Files:
	Transience.stx 
Added Files:
	TransienceInterfaces.py 
Log Message:
Updated Transience documentation


=== Added File Products/Transience/help/TransienceInterfaces.py ===
"""
Transient Objects

  TransientObjectContainers implement:

    - ItemWithId

    - StringKeyedHomogenousItemContainer

    - TransientItemContainer

  In particular, one uses the 'new_ _or_ _existing' method on
  TransientObjectContainers to retrieve or create a TransientObject based
  on a given string key.  

  If add or delete notifications are registered with the container, they
  will be called back when items in the container are added or deleted,
  with the item and the container as arguments.  The callbacks may be
  registered either as bound methods, functions, or named paths in Zope.

  TransientObjects implement:

    - ItemWithId

    - Transient

    - DictionaryLike

    - TTWDictionary

    - ImmutablyValuedMappingOfPickleableObjects

"""

import Interface

class Transient(Interface.Base):
    def invalidate(self):
        """
        Invalidate (expire) the transient object.

        Causes the transient object container's "before destruct" method
        related to this object to be called as a side effect.
        """

    def getLastAccessed(self):
        """
        Return the time the transient object was last accessed in
        integer seconds-since-the-epoch form.
        """

    def setLastAccessed(self):
        """
        Cause the last accessed time to be set to now.
        """

    def getCreated(self):
        """
        Return the time the transient object was created in integer
        seconds-since-the-epoch form.
        """

class DictionaryLike(Interface.Base):
    def keys(self):
        """
        Return sequence of key elements.
        """

    def values(self):
        """
        Return sequence of value elements.
        """

    def items(self):
        """
        Return sequence of (key, value) elements.
        """

    def get(self, k, default='marker'):
        """
        Return value associated with key k.  If k does not exist and default
        is not marker, return default, else raise KeyError.
        """

    def has_key(self, k):
        """
        Return true if item referenced by key k exists.
        """

    def clear(self):
        """
        Remove all key/value pairs.
        """

    def update(self, d):
        """
        Merge dictionary d into ourselves.
        """

    # DictionaryLike does NOT support copy()

class ItemWithId(Interface.Base):
    def getId(self):
        """
        Returns a meaningful unique id for the object.
        """

class TTWDictionary(DictionaryLike, ItemWithId):
    def set(self, k, v):
        """
        Call _  _setitem_  _ with key k, value v.
        """

    def delete(self, k):
        """
        Call _  _delitem_  _ with key k.
        """

    def __guarded_setitem__(self, k, v):
        """
        Call _  _setitem_  _ with key k, value v.
        """

class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
    def __setitem__(self, k, v):
        """
        Sets key k to value v, if k is both hashable and pickleable and
        v is pickleable, else raise TypeError.
        """

    def __getitem__(self, k):
        """
        Returns the value associated with key k.

        Note that no guarantee is made to persist changes made to mutable
        objects obtained via _  _getitem_  _, even if
        they support the ZODB Persistence interface.  In order to ensure
        that changes to mutable values are persisted, you need to explicitly
        put the value back in to the mapping via the
        _  _setitem_  _.
        """

    def __delitem__(self, k):
        """
        Remove the key/value pair related to key k.
        """

class HomogeneousItemContainer(Interface.Base):
    """
    An object which:
     1.  Contains zero or more subobjects, all of the same type.
     2.  Is responsible for the creation of its subobjects.
     3.  Allows for the access of a subobject by key.
    """
    def getSubobjectInterface(self):
        """
        Returns the interface object which must be supported by items added
        to or created by this container.
        """

    def get(self, k, default=None):
        """
        Return value associated with key k.  If value associated with k does
        not exist, return default.
        """

    def has_key(self, k):
        """
        Return true if container has value associated with key k, else
        return false.
        """

    def delete(self, k):
        """
        Delete value associated with key k, raise a KeyError if nonexistent.
        """

class StringKeyedHomogeneousItemContainer(HomogeneousItemContainer):
    def new(self, k):
        """
        Creates a new subobject of the type supported by this container
        with key "k" and returns it.

        If an object already exists in the container with key "k", a
        KeyError is raised.

        "k" must be a string, else a TypeError is raised.
        """

    def new_or_existing(self, k):
        """
        If an object already exists in the container with key "k", it
        is returned.

        Otherwiser, create a new subobject of the type supported by this
        container with key "k" and return it.

        "k" must be a string, else a TypeError is raised.
        """
    
class TransientItemContainer(Interface.Base):
    def setTimeoutMinutes(self, timeout_mins):
        """
        Set the number of minutes of inactivity allowable for subobjects
        before they expire.
        """

    def getTimeoutMinutes(self):
        """
        Return the number of minutes allowed for subobject inactivity
        before expiration.
        """

    def getAddNotificationTarget(self):
        """
        Returns the current 'after add' function, or None.
        """

    def setAddNotificationTarget(self, f):
        """
        Cause the 'after add' function to be 'f'.

        If 'f' is not callable and is a string, treat it as a Zope path to
        a callable function.

        'after add' functions need accept a single argument: 'item', which
        is the item being added to the container.
        """

    def getDelNotificationTarget(self):
        """
        Returns the current 'before destruction' function, or None.
        """

    def setDelNotificationTarget(self, f):
        """
        Cause the 'before destruction' function to be 'f'.

        If 'f' is not callable and is a string, treat it as a Zope path to
        a callable function.

        'before destruction' functions need accept a single argument: 'item',
        which is the item being destroyed.
        """


=== Products/Transience/help/Transience.stx 1.2 => 1.3 ===
-
-  This is the documentation to the Transience product.
+Transient Object Containers
 
   Transient Object Overview
 
     A transient object persists, but for a limited period of time.
     To facilitate persistence of items for a limited duration, the
     TransientObjectContainer provides a container which stores
-    TransientObjects.  A TransientObject is dictionary-like; it 
-    accepts string keys only.  The TransientObjectContainer 
+    TransientObjects.  A TransientObject is dictionary like; it 
+    will respond to dictionary semantics.  The TransientObjectContainer 
     maintains a time-out mechanism to flush out expired entries.
     The container also has a notification mechanism whereby it can
     notify a script or method that an object has been added or removed
     from the container.
 
-  Adding a TransientObjectContainer
-
-    id
-
-      The ID of the TransientObjectContainer is the container's name.
-
-    title (optional)
-
-      The title of the object.
-
-    timeout_minutes
-
-      The minimum number of minutes that objects in the container will
-      persist for.  Objects in the container are passively deleted, so
-      they may not be deleted exactly after timeout_minutes elapses.
-
-    addNotification (optional)
-
-      The name of an object to receive notifications when objects are
-      added to the TransientObjectContainer.  See NotificationTargets.
-
-    delNotification (optional)
-
-      The name of an object to receive notifications when objects are
-      deleted from the TransientObjectContainer.  See NotificationTargets.
-  
-  Implementation
-
-   TransientObjectContainer
-
-    Interfaces:
-
-      - ItemWithId
-
-      - StringKeyedHomogenousItemContainer
-
-      - TransientItemContainer
-
-    Constructors
-
-      manage_addTransientObjectContainer(id, title="", timeoutMinutes=20,
-		addNotification=None, delNotification=None)
-	
-	Creates a TransientObjectContainer with the given id and title, which
-	will contain objects for at least timeout_minutes.  If addNotification
-	or delNotification are provided, they are callables (either bound
-	methods, functions, or names of objects in Zope).
-
-    Interface ItemWithID
-
-      getId()
-
-	Returns the ID of the TransientObjectContainer.
-
-    Interface StringKeyedHomogenousItemContainer
-
-      new(name)
-
-        Creates a new TransientObject in the container with the specified
-	name.  Will raise a KeyError if the name already exists in the
-	container.  Returns the TransientObject.
-
-      new_ _or_ _existing(name)
-
-        Returns a TransientObject from the container with the given name,
-	creating it if it does not exist.
-
-    Interface TransientItemContainer
-
-      setTimeoutMinutes(timeoutMinutes)
-
-        Sets the timeout of all objects in the container to timeoutMinutes.
-	If this time is not the same as the prior timeoutMinutes, all items
-	in the container are flushed.
-
-      getTimeoutMinutes(timeoutMinutes)
-
-        Returns the number of minutes after which objects in the container
-	will expire.
-
-      getAddNotificationTarget()
-
-        Returns the notification target to be informed when new objects
-	are added to the container.  The result may be a string, which
-	indicates a path to an object in Zope, or may be a function or
-	bound method.
-
-      setAddNotificationTarget(target)
-
-        Sets the notification target to be informed when new objects are
-	added to the container.  The target may be a string, which indicates
-	a path to an object in Zope, or may be a function or bound method.
-	See NotifcationTargets for more information.
-      
-      getDelNotificationTarget()
-
-        Returns the notification target to be informed when objects
-	are deleted from the container.  The result may be a string, which
-	indicates a path to an object in Zope, or may be a function or
-	bound method.
-
-      setDelNotificationTarget(target)
-
-        Sets the notification target to be informed when objects are
-	delted from the container.  The target may be a string, which indicates
-	a path to an object in Zope, or may be a function or bound method.
-	See NotifcationTargets for more information.
-
-   Notification Targets
-
-   	A NotificationTarget is a callable (a bound method, function, or
-	named Zope object) which is called when an object is added or removed
-	from a TransientObjectContainer. 
-
-	NotificationTargets are called with two arguments, the first being
-	the item being added or removed from the container, and the second
-	being the container itself.  Within Zope, the container will be
-	acquisition wrapped, allowing the container to be used as a context
-	to reference other Zope objects.
-
-   TransientObject
-
-    Interfaces:
-
-      - ItemWithId
-
-      - Transient
-
-      - DictionaryLike
-
-      - TTWDictionary
-
-      - ImmutablyValuedMappingOfPickleableObjects
-
-    Constructors
-
-      Transient Objects are constructed by their TransientObjectContainer's
-      new or new_or_existing methods.
-
-
-    Interface ItemWithID
-
-      getId()
-
-      	Returns the ID of the TransientObject.
-
-    Interface Transient
-
-      invalidate()
-
-      	Marks the object as being invalidated -- this causes the parent to
-	call the delete notification for the object.
-
-      getLastAccessed()
-
-        Returns a last accessed timestamp.
-
-      setLastAccessed()
-
-        Updates the object's last accessed timestamp, subject to a timer
-	granularity (currently 30 seconds).  Thus, multiple rapid calls to
-	setLastAccessed() will only update the timestamp once.
-
-      getCreated()
-
-        Returns the object's creation timestamp.  This timestamp is set
-	when the object is created in its container.
-
-    Interface DictionaryLike
-
-      keys()
-
-      	Returns a list of keys in the object.
-
-      values()
-
-        Returns a list of values in the object.
-
-      items()
-
-        Returns a list of (key, value) pairs for all keys in the object.
-
-      get(key, default=None)
-
-        Returns the value corresponding to the given key.  If the key does
-	not exist, and a default is specified, the default is returned,
-	otherwise a KeyError will be raised.
-
-      has_key(key)
-
-        Tests to see if the given key exists in the TransientObject. If the
-	key exists, a 1 will be returned, otherwise a 0 will be returned.
-
-      clear()
+  Using Transient Objects
 
-        Removes all values from the TransientObject.
+    One uses the 'new_or_existing' or 'new' methods of a
+    TransientObjectContainer to obtain a TransientObject.  The
+    TransientObjectContainer only accepts string keys to name objects;
+    you may not use objects as keys.
 
-      update(dict)
+    When a new item is created, the add notification target on the
+    container is notified about the object via a callback.  Similarly,
+    when the item is deleted, either explicitly or by timeout, the
+    delete notification target is called back.
 
-        Updates the TransientObject from the dictionary provided, copying
-	keys and values from the dictionary into the TransientObject.
+    TransientObjects, since they behave as a dictionary, may contain
+    any arbitrarily keyed data.  However, the TransientObject cannot inspect
+    the contents of what it stores to determine if it has been changed,
+    thus, it is important to explicitly set data on the TransientObject
+    itself in the event some nested data has changed and requires saving.
 
-    Interface TTWDictionary
+    For example, consider the following python script::
 
-      set(key, value)
+       # Create a transientObject
+       t = container.transient_container.new_or_existing('Foobar')
 
-      	Sets the value for a specific key in the TransientObject.
+       # Create a dictionary
+       d = {}
 
-      delete(key)
+       # Store the dictionary in the transientObject
+       t['d'] = d
 
-        Removes a key/value pair from the TransientObject.
+    And a similar python script::
 
-    Interface ImmutablyValuedMappingOfPickleableObjects
+       # Retrieve our transientObject
+       t = container.transient_container.new_or_existing('Foobar')
 
-      _  _setitem_  _(key, value)
+       # Retreive the dictionary
+       d = t['d']
 
-        Sets the value for a specific key in the TransientObject.  If
-	the key or value is acquisition wrapped, it is unwrapped prior
-	to storage.
+       # Update the dictionary
+       d[1] = 1
 
-      _  _getitem_  _(key)
+    In this second example, the contents of the transientObject will not
+    be saved, because the transientObject itself was not modified.  It
+    is important to update the object to signal it that it must save its
+    state.
 
-        Retrieves the value for the given key in the TransientObject.
 
-      _  _delitem_  _(key)
+  See Also
 
-        Deletes the given key from the TransientObject.
+     - "Transient Object API":TransienceInterfaces.py