data/TWiki/TWikiStoreDotPm.txt
changeset 0 414e01d06fd5
child 2 7bc60a767fa4
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiStoreDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,563 @@
     1.4 +---+ Package =TWiki::Store=
     1.5 +
     1.6 +This module hosts the generic storage backend. This module provides
     1.7 +the interface layer between the "real" store provider - which is hidden
     1.8 +behind a handler - and the rest of the system. it is responsible for
     1.9 +checking for topic existance, access permissions, and all the other
    1.10 +general admin tasks that are common to all store implementations.
    1.11 +
    1.12 +This module knows nothing about how the data is actually _stored_ -
    1.13 +that knowledge is entirely encapsulated in the handlers.
    1.14 +
    1.15 +The general contract for methods in the class requires that errors
    1.16 +are signalled using exceptions. TWiki::AccessControlException is
    1.17 +used for access control exceptions, and Error::Simple for all other
    1.18 +types of error.
    1.19 +
    1.20 +
    1.21 +%TOC%
    1.22 +
    1.23 +---++ ClassMethod *new* <tt>($session)</tt>
    1.24 +
    1.25 +Construct a Store module, linking in the chosen sub-implementation.
    1.26 +
    1.27 +
    1.28 +
    1.29 +---++ ObjectMethod *finish* <tt>()</tt>
    1.30 +Break circular references.
    1.31 +
    1.32 +
    1.33 +
    1.34 +---++ ObjectMethod *readTopic* <tt>($user,$web,$topic,$version) -> ($metaObject,$text)</tt>
    1.35 +
    1.36 +Reads the given version of a topic and it's meta-data. If the version
    1.37 +is undef, then read the most recent version. The version number must be
    1.38 +an integer, or undef for the latest version.
    1.39 +
    1.40 +if $user is defined, view permission will be required for the topic
    1.41 +read to be successful.  Access control violations are flagged by a
    1.42 +TWiki::AccessControlException. Permissions are checked for the user
    1.43 +name passed in.
    1.44 +
    1.45 +If the topic contains a web specification (is of the form Web.Topic) the
    1.46 +web specification will override whatever is passed in $web.
    1.47 +
    1.48 +The metadata and topic text are returned separately, with the metadata in a
    1.49 +TWiki::Meta object.  (The topic text is, as usual, just a string.)
    1.50 +
    1.51 +
    1.52 +
    1.53 +---++ ObjectMethod *_findAttachments* <tt>($session,$web,$topic,$knownAttachments) -> @attachmentsFoundInPub</tt>
    1.54 +
    1.55 +Synchronise the attachment list with what's actually on disk Returns an ARRAY
    1.56 +of FILEATTACHMENTs. These can be put in the new meta using
    1.57 +meta->put('FILEATTACHMENTS', $tree) 
    1.58 +
    1.59 +This function is only called when the AutoAttachPubFiles configuration option is set.
    1.60 +
    1.61 +IDEA On Windows machines where the underlying filesystem can store arbitary
    1.62 +meta data against files, this might replace/fulfil the COMMENT purpose
    1.63 +
    1.64 +TODO consider logging when things are added to metadata
    1.65 +
    1.66 +
    1.67 +
    1.68 +---++ ObjectMethod *readTopicRaw* <tt>($user,$web,$topic,$version) -> $topicText</tt>
    1.69 +
    1.70 +Reads the given version of a topic, without separating out any embedded
    1.71 +meta-data. If the version is undef, then read the most recent version.
    1.72 +The version number must be an integer or undef.
    1.73 +
    1.74 +If $user is defined, view permission will be required for the topic
    1.75 +read to be successful.  Access control violations are flagged by a
    1.76 +TWiki::AccessControlException. Permissions are checked for the user
    1.77 +name passed in.
    1.78 +
    1.79 +If the topic contains a web specification (is of the form Web.Topic) the
    1.80 +web specification will override whatever is passed in $web.
    1.81 +
    1.82 +SMELL: DO NOT CALL THIS METHOD UNLESS YOU HAVE NO CHOICE. This method breaks
    1.83 +encapsulation of the store, as it assumes meta is stored embedded in the text.
    1.84 +Other implementors of store will be forced to insert meta-data to ensure
    1.85 +correct operation of View raw=debug and the 'repRev' mode of Edit.
    1.86 +
    1.87 +$web and $topic _must_ be untainted.
    1.88 +
    1.89 +
    1.90 +
    1.91 +---++ ObjectMethod *moveAttachment* <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment,$user)</tt>
    1.92 +
    1.93 +Move an attachment from one topic to another.
    1.94 +
    1.95 +The caller to this routine should check that all topics are valid.
    1.96 +
    1.97 +All parameters must be defined, and must be untainted.
    1.98 +
    1.99 +
   1.100 +
   1.101 +---++ ObjectMethod *getAttachmentStream* <tt>($user,$web,$topic,$attName) -> \*STREAM</tt>
   1.102 +
   1.103 +   * =$user= - the user doing the reading, or undef if no access checks
   1.104 +   * =$web= - The web
   1.105 +   * =$topic= - The topic
   1.106 +   * =$attName= - Name of the attachment
   1.107 +
   1.108 +Open a standard input stream from an attachment.
   1.109 +
   1.110 +If $user is defined, view permission will be required for the topic
   1.111 +read to be successful.  Access control violations and errors will
   1.112 +cause exceptions to be thrown.
   1.113 +
   1.114 +Permissions are checked for the user name passed in.
   1.115 +
   1.116 +
   1.117 +
   1.118 +---++ ObjectMethod *getAttachmentList* <tt>($web,$topic)</tt>
   1.119 +
   1.120 +returns @($attachmentName => [stat]) for any given web, topic
   1.121 +
   1.122 +
   1.123 +
   1.124 +---++ ObjectMethod *attachmentExists* <tt>($web,$topic,$att) -> $boolean</tt>
   1.125 +
   1.126 +Determine if the attachment already exists on the given topic
   1.127 +
   1.128 +
   1.129 +
   1.130 +---++ ObjectMethod *_removeAutoAttachmentsFromMeta* <tt></tt>
   1.131 +
   1.132 +This is where we are going to remove from meta any entry that is marked as an automatic attachment.
   1.133 +
   1.134 +
   1.135 +
   1.136 +---++ ObjectMethod *moveTopic* <tt>($oldWeb,$oldTopic,$newWeb,$newTopic,$user)</tt>
   1.137 +
   1.138 +All parameters must be defined and must be untainted.
   1.139 +
   1.140 +
   1.141 +
   1.142 +---++ ObjectMethod *moveWeb* <tt>($oldWeb,$newWeb,$user)</tt>
   1.143 +
   1.144 +Move a web.
   1.145 +
   1.146 +All parrameters must be defined and must be untainted.
   1.147 +
   1.148 +
   1.149 +
   1.150 +---++ ObjectMethod *readAttachment* <tt>($user,$web,$topic,$attachment,$theRev) -> $text</tt>
   1.151 +
   1.152 +Read the given version of an attachment, returning the content.
   1.153 +
   1.154 +View permission on the topic is required for the
   1.155 +read to be successful.  Access control violations are flagged by a
   1.156 +TWiki::AccessControlException. Permissions are checked for the user
   1.157 +passed in.
   1.158 +
   1.159 +If $theRev is not given, the most recent rev is assumed.
   1.160 +
   1.161 +
   1.162 +
   1.163 +---++ ObjectMethod *getRevisionNumber* <tt>($web,$topic,$attachment) -> $integer</tt>
   1.164 +
   1.165 +Get the revision number of the most recent revision. Returns
   1.166 +the integer revision number or '' if the topic doesn't exist.
   1.167 +
   1.168 +WORKS FOR ATTACHMENTS AS WELL AS TOPICS
   1.169 +
   1.170 +
   1.171 +
   1.172 +---++ ObjectMethod *getWorkArea* <tt>($key) -> $directorypath</tt>
   1.173 +
   1.174 +Gets a private directory uniquely identified by $key. The directory is
   1.175 +intended as a work area for plugins. The directory will exist.
   1.176 +
   1.177 +
   1.178 +
   1.179 +---++ ObjectMethod *getRevisionDiff* <tt>($user,$web,$topic,$rev1,$rev2,$contextLines) -> \@diffArray</tt>
   1.180 +
   1.181 +Return reference to an array of [ diffType, $right, $left ]
   1.182 +   * =$user= - the user id, or undef to suppress access control checks
   1.183 +   * =$web= - the web
   1.184 +   * =$topic= - the topic
   1.185 +   * =$rev1= Integer revision number
   1.186 +   * =$rev2= Integer revision number
   1.187 +   * =$contextLines= - number of lines of context required
   1.188 +
   1.189 +
   1.190 +
   1.191 +---++ ObjectMethod *getRevisionInfo* <tt>($web,$topic,$rev,$attachment) -> ($date,$user,$rev,$comment)</tt>
   1.192 +
   1.193 +Get revision info of a topic.
   1.194 +   * =$web= Web name, optional, e.g. ='Main'=
   1.195 +   * =$topic= Topic name, required, e.g. ='TokyoOffice'=
   1.196 +   * =$rev= revision number. If 0, undef, or out-of-range, will get info about the most recent revision.
   1.197 +   * =$attachment= attachment filename; undef for a topic
   1.198 +Return list with: ( last update date, last user id, =
   1.199 +| $date | in epochSec |
   1.200 +| $user | user *object* |
   1.201 +| $rev | the revision number |
   1.202 +| $comment | WHAT COMMENT? |
   1.203 +e.g. =( 1234561, 'phoeny', 5, 'no comment' )
   1.204 +
   1.205 +NOTE NOTE NOTE if you are working within the TWiki code DO NOT USE THIS
   1.206 +FUNCTION FOR GETTING REVISION INFO OF TOPICS - use
   1.207 +TWiki::Meta::getRevisionInfo instead. This is essential to allow clean
   1.208 +transition to a topic object model later, and avoids the risk of confusion
   1.209 +coming from meta and Store revision information being out of step.
   1.210 +(it's OK to use it for attachments)
   1.211 +
   1.212 +
   1.213 +
   1.214 +---++ StaticMethod *dataEncode* <tt>($uncoded) -> $coded</tt>
   1.215 +
   1.216 +Encode meta-data fields, escaping out selected characters. The encoding
   1.217 +is chosen to avoid problems with parsing the attribute values, while
   1.218 +minimising the number of characters encoded so searches can still work
   1.219 +(fairly) sensibly.
   1.220 +
   1.221 +The encoding has to be exported because TWiki (and plugins) use
   1.222 +encoded field data in other places e.g. RDiff, mainly as a shorthand
   1.223 +for the properly parsed meta object. Some day we may be able to
   1.224 +eliminate that....
   1.225 +
   1.226 +
   1.227 +
   1.228 +---++ StaticMethod *dataDecode* <tt>($encoded) -> $decoded</tt>
   1.229 +
   1.230 +Decode escapes in a string that was encoded using dataEncode
   1.231 +
   1.232 +The encoding has to be exported because TWiki (and plugins) use
   1.233 +encoded field data in other places e.g. RDiff, mainly as a shorthand
   1.234 +for the properly parsed meta object. Some day we may be able to
   1.235 +eliminate that....
   1.236 +
   1.237 +
   1.238 +
   1.239 +---++ ObjectMethod *saveTopic* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
   1.240 +
   1.241 +   * =$user= - user doing the saving (object)
   1.242 +   * =$web= - web for topic
   1.243 +   * =$topic= - topic to atach to
   1.244 +   * =$text= - topic text
   1.245 +   * =$meta= - topic meta-data
   1.246 +   * =$options= - Ref to hash of options
   1.247 +=$options= may include:
   1.248 +| =dontlog= | don't log this change in twiki log |
   1.249 +| =hide= | if the attachment is to be hidden in normal topic view |
   1.250 +| =comment= | comment for save |
   1.251 +| =file= | Temporary file name to upload |
   1.252 +| =minor= | True if this is a minor change (used in log) |
   1.253 +| =savecmd= | Save command |
   1.254 +| =forcedate= | grr |
   1.255 +| =unlock= | |
   1.256 +
   1.257 +Save a new revision of the topic, calling plugins handlers as appropriate.
   1.258 +
   1.259 +
   1.260 +
   1.261 +---++ ObjectMethod *saveAttachment* <tt>($web,$topic,$attachment,$user,$opts)</tt>
   1.262 +
   1.263 +   * =$user= - user doing the saving
   1.264 +   * =$web= - web for topic
   1.265 +   * =$topic= - topic to atach to
   1.266 +   * =$attachment= - name of the attachment
   1.267 +   * =$opts= - Ref to hash of options
   1.268 +=$opts= may include:
   1.269 +| =dontlog= | don't log this change in twiki log |
   1.270 +| =comment= | comment for save |
   1.271 +| =hide= | if the attachment is to be hidden in normal topic view |
   1.272 +| =stream= | Stream of file to upload |
   1.273 +| =file= | Name of a file to use for the attachment data. ignored is stream is set. |
   1.274 +| =filepath= | Client path to file |
   1.275 +| =filesize= | Size of uploaded data |
   1.276 +| =filedate= | Date |
   1.277 +| =tmpFilename= | Pathname of the server file the stream is attached to. Required if stream is set. |
   1.278 +
   1.279 +Saves a new revision of the attachment, invoking plugin handlers as
   1.280 +appropriate.
   1.281 +
   1.282 +If file is not set, this is a properties-only save.
   1.283 +
   1.284 +
   1.285 +
   1.286 +---++ ObjectMethod *repRev* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
   1.287 +
   1.288 +Replace last (top) revision with different text.
   1.289 +
   1.290 +Parameters and return value as saveTopic, except
   1.291 +   * =$options= - as for saveTopic, with the extra option:
   1.292 +      * =timetravel= - if we want to force the deposited revision to look as much like the revision specified in =$rev= as possible.
   1.293 +      * =operation= - set to the name of the operation performing the save. This is used only in the log, and is normally =cmd= or =save=. It defaults to =save=.
   1.294 +
   1.295 +Used to try to avoid the deposition of 'unecessary' revisions, for example
   1.296 +where a user quickly goes back and fixes a spelling error.
   1.297 +
   1.298 +Also provided as a means for administrators to rewrite history (timetravel).
   1.299 +
   1.300 +It is up to the store implementation if this is different
   1.301 +to a normal save or not.
   1.302 +
   1.303 +
   1.304 +
   1.305 +---++ ObjectMethod *delRev* <tt>($user,$web,$topic,$text,$meta,$options)</tt>
   1.306 +
   1.307 +Parameters and return value as saveTopic.
   1.308 +
   1.309 +Provided as a means for administrators to rewrite history.
   1.310 +
   1.311 +Delete last entry in repository, restoring the previous
   1.312 +revision.
   1.313 +
   1.314 +It is up to the store implementation whether this actually
   1.315 +does delete a revision or not; some implementations will
   1.316 +simply promote the previous revision up to the head.
   1.317 +
   1.318 +
   1.319 +
   1.320 +---++ ObjectMethod *lockTopic* <tt>($web,$topic)</tt>
   1.321 +
   1.322 +Grab a topic lock on the given topic. A topic lock will cause other
   1.323 +processes that also try to claim a lock to block. A lock has a
   1.324 +maximum lifetime of 2 minutes, so operations on a locked topic
   1.325 +must be completed within that time. You cannot rely on the
   1.326 +lock timeout clearing the lock, though; that should always
   1.327 +be done by calling unlockTopic. The best thing to do is to guard
   1.328 +the locked section with a try..finally clause. See man Error for more info.
   1.329 +
   1.330 +Topic locks are used to make store operations atomic. They are
   1.331 +_note_ the locks used when a topic is edited; those are Leases
   1.332 +(see =getLease=)
   1.333 +
   1.334 +
   1.335 +
   1.336 +---++ ObjectMethod *unlockTopic* <tt>($user,$web,$topic)</tt>
   1.337 +
   1.338 +Release the topic lock on the given topic. A topic lock will cause other
   1.339 +processes that also try to claim a lock to block. It is important to
   1.340 +release a topic lock after a guard section is complete. This should
   1.341 +normally be done in a 'finally' block. See man Error for more info.
   1.342 +
   1.343 +Topic locks are used to make store operations atomic. They are
   1.344 +_note_ the locks used when a topic is edited; those are Leases
   1.345 +(see =getLease=)
   1.346 +
   1.347 +
   1.348 +
   1.349 +---++ ObjectMethod *webExists* <tt>($web) -> $boolean</tt>
   1.350 +
   1.351 +Test if web exists
   1.352 +   * =$web= - Web name, required, e.g. ='Sandbox'=
   1.353 +
   1.354 +A web _has_ to have a preferences topic to be a web.
   1.355 +
   1.356 +
   1.357 +
   1.358 +---++ ObjectMethod *topicExists* <tt>($web,$topic) -> $boolean</tt>
   1.359 +
   1.360 +Test if topic exists
   1.361 +   * =$web= - Web name, optional, e.g. ='Main'=
   1.362 +   * =$topic= - Topic name, required, e.g. ='TokyoOffice'=, or ="Main.TokyoOffice"=
   1.363 +
   1.364 +
   1.365 +
   1.366 +---++ ObjectMethod *getTopicParent* <tt>($web,$topic) -> $string</tt>
   1.367 +
   1.368 +Get the name of the topic parent. Needs to be fast because
   1.369 +of use by Render.pm.
   1.370 +
   1.371 +
   1.372 +
   1.373 +---++ ObjectMethod *getTopicLatestRevTime* <tt>($web,$topic) -> $epochSecs</tt>
   1.374 +
   1.375 +Get an approximate rev time for the latest rev of the topic. This method
   1.376 +is used to optimise searching. Needs to be as fast as possible.
   1.377 +
   1.378 +
   1.379 +
   1.380 +---++ ObjectMethod *eachChange* <tt>($web,$time) -> $iterator</tt>
   1.381 +
   1.382 +Get an iterator over the list of all the changes in the given web between
   1.383 +=$time= and now. $time is a time in seconds since 1st Jan 1970, and is not
   1.384 +guaranteed to return any changes that occurred before (now - 
   1.385 +{Store}{RememberChangesFor}). Changes are returned in most-recent-first
   1.386 +order.
   1.387 +
   1.388 +
   1.389 +
   1.390 +---++ ObjectMethod *getTopicNames* <tt>($web) -> @topics</tt>
   1.391 +
   1.392 +Get list of all topics in a web
   1.393 +   * =$web= - Web name, required, e.g. ='Sandbox'=
   1.394 +Return a topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
   1.395 +
   1.396 +
   1.397 +
   1.398 +---++ ObjectMethod *getListOfWebs* <tt>($filter) -> @webNames</tt>
   1.399 +
   1.400 +Gets a list of webs, filtered according to the spec in the $filter,
   1.401 +which may include one of:
   1.402 +   1 'user' (for only user webs)
   1.403 +   2 'template' (for only template webs)
   1.404 +$filter may also contain the word 'public' which will further filter
   1.405 +webs on whether NOSEARCHALL is specified for them or not.
   1.406 +'allowed' filters out webs that the user is denied access to by a *WEBVIEW.
   1.407 +
   1.408 +If $TWiki::cfg{EnableHierarchicalWebs} is set, will also list
   1.409 +sub-webs recursively.
   1.410 +
   1.411 +
   1.412 +
   1.413 +---++ ObjectMethod *createWeb* <tt>($user,$newWeb,$baseWeb,$opts)</tt>
   1.414 +
   1.415 +$newWeb is the name of the new web.
   1.416 +
   1.417 +$baseWeb is the name of an existing web (a template web). If the
   1.418 +base web is a system web, all topics in it
   1.419 +will be copied into the new web. If it is a normal web, only topics starting
   1.420 +with 'Web' will be copied. If no base web is specified, an empty web
   1.421 +(with no topics) will be created. If it is specified but does not exist,
   1.422 +an error will be thrown.
   1.423 +
   1.424 +$opts is a ref to a hash that contains settings to be modified in
   1.425 +the web preferences topic in the new web.
   1.426 +
   1.427 +
   1.428 +
   1.429 +---++ ObjectMethod *removeWeb* <tt>($user,$web)</tt>
   1.430 +
   1.431 +   * =$user= - user doing the removing (for the history)
   1.432 +   * =$web= - web being removed
   1.433 +
   1.434 +Destroy a web, utterly. Removed the data and attachments in the web.
   1.435 +
   1.436 +Use with great care!
   1.437 +
   1.438 +The web must be a known web to be removed this way.
   1.439 +
   1.440 +
   1.441 +
   1.442 +---++ ObjectMethod *getDebugText* <tt>($meta,$text) -> $text</tt>
   1.443 +
   1.444 +Generate a debug text form of the text/meta, for use in debug displays,
   1.445 +by annotating the text with meta informtion.
   1.446 +
   1.447 +
   1.448 +
   1.449 +---++ ObjectMethod *cleanUpRevID* <tt>($rev) -> $integer</tt>
   1.450 +
   1.451 +Cleans up (maps) a user-supplied revision ID and converts it to an integer
   1.452 +number that can be incremented to create a new revision number.
   1.453 +
   1.454 +This method should be used to sanitise user-provided revision IDs.
   1.455 +
   1.456 +
   1.457 +
   1.458 +---++ ObjectMethod *copyTopic* <tt>($user,$fromweb,$fromtopic,$toweb,$totopic)</tt>
   1.459 +
   1.460 +Copy a topic and all it's attendant data from one web to another.
   1.461 +
   1.462 +SMELL: Does not fix up meta-data!
   1.463 +
   1.464 +
   1.465 +
   1.466 +---++ ObjectMethod *searchMetaData* <tt>($params) -> $text</tt>
   1.467 +
   1.468 +Search meta-data associated with topics. Parameters are passed in the $params hash,
   1.469 +which may contain:
   1.470 +| =type= | =topicmoved=, =parent= or =field= |
   1.471 +| =topic= | topic to search for, for =topicmoved= and =parent= |
   1.472 +| =name= | form field to search, for =field= type searches. May be a regex. |
   1.473 +| =value= | form field value. May be a regex. |
   1.474 +| =title= | Title prepended to the returned search results |
   1.475 +| =default= | defualt value if there are no results |
   1.476 +| =web= | web to search in, default is all webs |
   1.477 +| =format= | string for custom formatting results |
   1.478 +The idea is that people can search for meta-data values without having to be
   1.479 +aware of how or where meta-data is stored.
   1.480 +
   1.481 +SMELL: should be replaced with a proper SQL-like search, c.f. Plugins.DBCacheContrib.
   1.482 +
   1.483 +
   1.484 +
   1.485 +---++ ObjectMethod *searchInWebMetaData* <tt>($query,$web,\@topics) -> \%matches</tt>
   1.486 +
   1.487 +Search for a meta-data expression in the content of a web. =$query= must be a =TWiki::Query= object.
   1.488 +
   1.489 +Returns a reference to a hash that maps the names of topics that all matched
   1.490 +to the result of the query expression (e.g. if the query expression is
   1.491 +'TOPICPARENT.name' then you will get back a hash that maps topic names
   1.492 +to their parent.
   1.493 +
   1.494 +
   1.495 +
   1.496 +---++ ObjectMethod *searchInWebContent* <tt>($searchString,$web,\@topics,\%options) -> \%map</tt>
   1.497 +
   1.498 +Search for a string in the content of a web. The search must be over all
   1.499 +content and all formatted meta-data, though the latter search type is
   1.500 +deprecated (use searchMetaData instead).
   1.501 +
   1.502 +   * =$searchString= - the search string, in egrep format if regex
   1.503 +   * =$web= - The web to search in
   1.504 +   * =\@topics= - reference to a list of topics to search
   1.505 +   * =\%options= - reference to an options hash
   1.506 +The =\%options= hash may contain the following options:
   1.507 +   * =type= - if =regex= will perform a egrep-syntax RE search (default '')
   1.508 +   * =casesensitive= - false to ignore case (defaulkt true)
   1.509 +   * =files_without_match= - true to return files only (default false)
   1.510 +
   1.511 +The return value is a reference to a hash which maps each matching topic
   1.512 +name to a list of the lines in that topic that matched the search,
   1.513 +as would be returned by 'grep'. If =files_without_match= is specified, it will
   1.514 +return on the first match in each topic (i.e. it will return only one
   1.515 +match per topic, and will not return matching lines).
   1.516 +
   1.517 +
   1.518 +
   1.519 +---++ ObjectMethod *getRevisionAtTime* <tt>($web,$topic,$time) -> $rev</tt>
   1.520 +
   1.521 +   * =$web= - web for topic
   1.522 +   * =$topic= - topic
   1.523 +   * =$time= - time (in epoch secs) for the rev
   1.524 +
   1.525 +Get the revision number of a topic at a specific time.
   1.526 +Returns a single-digit rev number or undef if it couldn't be determined
   1.527 +(either because the topic isn't that old, or there was a problem)
   1.528 +
   1.529 +
   1.530 +
   1.531 +---++ ObjectMethod *getLease* <tt>($web,$topic) -> $lease</tt>
   1.532 +
   1.533 +   * =$web= - web for topic
   1.534 +   * =$topic= - topic
   1.535 +
   1.536 +If there is an lease on the topic, return the lease, otherwise undef.
   1.537 +A lease is a block of meta-information about a topic that can be
   1.538 +recovered (this is a hash containing =user=, =taken= and =expires=).
   1.539 +Leases are taken out when a topic is edited. Only one lease
   1.540 +can be active on a topic at a time. Leases are used to warn if
   1.541 +another user is already editing a topic.
   1.542 +
   1.543 +
   1.544 +
   1.545 +---++ ObjectMethod *setLease* <tt>($web,$topic,$user,$length)</tt>
   1.546 +
   1.547 +Take out an lease on the given topic for this user for $length seconds.
   1.548 +
   1.549 +See =getLease= for more details about Leases.
   1.550 +
   1.551 +
   1.552 +
   1.553 +---++ ObjectMethod *clearLease* <tt>($web,$topic)</tt>
   1.554 +
   1.555 +Cancel the current lease.
   1.556 +
   1.557 +See =getLease= for more details about Leases.
   1.558 +
   1.559 +
   1.560 +
   1.561 +---++ ObjectMethod *removeSpuriousLeases* <tt>($web)</tt>
   1.562 +
   1.563 +Remove leases that are not related to a topic. These can get left behind in
   1.564 +some store implementations when a topic is created, but never saved.
   1.565 +
   1.566 +