##########################################################################
#
# Copyright (c) 2001 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##########################################################################
"""
Transient Objects
TransientObjectContainers are objects which contain zero or more
TransientObjects. They implement the following interfaces:
- 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
physical paths to Zope Script (Python Script or External Method)
objects (e.g. '/some/resolvable/script/name'). In any of these
cases, the delete and add notifications will be called with
arguments allowing the callbacks to operate on data representing the
state of the transient object at the moment of addition or deletion
(see setAddNotificationTarget and setDelNotificationTarget below).
TransientObjects are containerish items held within
TransientObjectContainers and they implement the following
interfaces:
- ItemWithId
- Transient
- DictionaryLike
- TTWDictionary
- ImmutablyValuedMappingOfPickleableObjects
Of particular importance is the idea 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
"""
import Interface
class Transient(Interface.Base):
def invalidate():
"""
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 isValid():
"""
Return true if transient object is still valid, false if not.
A transient object is valid if its invalidate method has not been
called.
"""
def getLastAccessed():
"""
Return the time the transient object was last accessed in
integer seconds-since-the-epoch form. Last accessed time
is defined as the last time the transient object's container
"asked about" this transient object.
"""
def setLastAccessed():
"""
Cause the last accessed time to be set to now.
"""
def getLastModified():
"""
Return the time the transient object was last modified in
integer seconds-since-the-epoch form. Modification generally implies
a call to one of the transient object's __setitem__ or __delitem__
methods, directly or indirectly as a result of a call to
update, clear, or other mutating data access methods.
"""
def setLastModified():
"""
Cause the last modified time to be set to now.
"""
def getCreated():
"""
Return the time the transient object was created in integer
seconds-since-the-epoch form.
"""
def getContainerKey():
"""
Return the key under which the object was placed in its
container.
"""
class DictionaryLike(Interface.Base):
def keys():
"""
Return sequence of key elements.
"""
def values():
"""
Return sequence of value elements.
"""
def items():
"""
Return sequence of (key, value) elements.
"""
def get(k, default='marker'):
"""
Return value associated with key k. Return None or default if k
does not exist.
"""
def has_key(k):
"""
Return true if item referenced by key k exists.
"""
def clear():
"""
Remove all key/value pairs.
"""
def update(d):
"""
Merge dictionary d into ourselves.
"""
# DictionaryLike does NOT support copy()
class ItemWithId(Interface.Base):
def getId():
"""
Returns a meaningful unique id for the object. Note that this id
need not the key under which the object is stored in its container.
"""
class TTWDictionary(DictionaryLike, ItemWithId):
def set(k, v):
"""
Call __setitem__ with key k, value v.
"""
def delete(k):
"""
Call __delitem__ with key k.
"""
def __guarded_setitem__(k, v):
"""
Call __setitem__ with key k, value v.
"""
class ImmutablyValuedMappingOfPickleableObjects(Interface.Base):
def __setitem__(k, v):
"""
Sets key k to value v, if k is both hashable and pickleable and
v is pickleable, else raise TypeError.
"""
def __getitem__(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 __setitem__.
"""
def __delitem__(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 get(k, default=None):
"""
Return value associated with key k via __getitem__. If value
associated with k does not exist, return default.
Returned item is acquisition-wrapped in self unless a default
is passed in and returned.
"""
def has_key(k):
"""
Return true if container has value associated with key k, else
return false.
"""
class StringKeyedHomogeneousItemContainer(HomogeneousItemContainer):
def new(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.
If the container is 'full', a MaxTransientObjectsExceeded exception
will be raised.
Returned object is acquisition-wrapped in self.
"""
def new_or_existing(k):
"""
If an object already exists in the container with key "k", it
is returned.
Otherwise, 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.
If a new object needs to be created and the container is 'full',
a MaxTransientObjectsExceeded exception will be raised.
Returned object is acquisition-wrapped in self.
"""
class TransientItemContainer(Interface.Base):
def setTimeoutMinutes(timeout_mins):
"""
Set the number of minutes of inactivity allowable for subobjects
before they expire.
"""
def getTimeoutMinutes():
"""
Return the number of minutes allowed for subobject inactivity
before expiration.
"""
def getAddNotificationTarget():
"""
Returns the currently registered 'add notification' value, or None.
"""
def setAddNotificationTarget(f):
"""
Cause the 'add notification' function to be 'f'.
If 'f' is not callable and is a string, treat it as a physical
path to a Zope Script object (Python Script, External Method,
et. al).
'add notify' functions need accept two arguments: 'item',
which is the transient object being destroyed, and 'container',
which is the transient object container which is performing
the destruction. For example::
def addNotify(item, container):
print "id of 'item' arg was %s" % item.getId()
"""
def getDelNotificationTarget():
"""
Returns the currently registered 'delete notification' value, or
None.
"""
def setDelNotificationTarget(f):
"""
Cause the 'delete notification' function to be 'f'.
If 'f' is not callable and is a string, treat it as a physical
path to a Zope Script object (Python Script, External Method,
et. al).
'Before destruction' functions need accept two arguments: 'item',
which is the transient object being destroyed, and 'container',
which is the transient object container which is performing
the destruction. For example::
def delNotify(item, container):
print "id of 'item' arg was %s" % item.getId()
"""
|