Back to index

plone3  3.1.7
IVersionControl.py
Go to the documentation of this file.
00001 ##############################################################################
00002 #
00003 # Copyright (c) 2001 Zope Corporation and Contributors. All Rights Reserved.
00004 # 
00005 # This software is subject to the provisions of the Zope Public License,
00006 # Version 2.0 (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 
00014 __version__='$Revision: 1.7 $'[11:-2]
00015 
00016 from Interface import Interface
00017 
00018 
00019 class IVersionControl(Interface):
00020     """The version control interface serves as the main API for version 
00021        control operations. The interface hides most of the details of
00022        version data storage and retrieval.
00023 
00024        In Zope 3, the version control interface will probably be implemented
00025        by a version control service. In the meantime, it may be implemented
00026        directly by repository implementations (or other things, like CMF
00027        tools).
00028 
00029        The goal of this version of the version control interface is to
00030        support simple linear versioning with support for labelled versions.
00031        Future versions or extensions of this interface will likely support 
00032        more advanced version control features such as concurrent lines of
00033        descent (activities) and collection versioning."""
00034 
00035     def isAVersionableResource(object):
00036         """
00037         Returns true if the given object is a versionable resource.
00038 
00039         Permission: public
00040         """
00041 
00042     def isUnderVersionControl(object):
00043         """
00044         Returns true if the given object is under version control.
00045 
00046         Permission: public
00047         """
00048 
00049     def isResourceUpToDate(object, require_branch=0):
00050         """
00051         Returns true if a resource is based on the latest version. Note
00052         that the latest version is in the context of any activity (branch).
00053 
00054         If the require_branch flag is true, this method returns false if
00055         the resource is updated to a particular version, label, or date.
00056         Useful for determining whether a call to checkoutResource()
00057         will succeed.
00058 
00059         Permission: public
00060         """
00061 
00062     def isResourceChanged(object):
00063         """
00064         Return true if the state of a resource has changed in a transaction
00065         *after* the version bookkeeping was saved. Note that this method is 
00066         not appropriate for detecting changes within a transaction!
00067 
00068         Permission: public
00069         """
00070 
00071     def getVersionInfo(object):
00072         """
00073         Return the VersionInfo associated with the given object. The
00074         VersionInfo object contains version control bookkeeping information.
00075         If the object is not under version control, a VersionControlError
00076         will be raised.
00077 
00078         Permission: public
00079         """
00080 
00081     def applyVersionControl(object, message=None):
00082         """
00083         Place the given object under version control. A VersionControlError
00084         will be raised if the object is already under version control.
00085 
00086         After being placed under version control, the resource is logically
00087         in the 'checked-in' state.
00088 
00089         If no message is passed the 'Initial checkin.' message string is 
00090         written as the message log entry.
00091 
00092         Permission: Use version control
00093         """
00094 
00095     def checkoutResource(object):
00096         """
00097         Put the given version-controlled object into the 'checked-out'
00098         state, allowing changes to be made to the object. If the object is
00099         not under version control or the object is already checked out, a
00100         VersionControlError will be raised.
00101 
00102         Permission: Use version control
00103         """
00104 
00105     def checkinResource(object, message=''):
00106         """
00107         Check-in (create a new version) of the given object, updating the
00108         state and bookkeeping information of the given object. The optional
00109         message should describe the changes being committed. If the object
00110         is not under version control or is already in the checked-in state,
00111         a VersionControlError will be raised.
00112 
00113         Permission: Use version control
00114         """
00115 
00116     def uncheckoutResource(object):
00117         """
00118         Discard changes to the given object made since the last checkout.
00119         If the object is not under version control or is not checked out,
00120         a VersionControlError will be raised.
00121         """
00122 
00123     def updateResource(object, selector=None):
00124         """
00125         Update the state of the given object to that of a specific version
00126         of the object. The object must be in the checked-in state to be
00127         updated. The selector must be a string (version id, activity id,
00128         label or date) that is used to select a version from the version
00129         history.
00130 
00131         Permission: Use version control
00132         """
00133 
00134     def labelResource(object, label, force=None):
00135         """
00136         Associate the given resource with a label. If force is true, then
00137         any existing association with the given label will be removed and
00138         replaced with the new association. If force is false and there is
00139         an existing association with the given label, a VersionControlError
00140         will be raised.
00141 
00142         Permission: Use version control
00143         """
00144 
00145     def getVersionOfResource(history_id, selector):
00146         """
00147         Given a version history id and a version selector, return the
00148         object as of that version. Note that the returned object has no
00149         acquisition context. The selector must be a string (version id,
00150         activity id, label or date) that is used to select a version
00151         from the version history.
00152 
00153         Permission: Use version control
00154         """
00155 
00156     def getVersionIds(object):
00157         """
00158         Return a sequence of the (string) version ids corresponding to the
00159         available versions of an object. This should be used by UI elements
00160         to populate version selection widgets, etc.
00161 
00162         Permission: Use version control
00163         """
00164 
00165     def getLabelsForResource(object):
00166         """
00167         Return a sequence of the (string) labels corresponding to the
00168         versions of the given object that have been associated with a
00169         label. This should be used by UI elements to populate version
00170         selection widgets, etc.
00171 
00172         Permission: Use version control
00173         """
00174 
00175     def getLogEntries(object):
00176         """
00177         Return a sequence of LogEntry objects (most recent first) that
00178         are associated with a version-controlled object.
00179 
00180         Permission: Use version control
00181         """
00182 
00183 class IVersionInfo(Interface):
00184     """The IVersionInfo interface provides access to version control
00185        bookkeeping information. The fields provided by this interface
00186        are:
00187 
00188          timestamp - a float (time.time() format) value indicating the
00189          time that the bookkeeping information was created.
00190 
00191          history_id - the id of the version history related to the version
00192          controlled resource.
00193          
00194          version_id - the version id that the version controlled resource
00195          is based upon.
00196 
00197          status - an enumerated value indicating the status of the version
00198          controlled resource. This value is one of the VersionInfo class
00199          constants CHECKED_IN or CHECKED_OUT.
00200 
00201          sticky - sticky tag information used internally by the version
00202          control implementation.
00203 
00204          user_id - the id of the effective user at the time the bookkeeping
00205          information was created.
00206          """
00207 
00208 class ILogEntry(Interface):
00209     """The ILogEntry interface provides access to the information in an
00210        audit log entry. The fields provided by this interface are:
00211 
00212          timestamp - a float (time.time() format) value indicating the
00213          time that the log entry was created.
00214 
00215          version_id - the version id of the version controlled resource
00216          related to the log entry.
00217 
00218          action - an enumerated value indicating the action that was taken.
00219          This value is one of the LogEntry class constants ACTION_CHECKOUT,
00220          ACTION_CHECKIN, ACTION_UNCHECKOUT, ACTION_UPDATE.
00221 
00222          message - a string message provided by the user at the time of the
00223          action. This string may be empty.
00224 
00225          user_id - the id of the user causing the audited action.
00226 
00227          path - the path to the object upon which the action was taken.
00228 
00229          """
00230 
00231 
00232 class INonVersionedData(Interface):
00233     """Controls what parts of an object fall outside version control.
00234 
00235     Containerish objects implement this interface to allow the items they
00236     contain to be versioned independently of the container.
00237     """
00238 
00239     def listNonVersionedObjects():
00240         """Returns a list of subobjects that should not be pickled.
00241 
00242         The objects in the list must not be wrapped, because only the
00243         identity of the objects will be considered.  The version
00244         repository uses this method to avoid cloning subobjects that
00245         will soon be removed by removeNonVersionedData.
00246         """
00247 
00248     def removeNonVersionedData():
00249         """Removes the non-versioned data from this object.
00250 
00251         The version repository uses this method before storing an
00252         object in the version repository.
00253         """
00254 
00255     def getNonVersionedData():
00256         """Returns an opaque object containing the non-versioned data.
00257 
00258         The version repository uses this method before reverting an
00259         object to a revision.
00260         """
00261 
00262     def restoreNonVersionedData(dict):
00263         """Restores non-versioned data to this object.
00264 
00265         The version repository uses this method after reverting an
00266         object to a revision.
00267         """
00268 
00269 IVersionedContainer = INonVersionedData