Back to index

plone3  3.1.7
interfaces.py
Go to the documentation of this file.
00001 ##############################################################################
00002 #
00003 # Copyright (c) 2004 Zope Corporation and Contributors. All Rights Reserved.
00004 #
00005 # This software is subject to the provisions of the Zope Public License,
00006 # Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
00007 # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
00008 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00009 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
00010 # FOR A PARTICULAR PURPOSE.
00011 #
00012 ##############################################################################
00013 """Unique Id Generation and Handling
00014 
00015 These interfaces are intentionaly kept close to those from Zope3. Additionaly
00016 handling (IUniqueIdHandler) and generation (IUniqueIdGenerator) of unique ids
00017 are kept separate.
00018 
00019 $Id: interfaces.py 77186 2007-06-28 19:06:19Z yuppie $
00020 """
00021 
00022 from zope.interface import Interface
00023 
00024 from Products.CMFCore.interfaces import ICallableOpaqueItem
00025 from Products.CMFCore.interfaces import ICallableOpaqueItemEvents
00026 
00027 
00028 class UniqueIdError(Exception):
00029 
00030     pass
00031 
00032 
00033 class IUniqueIdGenerator(Interface):
00034 
00035     """Generate a unique id.
00036     """
00037 
00038     def __call__():
00039         """Return a unique id value.
00040         """
00041 
00042     def convert(uid):
00043         """Converts the unique id from string type to the appropriate
00044            uid type.
00045 
00046         The resulting type has to be the same as the one '__call__'
00047         returns.
00048         """
00049 
00050 
00051 class IUniqueIdAnnotationManagement(Interface):
00052 
00053     """Manage unique id annotations.
00054     """
00055 
00056     def __call__(obj, id):
00057         """Attach an unique id attribute of 'id' to the passed object.
00058 
00059         Return a unique id object implementing 'IUniqueIdAnnotation'.
00060         """
00061 
00062 
00063 class IUniqueIdAnnotation(ICallableOpaqueItem):
00064 
00065     """Opaque unique id item handling adding, copying, and deletion events.
00066     """
00067 
00068     def setUid(uid):
00069         """Set the uid value the unique id annotation shall return.
00070         """
00071 
00072 
00073 class IUniqueIdSet(Interface):
00074 
00075     """(Un)register unique ids on objects.
00076     """
00077 
00078     def register(obj):
00079         """Register the object and return the unique id generated for it.
00080 
00081         If the object is already registered, its unique id is returned anyway.
00082 
00083         UniqueIdError is raised if object can not be registered a unique id.
00084         """
00085 
00086     def unregister(obj):
00087         """Remove the object from the indexes.
00088 
00089         UniqueIdError is raised if object was not registered previously.
00090         """
00091 
00092     def setUid(obj, uid, check_uniqueness=True):
00093         """Set the unique id of an object.
00094 
00095         By default a check ensuring uniqueness is enabled. Be aware when
00096         disabling this check: You really need to know what you do !!!
00097         """
00098 
00099 
00100 class IUniqueIdQuery(Interface):
00101 
00102     """Querying unique ids.
00103     """
00104 
00105     def queryUid(obj, default=None):
00106         """Return the unique id of the object.
00107 
00108         If the object doesn't have a unique, the default value is returned.
00109         """
00110 
00111     def getUid(obj):
00112         """Return the unique id of the object.
00113 
00114         If the object doesn't have a unique, a UniqueIdError is raised.
00115         """
00116 
00117     def queryObject(uid, default=None):
00118         """Return the object with the given uid.
00119 
00120         If no object exist with the given unique id, the default value is
00121         returned.
00122         """
00123 
00124     def getObject(uid):
00125         """Return the object with the given uid.
00126 
00127         If no object exist with the given unique id, a UniqueIdError is raised.
00128         """
00129 
00130 
00131 # This is the main API for playing with unique ids
00132 class IUniqueIdHandler(IUniqueIdSet, IUniqueIdQuery):
00133 
00134     """Handle registering, querying unique ids and objects.
00135     """
00136 
00137 
00138 # This is a secondary API enhancement
00139 class IUniqueIdBrainQuery(Interface):
00140 
00141     """Querying unique ids returning brains for efficiency sake.
00142 
00143     Returning a brain is more efficient than returning the object. A brain
00144     usually exposes only parts of the object and should only be read from.
00145 
00146     If the implementing class doesn't support returning a catalog brain it may
00147     fallback to return the object. To be entirely compatible it must implement
00148     the (non existing) interface catalog brains implement.
00149     """
00150 
00151     def queryBrain(uid, default=None):
00152         """Return the brain of object with the given uid.
00153 
00154         If no object exist with the given unique id, the default value
00155         is returned.
00156         """
00157 
00158     def getBrain(uid):
00159         """Return a brain of the object with the given uid.
00160 
00161         If no object exist with the given unique id, a UniqueIdError is
00162         raised.
00163         """
00164 
00165 
00166 # This is another secondary API enhancement
00167 class IUniqueIdUnrestrictedQuery(Interface):
00168 
00169     """Querying unique ids unrestricted.
00170 
00171     The below methods return not yet effective and already expired
00172     objects regardless of the roles the caller has.
00173 
00174     CAUTION: Care must be taken not to open security holes by exposing
00175     the results of these methods to non authorized callers!
00176 
00177     If you're in doubth if you should use this method signature or
00178     the restricted ones ('IUniqueIdQuery' and 'IUniqueIdBrainQuery')
00179     use the latter!
00180 
00181     Returning a brain is more efficient than returning the object. A brain
00182     usually exposes only parts of the object and should only be read from.
00183 
00184     If the implementing class doesn't support returning a catalog
00185     brain it may fallback to return the object. To be entirely
00186     compatible it must implement the (non existing) interface
00187     catalog brains implement.
00188     """
00189 
00190     def unrestrictedQueryObject(uid, default=None):
00191         """Return the object with the given uid.
00192 
00193         If no object exist with the given unique id, the default value
00194         is returned.
00195         """
00196 
00197     def unrestrictedGetObject(uid):
00198         """Return a brain of the object with the given uid.
00199 
00200         If no object exist with the given unique id, a UniqueIdError
00201         is raised.
00202         """
00203 
00204     def unrestrictedQueryBrain(uid, default=None):
00205         """Return the brain of the object with the given uid.
00206 
00207         If no object exist with the given unique id, the default value
00208         is returned.
00209         """
00210 
00211     def unrestrictedGetBrain(uid):
00212         """Return a brain of the object with the given uid.
00213 
00214         If no object exist with the given unique id, a UniqueIdError
00215         is raised.
00216         """