Back to index

plone3  3.1.7
IRepository.py
Go to the documentation of this file.
00001 #########################################################################
00002 # Copyright (c) 2004, 2005 Alberto Berti, Gregoire Weber.
00003 # All Rights Reserved.
00004 #
00005 # This file is part of CMFEditions.
00006 #
00007 # CMFEditions is free software; you can redistribute it and/or modify
00008 # it under the terms of the GNU General Public License as published by
00009 # the Free Software Foundation; either version 2 of the License, or
00010 # (at your option) any later version.
00011 #
00012 # CMFEditions is distributed in the hope that it will be useful,
00013 # but WITHOUT ANY WARRANTY; without even the implied warranty of
00014 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015 # GNU General Public License for more details.
00016 #
00017 # You should have received a copy of the GNU General Public License
00018 # along with CMFEditions; if not, write to the Free Software
00019 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
00020 #########################################################################
00021 """Repository strategies
00022 
00023 Terminology
00024 -----------
00025 
00026 content
00027   May be any kind of content, like a document, an image etc.
00028   The term doesn't carry any information about which version is talked about.
00029   Many different versions of a content may exist.
00030 
00031 version
00032   The state of a content at a given time.
00033 
00034 working copy
00035   A specific version of a content living in the Zope tree.
00036 
00037 former version
00038   A specific version in the past.
00039 
00040 
00041 $Id: IRepository.py,v 1.8 2005/04/01 17:41:56 disommav Exp $
00042 """
00043 
00044 from zope.interface import Interface as Z3Interface
00045 from Interface import Interface, Attribute
00046 
00047 
00048 class ICopyModifyMergeRepository(Interface):
00049     """The simplest repository possible.
00050 
00051     This component exposes the main API.
00052     """
00053 
00054     def isVersionable(obj):
00055         """Return True if the content type is versionable.
00056         """
00057 
00058     def setAutoApplyMode(autoapply):
00059         """Sets the autoapply mode.
00060 
00061         Before a repository can host a version of a content it has to be
00062         registred.
00063         If True the first 'save' operation will register the content
00064         automatically and applies version control.
00065         The default value is True.
00066         """
00067 
00068     def applyVersionControl(obj, comment='', metadata={}):
00069         """Register the content to the repository.
00070 
00071         Must be called prior any of the other repository related methods.
00072         Not necessary if 'autoapply' is set to a True.
00073         'comment' preferably is a human readable string comment.
00074         'metadata' must be a dictionary.
00075         This operation save the current version of the working copy as
00076         first version to the repository.
00077         """
00078 
00079     def save(obj, comment='', metadata={}):
00080         """Saves the current version of the content.
00081 
00082         'comment' preferably is a human readable string comment.
00083         'metadata' must be a dictionary.
00084         """
00085 
00086     def revert(obj, selector=None):
00087         """Reverts to a former version of the content by replacing the working
00088         copy.
00089 
00090         Reverts to the most recently saved version if no selector
00091         is passed.
00092         """
00093 
00094     def retrieve(obj, selector=None, preserve=()):
00095         """Returns a former version of a content without replacing the working
00096         copy.
00097 
00098         It returns an ``IVersionData`` object and doesn't modify the working
00099         copy in any way.
00100         """
00101 
00102     def restore(history_id, selector, container, new_id=None):
00103         """Restore a Specific version of an Object into a Container
00104         
00105         Usage Hint:
00106         
00107         May be used to restore a deleted object (delted from the tree).
00108         A version having been purged from the storage may never be restored.
00109         A new id may be chosen.
00110         """
00111 
00112     def isUpToDate(obj, selector=None):
00113         """Returns True if the working copy is modified.
00114         
00115         Comparison is done with the selected version.
00116         """
00117 
00118     def getHistory(obj, oldestFirst=False, preserve=()):
00119         """Returns the history of a content.
00120 
00121         Return the oldest version first  when ``oldestFirst`` set to 
00122         ``True``. Default is ``False`` (youngest version first).
00123         
00124         Returns a sequence (``IHistory``) of ``IVersionData`` objects.
00125         """
00126 
00127 
00128 class IPurgeSupport(Interface):
00129     """Repository Purge Support
00130     
00131     Purging a version removes that version irrevocably.
00132     
00133     Adds ``purge`` method and extends the signature of the ``isUpToDate``, 
00134     ``retrieve``, ``revert``, ``restore`` and ``getHistory`` methods.
00135     The defaults of the extended methods mimique the standard behaviour of 
00136     the original methods.
00137     
00138     With the introduction of purging two selection scheme exist for 
00139     retrieving versions. Either purged versions are taken into account 
00140     or not:
00141     
00142     - By passing ``countPurged=True`` purged versions are taken into
00143       account when accessing a version. When a purged version is accessed
00144       the archivist tool decides what to do.
00145     - By passing ``countPurged=False`` purged versions are **not taken into
00146       account** when accessing a version.
00147     
00148     Example: 
00149     
00150     An object got saved ten times. Two versions got purged in earlier 
00151     calls. The history looks like this (``s`` means: depends on storage,
00152     ``e`` means: exception raised)::
00153     
00154       countPurged==True:
00155       
00156         selector:          0, 1, 2, 3, 4, 5, 6, 7, 8, 9
00157         version retrieved: 0, 1, 2, s, s, 5, 6, 7, 8, 9
00158         
00159       countPurged==False:
00160        
00161         selector:          0, 1, 2, 3, 4, 5, 6, 7, 8, 9
00162         version retrieved: 0, 1, 2, 5, 6, 7, 8, 9, e, e
00163     """
00164     
00165     def purge(obj, selector, comment="", metadata={}, countPurged=True):
00166         """Purge a Version of a Content
00167         
00168         Purge the given version of the object. Referenced content objects 
00169         versions aren't purged. No recursive purging takes place.
00170         
00171         Also counts purged versions if ``True`` is passed to ``countPurged``
00172         (see interface documentation for details).
00173         
00174         Example: 
00175         
00176         An object got saved ten times. Two versions got purged in earlier 
00177         calls. The histor looks like this (a ``p`` stands for purged)::
00178         
00179             versions: 0, 1, 2, 3p, 4p, 5, 6, 7, 8, 9
00180             selector: 0, 1, 2, 3,  4,  5, 6, 7, 8, 9 (countPurged==True)
00181             selector: 0, 1, 2, -,  -,  3, 4, 5, 6, 7 (countPurged==False)
00182         
00183         The comment and metadata passed may be used to store informations 
00184         about the reasons of the purging.
00185         """
00186 
00187     def revert(obj, selector=None, countPurged=True):
00188         """Reverts to a former version of the content by replacing the working
00189         copy.
00190 
00191         Reverts to the most recently saved version if no selector
00192         is passed.
00193         
00194         Also counts purged versions if ``True`` is passed to ``countPurged``
00195         (see interface documentation for details).
00196         """
00197 
00198     def retrieve(obj, selector=None, preserve=(), countPurged=True):
00199         """Returns a former version of a content without replacing the working
00200         copy.
00201 
00202         It returns an ``IVersionData`` object and doesn't modify the working
00203         copy in any way.
00204         
00205         Also counts purged versions if ``True`` is passed to ``countPurged``
00206         (see interface documentation for details).
00207         """
00208 
00209     def restore(history_id, selector, container, new_id=None, 
00210                 countPurged=True):
00211         """Restore a Specific version of an Object into a Container
00212         
00213         Usage Hint:
00214         
00215         May be used to restore a deleted object (delted from the tree).
00216         A version having been purged from the storage may never be restored.
00217         A new id may be chosen.
00218         
00219         Also counts purged versions if ``True`` is passed to ``countPurged``
00220         (see interface documentation for details).
00221         """
00222 
00223     def isUpToDate(obj, selector=None, countPurged=True):
00224         """Returns True if the working copy is modified.
00225         
00226         Comparison is done with the selected version.
00227         
00228         Also counts purged versions if ``True`` is passed to ``countPurged``
00229         (see interface documentation for details).
00230         """
00231 
00232     def getHistory(obj, oldestFirst=False, preserve=(), countPurged=True):
00233         """Returns the history of a content.
00234 
00235         Return the oldest version first  when ``oldestFirst`` set to 
00236         ``True``. Default is ``False`` (youngest version first).
00237         
00238         Returns a sequence (``IHistory``) of ``IVersionData`` objects.
00239         
00240         Also counts purged versions if ``True`` is passed to ``countPurged``
00241         (see interface documentation for details).
00242         """
00243 
00244 
00245 class IVersionSupport(Interface):
00246     """Check if versioning is supported for a specific content.
00247     """
00248 
00249     def isVersionable(obj):
00250         """Returns True if the object is versionable
00251         """
00252 
00253 
00254 class IContentTypeVersionSupport(IVersionSupport):
00255     """Registry for versionable content types
00256     """
00257 
00258     def getVersionableContentTypes():
00259         """Returns a list of Versionable content types
00260         """
00261 
00262     def setVersionableContentTypes(new_content_types):
00263         """Set the list of Versionable content types
00264         """
00265 
00266 class IContentTypeVersionPolicySupport(IContentTypeVersionSupport):
00267     """Determine if a type supports a particular versioning method, the policy
00268        parameter is simply a string representing the policy"""
00269 
00270     def addPolicyForContentType(content_type, policy):
00271         """Sets a content type to use a specific policy"""
00272 
00273     def removePolicyFromContentType(content_type, policy):
00274         """Sets a content type to use a specific policy"""
00275 
00276     def supportsPolicy(obj, policy):
00277         """Determine if an object is set to use a specific versioning policy
00278         """
00279 
00280     def hasPolicy(obj):
00281         """Determine if an object has any assigned versioning policies"""
00282 
00283     def manage_setTypePolicies(policy_map):
00284         """Set the policy_mapping for all types from a dict of
00285         content_type : policy list mappings {content_type: [policy1, policy2]}
00286         """
00287 
00288     def listPolicies():
00289         """Return a sequence of all defined VersionPolicy objects"""
00290 
00291     def addPolicy(policy_id, policy_title, policy_class):
00292         """Add a new versioning policy, can optionally use an alternate
00293            policy class."""
00294 
00295     def removePolicy(policy_id):
00296         """Removes a versioning policy from the tool and all types which
00297            support it"""
00298 
00299     def manage_changePolicyDefs(policy_list):
00300         """Update the policy structure with a list of tuples [(id, title),...]
00301            The tuples may optionally contain a policy class and a dict of
00302            kwargs to pass to the policy add hook. e.g.:
00303           [(id, title, klass, {'arg1': val1}), ...]
00304         """
00305 
00306     def getPolicyMap():
00307         """Return a mapping of types to the lists of policies they support,
00308            for use in config screen."""
00309 
00310 
00311 class IVersionData(Interface):
00312     """ Used to store the versioned content plus additional data.
00313     """
00314 
00315     object = Attribute(
00316         """The retrieved version of the content.
00317         """)
00318 
00319     preserved_data = Attribute(
00320         """It is the data preserved from overwriting during the
00321         retrive process.
00322 
00323         The preserved data is a flat dictionary.
00324         With the example from above:
00325                 nick_name = vdata.preserved_data['nick_name']
00326         """)
00327 
00328     comment = Attribute(
00329         """The comment stored when the working copies version was saved.
00330         """)
00331 
00332     metadata = Attribute(
00333         """Metadata stored when the working copies version was saved.
00334         """)
00335 
00336     sys_metadata = Attribute(
00337         """System related metadata.
00338 
00339         A Dictionary with the following keys:
00340         - timestamp: save time
00341         - principal: the actor that did the save
00342         """)
00343 
00344     version_id = Attribute(
00345         """The version_id of the object.
00346         """)
00347 
00348 
00349 class IHistory(Interface):
00350     """Iterable version history.
00351     """
00352 
00353     def __len__():
00354         """Returns the length of the history.
00355         """
00356 
00357     def __getitem__(selector):
00358         """Returns the selected version of a content.
00359 
00360         Returns a ``IVersionData`` object.
00361         """
00362 
00363     def __iter__():
00364         """ Returns an iterator returning 'IVersionData' object.
00365         """
00366 
00367 
00368 class IRepositoryTool(Z3Interface):
00369     """Marker interface for the repository tool used in GenericSetup
00370        exportimport handlers.
00371     """
00372 
00373 
00374 class RepositoryError(Exception):
00375     """Repository exception.
00376     """
00377 
00378 
00379 class RepositoryPurgeError(RepositoryError):
00380     """Purge is only possible with a purge policy installed.
00381     """