[Zope-CVS] CVS: Products/Transience/help - Transience-change.stx:1.3 Transience.stx:1.4 Transience-export.stx:NONE
Chris McDonough
chrism@zope.com
Wed, 7 Nov 2001 01:46:37 -0500
Update of /cvs-repository/Products/Transience/help
In directory cvs.zope.org:/tmp/cvs-serv27930/help
Modified Files:
Transience-change.stx Transience.stx
Removed Files:
Transience-export.stx
Log Message:
- Permission name changes.
- Removed advanced (import/export) view - superfluous.
- new() and new_or_existing() methods now accept a wrap_with argument.
If wrap_with is non-None, the data object returned will be wrapped
in (via __of__) with the object passed into the wrap_with argument.
This will facilitate the wrapping of data objects in the calling
session data manager object.
- Transient objects no longer keep a reference to their container.
Instead, containers use the isValid method of objects to determine
whether an object is valid. An object no longer deletes itself from
its container and relies solely on this mechanism.
- Callback handling now logs on failure.
- Various deletions of commented material.
- getToken of data objects returns the key with which they were entered
into their container, while getId returns a uniform unique id. getName
is now aliased to getId.
- data objects now no longer aq-unwrap things stored in them. This
is a security change.
- repr method of data object now returns simpler structure.
- removed stx workarounds from interfaces file (we should just fix the
help system instead of doing stuff like _, etc.)
- extended some descriptions of interfaces.
- extended and edited other docs.
TODO:
- fix tests to run under testrunner.
- "ring" must change to become more conflict resistant.
(new data structure and algorithm needs to be put in)
- need new icon for data container.
- need out of memory protection in container.
=== Products/Transience/help/Transience-change.stx 1.2 => 1.3 ===
+TransientObjectContainer - Manage
Transient Object Containers
A TransientObjectContainer contains objects which will expire after
a given period of time. A TransientObjectContainer is used by
- SessionDataMangers to store session information.
+ a SessionDataManager to store session data.
To change a TransientObjectContainer, specify the following:
- - *title*
+ - **Title**
- The title of the object.
+ The title of the object (optional).
- - **timeout_minutes**
+ - **Data object timeout in minutes**
The minimum number of minutes that objects in the container will
persist for. Objects in the container are passively deleted, so
@@ -21,29 +21,38 @@
If you change the timeout value, all objects in the transient
container will be flushed.
- - *addNotification*
+ The default is 20 minutes.
- The name of an object to receive notifications when objects are
- added to the TransientObjectContainer. See NotificationTargets.
+ - **Add Notification Target**
- - *delNotification*
+ The physical path of a script which will receive notifications when
+ objects are added to the TransientObjectContainer. See
+ NotificationTargets below. Ex: '/path/to/addNotificationMethod'.
- The name of an object to receive notifications when objects are
- deleted from the TransientObjectContainer. See NotificationTargets.
+ - **Delete Notification Target**
+ The physical path of a script which will receive notifications when
+ objects are deleted from the TransientObjectContainer. See
+ NotificationTargets below. Ex: 'path/to/delNotificationMethod'.
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.
-
+ A NotificationTarget is a string representing a physical path to a
+ Zope Script (Python Script or External Method) object which is
+ called when an object is added or removed from a
+ TransientObjectContainer.
+
+ Notification targets 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.
+
+ An example of a notification target External Method::
+
+ def notificationTarget(item, container):
+ from zLOG import LOG
+ LOG(100, 'test', 'id: %s' % item.getId())
See Also
=== Products/Transience/help/Transience.stx 1.3 => 1.4 ===
+Transient Objects
- 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
- 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.
-
- Using Transient Objects
+ A transient object is an object which persists for a limited
+ period of time after which it is automatically expired. The
+ objects which make this behavior possible are
+ TransientObjectContainers and TransientObjects.
+
+ Transient Object Container Overview
+
+ To facilitate persistence of items for a limited duration, a
+ TransientObjectContainer is a container which stores and maintains
+ an expiration policy related to TransientObjects.
+
+ A TransientObjectContainer flushes expired entries based on a
+ timeout based on last access of a contained key. It also has a
+ notification mechanism whereby it can notify a script or method
+ that an object has been added or removed from the container. When
+ a new item is created, the add notification target on the
+ container is called. Similarly, when the item is deleted, either
+ explicitly or by timeout, the delete notification target is
+ called.
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.
- 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.
-
- 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.
-
- For example, consider the following python script::
-
- # Create a transientObject
- t = container.transient_container.new_or_existing('Foobar')
-
- # Create a dictionary
- d = {}
+ A Transient Object is considered "expired" by a
+ TransientObjectContainer when it has not been accessed in a
+ configurable number of minutes (the "data object timeout").
- # Store the dictionary in the transientObject
- t['d'] = d
-
- And a similar python script::
-
- # Retrieve our transientObject
- t = container.transient_container.new_or_existing('Foobar')
-
- # Retreive the dictionary
- d = t['d']
-
- # Update the dictionary
- d[1] = 1
-
- 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.
+ Using Transient Objects
+ TransientObjects are themselves "containerish" and
+ "dictionary-like"; they implement a dictionary-like interface as
+ well as methods related to manual invalidation, timeout, and
+ introspection.
+
+ The values of a transient object can be any pickleable Python data
+ structure while the keys of a transient object may be any hashable
+ and pickleable Python data structure.
+
+ Note that TransientObjects do not offer the contract of "normal"
+ ZODB container objects; mutations made to items which are
+ contained within a TransientObject cannot be expected to persist.
+ Developers need explicitly resave the state of a subobject of a
+ TransientObject by placing it back into the TransientObject via
+ the TransientObject.__setitem__ or .set methods. This requirement
+ is due to the desire to allow people to create alternate
+ TransientObject implementations that are *not* based on the ZODB.
+ Practically, this means that when working with a TransientObject
+ which contains mutable subobjects (even if they inherit from
+ Persistence.Persistent), you *must* resave them back into the
+ TransientObject. For example::
+
+ class Foo(Persistence.Persistent):
+ pass
+
+ transient_object = transient_data_container.new('t')
+ foo = transient_object['foo'] = Foo()
+ foo.bar = 1
+ # the following is *necessary* to repersist the data
+ transient_object['foo'] = foo
See Also
=== Removed File Products/Transience/help/Transience-export.stx ===