Skip to content

Z
Zope
Commit d929af72 authored by matt@zope.com's avatar matt@zope.com
Browse files
Options

Updated Transience documentation

parent f8719ed3
Hide whitespace changes
Inline Side-by-side
Showing with 345 additions and 234 deletions
lib/python/Products/Transience/Transience.py
View file @ d929af72
......@@ -85,10 +85,10 @@
"""
Core session tracking SessionData class.
$Id: Transience.py,v 1.7 2001/10/23 20:29:27 matt Exp $
$Id: Transience.py,v 1.8 2001/11/02 20:44:22 matt Exp $
"""
__version__='$Revision: 1.7 $'[11:-2]
__version__='$Revision: 1.8 $'[11:-2]
import Globals
from Globals import HTMLFile, MessageDialog
......@@ -103,6 +103,8 @@ from BTrees import OOBTree
import os.path
import math
import time
import sys
import random
_notfound = []
_marker = []
......@@ -605,7 +607,8 @@ class TransientObject(Persistent, Implicit):
#
def __init__(self, id, parent=None):
self.id = id
self.name = id
self.id = self._generateUniqueId()
self._parent = parent
self._container = {}
self._created = self._last_accessed = time()
......@@ -723,7 +726,19 @@ class TransientObject(Persistent, Implicit):
# other objects (eliminates read conflicts).
return 1
getName = getId
def getName(self):
return self.name
def _generateUniqueId(self):
return str(time())+str(random.randint(0,sys.maxint-1))
def __str__(self):
result = "<table>\n"
for (key, value) in self.items():
result = result + "<tr><th>%s</th><td>%s</td></tr>\n" % (key, value)
result= result + "</table>"
return result
Globals.InitializeClass(TransientObjectContainer)
Globals.InitializeClass(TransientObject)
lib/python/Products/Transience/TransienceInterfaces.py
View file @ d929af72
"""
Transient object and transient object container interfaces.
Transient Objects
TransientObjectContainers implement:
- ItemWithId
- StringKeyedHomogenousItemContainer
- TransientItemContainer
In particular, one uses the 'new_&nbsp;_or_&nbsp;_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
......@@ -78,17 +108,17 @@ class ItemWithId(Interface.Base):
class TTWDictionary(DictionaryLike, ItemWithId):
def set(self, k, v):
"""
Call __setitem__ with key k, value v.
Call _&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_ with key k, value v.
"""
def delete(self, k):
"""
Call __delitem__ with key k.
Call _&nbsp;&nbsp;_delitem_&nbsp;&nbsp;_ with key k.
"""
def __guarded_setitem__(self, k, v):
"""
Call __setitem__ with key k, value v.
Call _&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_ with key k, value v.
"""
class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
......@@ -103,10 +133,11 @@ class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
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 __setitem__.
objects obtained via _&nbsp;&nbsp;_getitem_&nbsp;&nbsp;_, 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
_&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_.
"""
def __delitem__(self, k):
......@@ -117,9 +148,9 @@ class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
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.
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):
"""
......
lib/python/Products/Transience/__init__.py
View file @ d929af72
......@@ -85,7 +85,7 @@
"""
Transience initialization routines
$Id: __init__.py,v 1.2 2001/10/22 16:23:51 matt Exp $
$Id: __init__.py,v 1.3 2001/11/02 20:44:22 matt Exp $
"""
import Transience
......@@ -99,3 +99,4 @@ def initialize(context):
Transience.constructTransientObjectContainer)
)
context.registerHelp()
context.registerHelpTitle('Zope Help')
lib/python/Products/Transience/dtml/addTransientObjectContainer.dtml
View file @ d929af72
......@@ -2,7 +2,7 @@
<dtml-var "manage_form_title(this(), _,
form_title='Add Transient Object Container',
help_product='Transience',
help_product='Zope Help',
help_topic='Transience.stx'
)">
......
lib/python/Products/Transience/help/Transience.stx
View file @ d929af72
Transient Object Documentation
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')
_&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_(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
_&nbsp;&nbsp;_getitem_&nbsp;&nbsp;_(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.
_&nbsp;&nbsp;_delitem_&nbsp;&nbsp;_(key)
See Also
Deletes the given key from the TransientObject.
- "Transient Object API":TransienceInterfaces.py
lib/python/Products/Transience/help/TransienceInterfaces.py 0 → 100644
View file @ d929af72
"""
Transient Objects
TransientObjectContainers implement:
- ItemWithId
- StringKeyedHomogenousItemContainer
- TransientItemContainer
In particular, one uses the 'new_&nbsp;_or_&nbsp;_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 _&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_ with key k, value v.
"""
def delete(self, k):
"""
Call _&nbsp;&nbsp;_delitem_&nbsp;&nbsp;_ with key k.
"""
def __guarded_setitem__(self, k, v):
"""
Call _&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_ 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 _&nbsp;&nbsp;_getitem_&nbsp;&nbsp;_, 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
_&nbsp;&nbsp;_setitem_&nbsp;&nbsp;_.
"""
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.
"""
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7