Back to index

plone3  3.1.7
interfaces.py
Go to the documentation of this file.
00001 from zope.interface import implements, Interface
00002 from zope.annotation.interfaces import IAttributeAnnotatable
00003 
00004 from zope import schema
00005 
00006 # Lock types, including the default
00007 
00008 class ILockType(Interface):
00009     """Representation of a type of lock
00010     """
00011     
00012     __name__ = schema.TextLine(title=u"Name",
00013                                description=u"The unique name of the lock type")
00014     
00015     stealable = schema.Bool(title=u"Stealable",
00016                             description=u"Whether this type of lock is stealable")
00017     user_unlockable = schema.Bool(title=u"User unlockable",
00018                                   description=u"Whether this type of lock should be unlockable immediately")
00019 
00020 class LockType(object):
00021     implements(ILockType)
00022     
00023     def __init__(self, name, stealable, user_unlockable):
00024         self.__name__ = name
00025         self.stealable = stealable
00026         self.user_unlockable = user_unlockable
00027          
00028 STEALABLE_LOCK = LockType(u"plone.locking.stealable", stealable=True, user_unlockable=True)
00029 
00030 # Marker interfaces
00031 
00032 class ITTWLockable(IAttributeAnnotatable):
00033     """Marker interface for objects that are lockable through-the-web
00034     """
00035     
00036 class INonStealableLock(Interface):
00037     """Mark an object with this interface to make locks be non-stealable.
00038     """
00039     
00040 # Functionality
00041     
00042 class ILockable(Interface):
00043     """A component that is lockable.
00044     
00045     Lock tokens are remembered (in annotations). Multiple locks can exist, 
00046     based on lock types. The default lock type, STEALABLE_LOCK, is a lock 
00047     that can be stolen (unless the object is marked with INonStealableLock).
00048     
00049     Most operations take the type as a parameter and operate on the lock token
00050     assocaited with a particular type.
00051     """
00052 
00053     def lock(lock_type=STEALABLE_LOCK, children=False):
00054         """Lock the object using the given key.
00055         
00056         If children is True, child objects will be locked as well.
00057         """
00058 
00059     def unlock(lock_type=STEALABLE_LOCK, stealable_only=True):
00060         """Unlock the object using the given key.
00061         
00062         If stealable_only is true, the operation will only have an effect on
00063         objects that are stealable(). Thus, non-stealable locks will need
00064         to pass stealable_only=False to actually get unlocked.
00065         """
00066         
00067     def clear_locks():
00068         """Clear all locks on the object
00069         """
00070         
00071     def locked():
00072         """True if the object is locked with any lock.
00073         """
00074         
00075     def can_safely_unlock(lock_type=STEALABLE_LOCK):
00076         """Determine if the current user can safely attempt to unlock the 
00077         object.
00078        
00079         That means:
00080         
00081          - lock_type.user_unlockable is True; and
00082          
00083          - the object is not locked; or
00084          - the object is only locked with the given lock_type, for the 
00085            current user;
00086         """
00087     
00088     def stealable(lock_type=STEALABLE_LOCK):
00089         """Find out if the lock can be stolen.
00090         
00091         This means:
00092         
00093          - the lock type is stealable; and
00094         
00095          - the object is not marked with INonStealableLock; or
00096          - can_safely_unlock() is true.
00097     
00098         """
00099     
00100     def lock_info():
00101         """Get information about locks on object. 
00102         
00103         Returns a list containing the following dict for each valid lock:
00104         
00105          - creator : the username of the lock creator
00106          - time    : the time at which the lock was acquired
00107          - token   : the underlying lock token
00108          - type    : the type of lock
00109         """