TWiki/TWikiStoreDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Store="></a> Package =TWiki::Store
   2
   3 This module hosts the generic storage backend. This module provides the interface layer between the "real" store provider - which is hidden behind a handler - and the rest of the system. it is responsible for checking for topic existance, access permissions, and all the other general admin tasks that are common to all store implementations.
   4
   5 This module knows nothing about how the data is actually _stored_ - that knowledge is entirely encapsulated in the handlers.
   6
   7 The general contract for methods in the class requires that errors are signalled using exceptions. TWiki::AccessControlException is used for access control exceptions, and Error::Simple for all other types of error.
   8
   9 <div>
  10   <ul>
  11     <li><a href="#Package =TWiki::Store="> Package TWiki::Store</a><ul>
  12         <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
  13         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  14         <li><a href="#ObjectMethod <strong>readTopic</strong> ($user,"> ObjectMethod readTopic <tt>($user,$web,$topic,$version) -&gt; ($metaObject,$text)</tt></a></li>
  15         <li><a href="#ObjectMethod *_findAttachments*"> ObjectMethod _findAttachments <tt>($session,$web,$topic,$knownAttachments) -&gt; @attachmentsFoundInPub</tt></a></li>
  16         <li><a href="#ObjectMethod <strong>read_TopicRaw</strong> ($u"> ObjectMethod readTopicRaw <tt>($user,$web,$topic,$version) -&gt; $topicText</tt></a></li>
  17         <li><a href="#ObjectMethod <strong>moveAttachment</strong> ($"> ObjectMethod moveAttachment <tt>($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment,$user)</tt></a></li>
  18         <li><a href="#ObjectMethod *get_AttachmentStre"> ObjectMethod getAttachmentStream <tt>($user,$web,$topic,$attName) -&gt; \*STREAM</tt></a></li>
  19         <li><a href="#ObjectMethod *get_AttachmentList"> ObjectMethod getAttachmentList <tt>($web,$topic)</tt></a></li>
  20         <li><a href="#ObjectMethod *attachmentExists*"> ObjectMethod attachmentExists <tt>($web,$topic,$att) -&gt; $boolean</tt></a></li>
  21         <li><a href="#ObjectMethod *_remove_AutoAttach"> ObjectMethod _removeAutoAttachmentsFromMeta <tt></tt></a></li>
  22         <li><a href="#ObjectMethod <strong>moveTopic</strong> ($oldWe"> ObjectMethod moveTopic <tt>($oldWeb,$oldTopic,$newWeb,$newTopic,$user)</tt></a></li>
  23         <li><a href="#ObjectMethod <strong>moveWeb</strong> ($oldWeb,"> ObjectMethod moveWeb <tt>($oldWeb,$newWeb,$user)</tt></a></li>
  24         <li><a href="#ObjectMethod <strong>readAttachment</strong> ($"> ObjectMethod readAttachment <tt>($user,$web,$topic,$attachment,$theRev) -&gt; $text</tt></a></li>
  25         <li><a href="#ObjectMethod *get_RevisionNumber"> ObjectMethod getRevisionNumber <tt>($web,$topic,$attachment) -&gt; $integer</tt></a></li>
  26         <li><a href="#ObjectMethod <strong>get_WorkArea</strong> ($ke"> ObjectMethod getWorkArea <tt>($key) -&gt; $directorypath</tt></a></li>
  27         <li><a href="#ObjectMethod *get_RevisionDiff*"> ObjectMethod getRevisionDiff <tt>($user,$web,$topic,$rev1,$rev2,$contextLines) -&gt; \@diffArray</tt></a></li>
  28         <li><a href="#ObjectMethod *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($web,$topic,$rev,$attachment) -&gt; ($date,$user,$rev,$comment)</tt></a></li>
  29         <li><a href="#StaticMethod <strong>dataEncode</strong> ($unco"> StaticMethod dataEncode <tt>($uncoded) -&gt; $coded</tt></a></li>
  30         <li><a href="#StaticMethod <strong>dataDecode</strong> ($enco"> StaticMethod dataDecode <tt>($encoded) -&gt; $decoded</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>saveTopic</strong> ($user,"> ObjectMethod saveTopic <tt>($user,$web,$topic,$text,$meta,$options)</tt></a></li>
  32         <li><a href="#ObjectMethod <strong>saveAttachment</strong> ($"> ObjectMethod saveAttachment <tt>($web,$topic,$attachment,$user,$opts)</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>repRev</strong> ($user,$we"> ObjectMethod repRev <tt>($user,$web,$topic,$text,$meta,$options)</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>delRev</strong> ($user,$we"> ObjectMethod delRev <tt>($user,$web,$topic,$text,$meta,$options)</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>lockTopic</strong> ($web,$"> ObjectMethod lockTopic <tt>($web,$topic)</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>unlockTopic</strong> ($use"> ObjectMethod unlockTopic <tt>($user,$web,$topic)</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>webExists</strong> ($web)"> ObjectMethod webExists <tt>($web) -&gt; $boolean</tt></a></li>
  38         <li><a href="#ObjectMethod <strong>topicExists</strong> ($web"> ObjectMethod topicExists <tt>($web,$topic) -&gt; $boolean</tt></a></li>
  39         <li><a href="#ObjectMethod <strong>get_TopicParent</strong> ("> ObjectMethod getTopicParent <tt>($web,$topic) -&gt; $string</tt></a></li>
  40         <li><a href="#ObjectMethod *get_TopicLatestRev"> ObjectMethod getTopicLatestRevTime <tt>($web,$topic) -&gt; $epochSecs</tt></a></li>
  41         <li><a href="#ObjectMethod <strong>eachChange</strong> ($web,"> ObjectMethod eachChange <tt>($web,$time) -&gt; $iterator</tt></a></li>
  42         <li><a href="#ObjectMethod <strong>get_TopicNames</strong> ($"> ObjectMethod getTopicNames <tt>($web) -&gt; @topics</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>get_ListOfWebs</strong> ($"> ObjectMethod getListOfWebs <tt>($filter) -&gt; @webNames</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>createWeb</strong> ($user,"> ObjectMethod createWeb <tt>($user,$newWeb,$baseWeb,$opts)</tt></a></li>
  45         <li><a href="#ObjectMethod <strong>removeWeb</strong> ($user,"> ObjectMethod removeWeb <tt>($user,$web)</tt></a></li>
  46         <li><a href="#ObjectMethod <strong>get_DebugText</strong> ($m"> ObjectMethod getDebugText <tt>($meta,$text) -&gt; $text</tt></a></li>
  47         <li><a href="#ObjectMethod <strong>clean_UpRevID</strong> ($r"> ObjectMethod cleanUpRevID <tt>($rev) -&gt; $integer</tt></a></li>
  48         <li><a href="#ObjectMethod <strong>copyTopic</strong> ($user,"> ObjectMethod copyTopic <tt>($user,$fromweb,$fromtopic,$toweb,$totopic)</tt></a></li>
  49         <li><a href="#ObjectMethod <strong>search_MetaData</strong> ("> ObjectMethod searchMetaData <tt>($params) -&gt; $text</tt></a></li>
  50         <li><a href="#ObjectMethod *search_InWebMetaDa"> ObjectMethod searchInWebMetaData <tt>($query,$web,\@topics) -&gt; \%matches</tt></a></li>
  51         <li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -&gt; \%map</tt></a></li>
  52         <li><a href="#ObjectMethod *get_RevisionAtTime"> ObjectMethod getRevisionAtTime <tt>($web,$topic,$time) -&gt; $rev</tt></a></li>
  53         <li><a href="#ObjectMethod <strong>getLease</strong> ($web,$t"> ObjectMethod getLease <tt>($web,$topic) -&gt; $lease</tt></a></li>
  54         <li><a href="#ObjectMethod <strong>setLease</strong> ($web,$t"> ObjectMethod setLease <tt>($web,$topic,$user,$length)</tt></a></li>
  55         <li><a href="#ObjectMethod <strong>clearLease</strong> ($web,"> ObjectMethod clearLease <tt>($web,$topic)</tt></a></li>
  56         <li><a href="#ObjectMethod *remove_SpuriousLea"> ObjectMethod removeSpuriousLeases <tt>($web)</tt></a></li>
  57       </ul>
  58     </li>
  59   </ul>
  60 </div>
  61
  62 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session)"></a> [[ClassMethod]] **new** `($session)`
  63
  64 Construct a Store module, linking in the chosen sub-implementation.
  65
  66 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  67
  68 Break circular references.
  69
  70 ## <a name="ObjectMethod &lt;strong&gt;readTopic&lt;/strong&gt; ($user,"></a> [[ObjectMethod]] **readTopic** `($user,$web,$topic,$version) -> ($metaObject,$text)`
  71
  72 Reads the given version of a topic and it's meta-data. If the version is undef, then read the most recent version. The version number must be an integer, or undef for the latest version.
  73
  74 if $user is defined, view permission will be required for the topic read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the user name passed in.
  75
  76 If the topic contains a web specification (is of the form Web.Topic) the web specification will override whatever is passed in $web.
  77
  78 The metadata and topic text are returned separately, with the metadata in a TWiki::Meta object. (The topic text is, as usual, just a string.)
  79
  80 ## <a name="ObjectMethod &lt;strong&gt;_findAttachments*"></a><a name="ObjectMethod *_findAttachments&lt;/strong&gt; "></a> [[ObjectMethod]] **\_findAttachments** `($session,$web,$topic,$knownAttachments) -> @attachmentsFoundInPub`
  81
  82 Synchronise the attachment list with what's actually on disk Returns an ARRAY of FILEATTACHMENTs. These can be put in the new meta using meta-&gt;put('FILEATTACHMENTS', $tree)
  83
  84 This function is only called when the [[AutoAttachPubFiles]] configuration option is set.
  85
  86 IDEA On Windows machines where the underlying filesystem can store arbitary meta data against files, this might replace/fulfil the COMMENT purpose
  87
  88 TODO consider logging when things are added to metadata
  89
  90 ## <a name="ObjectMethod &lt;strong&gt;read_TopicRaw&lt;/strong&gt; ($u"></a> [[ObjectMethod]] **readTopicRaw** `($user,$web,$topic,$version) -> $topicText`
  91
  92 Reads the given version of a topic, without separating out any embedded meta-data. If the version is undef, then read the most recent version. The version number must be an integer or undef.
  93
  94 If $user is defined, view permission will be required for the topic read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the user name passed in.
  95
  96 If the topic contains a web specification (is of the form Web.Topic) the web specification will override whatever is passed in $web.
  97
  98 SMELL: DO NOT CALL THIS METHOD UNLESS YOU HAVE NO CHOICE. This method breaks encapsulation of the store, as it assumes meta is stored embedded in the text. Other implementors of store will be forced to insert meta-data to ensure correct operation of View raw=debug and the 'repRev' mode of Edit.
  99
 100 $web and $topic _must_ be untainted.
 101
 102 ## <a name="ObjectMethod &lt;strong&gt;moveAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **moveAttachment** `($oldWeb,$oldTopic,$oldAttachment,$newWeb,$newTopic,$newAttachment,$user)`
 103
 104 Move an attachment from one topic to another.
 105
 106 The caller to this routine should check that all topics are valid.
 107
 108 All parameters must be defined, and must be untainted.
 109
 110 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentStre"></a> [[ObjectMethod]] \*getAttachmentStream `($user,$web,$topic,$attName) -> \*STREAM`
 111
 112 - `$user` - the user doing the reading, or undef if no access checks
 113 - `$web` - The web
 114 - `$topic` - The topic
 115 - `$attName` - Name of the attachment
 116
 117 Open a standard input stream from an attachment.
 118
 119 If $user is defined, view permission will be required for the topic read to be successful. Access control violations and errors will cause exceptions to be thrown.
 120
 121 Permissions are checked for the user name passed in.
 122
 123 ## <a name="ObjectMethod &lt;strong&gt;get_AttachmentList"></a> [[ObjectMethod]] \*getAttachmentList `($web,$topic)`
 124
 125 returns @($attachmentName =&gt; [stat]) for any given web, topic
 126
 127 ## <a name="ObjectMethod &lt;strong&gt;attachmentExists*"></a><a name="ObjectMethod *attachmentExists&lt;/strong&gt; "></a> [[ObjectMethod]] **attachmentExists** `($web,$topic,$att) -> $boolean`
 128
 129 Determine if the attachment already exists on the given topic
 130
 131 ## <a name="ObjectMethod &lt;strong&gt;_remove_AutoAttach"></a> [[ObjectMethod]] \*\_removeAutoAttachmentsFromMeta ``
 132
 133 This is where we are going to remove from meta any entry that is marked as an automatic attachment.
 134
 135 ## <a name="ObjectMethod &lt;strong&gt;moveTopic&lt;/strong&gt; ($oldWe"></a> [[ObjectMethod]] **moveTopic** `($oldWeb,$oldTopic,$newWeb,$newTopic,$user)`
 136
 137 All parameters must be defined and must be untainted.
 138
 139 ## <a name="ObjectMethod &lt;strong&gt;moveWeb&lt;/strong&gt; ($oldWeb,"></a> [[ObjectMethod]] **moveWeb** `($oldWeb,$newWeb,$user)`
 140
 141 Move a web.
 142
 143 All parrameters must be defined and must be untainted.
 144
 145 ## <a name="ObjectMethod &lt;strong&gt;readAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **readAttachment** `($user,$web,$topic,$attachment,$theRev) -> $text`
 146
 147 Read the given version of an attachment, returning the content.
 148
 149 View permission on the topic is required for the read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the user passed in.
 150
 151 If $theRev is not given, the most recent rev is assumed.
 152
 153 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionNumber"></a> [[ObjectMethod]] \*getRevisionNumber `($web,$topic,$attachment) -> $integer`
 154
 155 Get the revision number of the most recent revision. Returns the integer revision number or '' if the topic doesn't exist.
 156
 157 WORKS FOR ATTACHMENTS AS WELL AS TOPICS
 158
 159 ## <a name="ObjectMethod &lt;strong&gt;get_WorkArea&lt;/strong&gt; ($ke"></a> [[ObjectMethod]] **getWorkArea** `($key) -> $directorypath`
 160
 161 Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins. The directory will exist.
 162
 163 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionDiff*"></a><a name="ObjectMethod *get_RevisionDiff&lt;/strong&gt; "></a> [[ObjectMethod]] **getRevisionDiff** `($user,$web,$topic,$rev1,$rev2,$contextLines) -> \@diffArray`
 164
 165 Return reference to an array of [ diffType, $right, $left ]
 166
 167 - `$user` - the user id, or undef to suppress access control checks
 168 - `$web` - the web
 169 - `$topic` - the topic
 170 - `$rev1` Integer revision number
 171 - `$rev2` Integer revision number
 172 - `$contextLines` - number of lines of context required
 173
 174 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo&lt;/strong&gt; "></a> [[ObjectMethod]] **getRevisionInfo** `($web,$topic,$rev,$attachment) -> ($date,$user,$rev,$comment)`
 175
 176 Get revision info of a topic.
 177
 178 - `$web` Web name, optional, e.g. `'Main'`
 179 - `$topic` Topic name, required, e.g. `'TokyoOffice'`
 180 - `$rev` revision number. If 0, undef, or out-of-range, will get info about the most recent revision.
 181 - `$attachment` attachment filename; undef for a topic
 182
 183 Return list with: ( last update date, last user id, =
 184
 185 <table border="1" cellpadding="0" cellspacing="0">
 186   <tr>
 187     <td> $date </td>
 188     <td> in epochSec </td>
 189   </tr>
 190   <tr>
 191     <td> $user </td>
 192     <td> user <strong>object</strong></td>
 193   </tr>
 194   <tr>
 195     <td> $rev </td>
 196     <td> the revision number </td>
 197   </tr>
 198   <tr>
 199     <td> $comment </td>
 200     <td> WHAT COMMENT? </td>
 201   </tr>
 202 </table>
 203
 204 e.g. =( 1234561, 'phoeny', 5, 'no comment' )
 205
 206 NOTE NOTE NOTE if you are working within the TWiki code DO NOT USE THIS FUNCTION FOR GETTING REVISION INFO OF TOPICS - use TWiki::Meta::getRevisionInfo instead. This is essential to allow clean transition to a topic object model later, and avoids the risk of confusion coming from meta and Store revision information being out of step. (it's OK to use it for attachments)
 207
 208 ## <a name="StaticMethod &lt;strong&gt;dataEncode&lt;/strong&gt; ($unco"></a> [[StaticMethod]] **dataEncode** `($uncoded) -> $coded`
 209
 210 Encode meta-data fields, escaping out selected characters. The encoding is chosen to avoid problems with parsing the attribute values, while minimising the number of characters encoded so searches can still work (fairly) sensibly.
 211
 212 The encoding has to be exported because TWiki (and plugins) use encoded field data in other places e.g. RDiff, mainly as a shorthand for the properly parsed meta object. Some day we may be able to eliminate that....
 213
 214 ## <a name="StaticMethod &lt;strong&gt;dataDecode&lt;/strong&gt; ($enco"></a> [[StaticMethod]] **dataDecode** `($encoded) -> $decoded`
 215
 216 Decode escapes in a string that was encoded using dataEncode
 217
 218 The encoding has to be exported because TWiki (and plugins) use encoded field data in other places e.g. RDiff, mainly as a shorthand for the properly parsed meta object. Some day we may be able to eliminate that....
 219
 220 ## <a name="ObjectMethod &lt;strong&gt;saveTopic&lt;/strong&gt; ($user,"></a> [[ObjectMethod]] **saveTopic** `($user,$web,$topic,$text,$meta,$options)`
 221
 222 - `$user` - user doing the saving (object)
 223 - `$web` - web for topic
 224 - `$topic` - topic to atach to
 225 - `$text` - topic text
 226 - `$meta` - topic meta-data
 227 - `$options` - Ref to hash of options
 228
 229 `$options` may include:
 230
 231 <table border="1" cellpadding="0" cellspacing="0">
 232   <tr>
 233     <td><code>dontlog</code></td>
 234     <td> don't log this change in twiki log </td>
 235   </tr>
 236   <tr>
 237     <td><code>hide</code></td>
 238     <td> if the attachment is to be hidden in normal topic view </td>
 239   </tr>
 240   <tr>
 241     <td><code>comment</code></td>
 242     <td> comment for save </td>
 243   </tr>
 244   <tr>
 245     <td><code>file</code></td>
 246     <td> Temporary file name to upload </td>
 247   </tr>
 248   <tr>
 249     <td><code>minor</code></td>
 250     <td> True if this is a minor change (used in log) </td>
 251   </tr>
 252   <tr>
 253     <td><code>savecmd</code></td>
 254     <td> Save command </td>
 255   </tr>
 256   <tr>
 257     <td><code>forcedate</code></td>
 258     <td> grr </td>
 259   </tr>
 260   <tr>
 261     <td><code>unlock</code></td>
 262     <td>   </td>
 263   </tr>
 264 </table>
 265
 266 Save a new revision of the topic, calling plugins handlers as appropriate.
 267
 268 ## <a name="ObjectMethod &lt;strong&gt;saveAttachment&lt;/strong&gt; ($"></a> [[ObjectMethod]] **saveAttachment** `($web,$topic,$attachment,$user,$opts)`
 269
 270 - `$user` - user doing the saving
 271 - `$web` - web for topic
 272 - `$topic` - topic to atach to
 273 - `$attachment` - name of the attachment
 274 - `$opts` - Ref to hash of options
 275
 276 `$opts` may include:
 277
 278 <table border="1" cellpadding="0" cellspacing="0">
 279   <tr>
 280     <td><code>dontlog</code></td>
 281     <td> don't log this change in twiki log </td>
 282   </tr>
 283   <tr>
 284     <td><code>comment</code></td>
 285     <td> comment for save </td>
 286   </tr>
 287   <tr>
 288     <td><code>hide</code></td>
 289     <td> if the attachment is to be hidden in normal topic view </td>
 290   </tr>
 291   <tr>
 292     <td><code>stream</code></td>
 293     <td> Stream of file to upload </td>
 294   </tr>
 295   <tr>
 296     <td><code>file</code></td>
 297     <td> Name of a file to use for the attachment data. ignored is stream is set. </td>
 298   </tr>
 299   <tr>
 300     <td><code>filepath</code></td>
 301     <td> Client path to file </td>
 302   </tr>
 303   <tr>
 304     <td><code>filesize</code></td>
 305     <td> Size of uploaded data </td>
 306   </tr>
 307   <tr>
 308     <td><code>filedate</code></td>
 309     <td> Date </td>
 310   </tr>
 311   <tr>
 312     <td><code>tmpFilename</code></td>
 313     <td> Pathname of the server file the stream is attached to. Required if stream is set. </td>
 314   </tr>
 315 </table>
 316
 317 Saves a new revision of the attachment, invoking plugin handlers as appropriate.
 318
 319 If file is not set, this is a properties-only save.
 320
 321 ## <a name="ObjectMethod &lt;strong&gt;repRev&lt;/strong&gt; ($user,$we"></a> [[ObjectMethod]] **repRev** `($user,$web,$topic,$text,$meta,$options)`
 322
 323 Replace last (top) revision with different text.
 324
 325 Parameters and return value as saveTopic, except
 326
 327 - `$options` - as for saveTopic, with the extra option:
 328   - `timetravel` - if we want to force the deposited revision to look as much like the revision specified in `$rev` as possible.
 329   - `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`.
 330
 331 Used to try to avoid the deposition of 'unecessary' revisions, for example where a user quickly goes back and fixes a spelling error.
 332
 333 Also provided as a means for administrators to rewrite history (timetravel).
 334
 335 It is up to the store implementation if this is different to a normal save or not.
 336
 337 ## <a name="ObjectMethod &lt;strong&gt;delRev&lt;/strong&gt; ($user,$we"></a> [[ObjectMethod]] **delRev** `($user,$web,$topic,$text,$meta,$options)`
 338
 339 Parameters and return value as saveTopic.
 340
 341 Provided as a means for administrators to rewrite history.
 342
 343 Delete last entry in repository, restoring the previous revision.
 344
 345 It is up to the store implementation whether this actually does delete a revision or not; some implementations will simply promote the previous revision up to the head.
 346
 347 ## <a name="ObjectMethod &lt;strong&gt;lockTopic&lt;/strong&gt; ($web,$"></a> [[ObjectMethod]] **lockTopic** `($web,$topic)`
 348
 349 Grab a topic lock on the given topic. A topic lock will cause other processes that also try to claim a lock to block. A lock has a maximum lifetime of 2 minutes, so operations on a locked topic must be completed within that time. You cannot rely on the lock timeout clearing the lock, though; that should always be done by calling unlockTopic. The best thing to do is to guard the locked section with a try..finally clause. See man Error for more info.
 350
 351 Topic locks are used to make store operations atomic. They are _note_ the locks used when a topic is edited; those are Leases (see `getLease`)
 352
 353 ## <a name="ObjectMethod &lt;strong&gt;unlockTopic&lt;/strong&gt; ($use"></a> [[ObjectMethod]] **unlockTopic** `($user,$web,$topic)`
 354
 355 Release the topic lock on the given topic. A topic lock will cause other processes that also try to claim a lock to block. It is important to release a topic lock after a guard section is complete. This should normally be done in a 'finally' block. See man Error for more info.
 356
 357 Topic locks are used to make store operations atomic. They are _note_ the locks used when a topic is edited; those are Leases (see `getLease`)
 358
 359 ## <a name="ObjectMethod &lt;strong&gt;webExists&lt;/strong&gt; ($web)"></a><a name="ObjectMethod &lt;strong&gt;webExists&lt;/strong&gt; ($web) "></a> [[ObjectMethod]] **webExists** `($web) -> $boolean`
 360
 361 Test if web exists
 362
 363 - `$web` - Web name, required, e.g. `'Sandbox'`
 364
 365 A web _has_ to have a preferences topic to be a web.
 366
 367 ## <a name="ObjectMethod &lt;strong&gt;topicExists&lt;/strong&gt; ($web"></a> [[ObjectMethod]] **topicExists** `($web,$topic) -> $boolean`
 368
 369 Test if topic exists
 370
 371 - `$web` - Web name, optional, e.g. `'Main'`
 372 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 373
 374 Warning: topicExists does not call ( $web, $topic ) = $this-&gt;\{session\}-&gt;normalizeWebTopicName( $web, $topic ); for you (it'd make TWiki even slower) so make sure you do so.
 375
 376 ## <a name="ObjectMethod &lt;strong&gt;get_TopicParent&lt;/strong&gt; ("></a> [[ObjectMethod]] **getTopicParent** `($web,$topic) -> $string`
 377
 378 Get the name of the topic parent. Needs to be fast because of use by Render.pm.
 379
 380 ## <a name="ObjectMethod &lt;strong&gt;get_TopicLatestRev"></a> [[ObjectMethod]] \*getTopicLatestRevTime `($web,$topic) -> $epochSecs`
 381
 382 Get an approximate rev time for the latest rev of the topic. This method is used to optimise searching. Needs to be as fast as possible.
 383
 384 ## <a name="ObjectMethod &lt;strong&gt;eachChange&lt;/strong&gt; ($web,"></a> [[ObjectMethod]] **eachChange** `($web,$time) -> $iterator`
 385
 386 Get an iterator over the list of all the changes in the given web between `$time` and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - \{Store\}\{RememberChangesFor\}). Changes are returned in most-recent-first order.
 387
 388 ## <a name="ObjectMethod &lt;strong&gt;get_TopicNames&lt;/strong&gt; ($"></a> [[ObjectMethod]] **getTopicNames** `($web) -> @topics`
 389
 390 Get list of all topics in a web
 391
 392 - `$web` - Web name, required, e.g. `'Sandbox'`
 393
 394 Return a topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 395
 396 ## <a name="ObjectMethod &lt;strong&gt;get_ListOfWebs&lt;/strong&gt; ($"></a> [[ObjectMethod]] **getListOfWebs** `($filter) -> @webNames`
 397
 398 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 399
 400 1. 'user' (for only user webs)
 401 2. 'template' (for only template webs)
 402
 403 $filter may also contain the word 'public' which will further filter webs on whether NOSEARCHALL is specified for them or not. 'allowed' filters out webs that the user is denied access to by a \*WEBVIEW.
 404
 405 If $TWiki::cfg\{EnableHierarchicalWebs\} is set, will also list sub-webs recursively.
 406
 407 ## <a name="ObjectMethod &lt;strong&gt;createWeb&lt;/strong&gt; ($user,"></a> [[ObjectMethod]] **createWeb** `($user,$newWeb,$baseWeb,$opts)`
 408
 409 $newWeb is the name of the new web.
 410
 411 $baseWeb is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
 412
 413 $opts is a ref to a hash that contains settings to be modified in the web preferences topic in the new web.
 414
 415 ## <a name="ObjectMethod &lt;strong&gt;removeWeb&lt;/strong&gt; ($user,"></a> [[ObjectMethod]] **removeWeb** `($user,$web)`
 416
 417 - `$user` - user doing the removing (for the history)
 418 - `$web` - web being removed
 419
 420 Destroy a web, utterly. Removed the data and attachments in the web.
 421
 422 Use with great care!
 423
 424 The web must be a known web to be removed this way.
 425
 426 ## <a name="ObjectMethod &lt;strong&gt;get_DebugText&lt;/strong&gt; ($m"></a> [[ObjectMethod]] **getDebugText** `($meta,$text) -> $text`
 427
 428 Generate a debug text form of the text/meta, for use in debug displays, by annotating the text with meta informtion.
 429
 430 ## <a name="ObjectMethod &lt;strong&gt;clean_UpRevID&lt;/strong&gt; ($r"></a> [[ObjectMethod]] **cleanUpRevID** `($rev) -> $integer`
 431
 432 Cleans up (maps) a user-supplied revision ID and converts it to an integer number that can be incremented to create a new revision number.
 433
 434 This method should be used to sanitise user-provided revision IDs.
 435
 436 ## <a name="ObjectMethod &lt;strong&gt;copyTopic&lt;/strong&gt; ($user,"></a> [[ObjectMethod]] **copyTopic** `($user,$fromweb,$fromtopic,$toweb,$totopic)`
 437
 438 Copy a topic and all it's attendant data from one web to another.
 439
 440 SMELL: Does not fix up meta-data!
 441
 442 ## <a name="ObjectMethod &lt;strong&gt;search_MetaData&lt;/strong&gt; ("></a> [[ObjectMethod]] **searchMetaData** `($params) -> $text`
 443
 444 Search meta-data associated with topics. Parameters are passed in the $params hash, which may contain:
 445
 446 <table border="1" cellpadding="0" cellspacing="0">
 447   <tr>
 448     <td><code>type</code></td>
 449     <td><code>topicmoved</code>, <code>parent</code> or <code>field</code></td>
 450   </tr>
 451   <tr>
 452     <td><code>topic</code></td>
 453     <td> topic to search for, for <code>topicmoved</code> and <code>parent</code></td>
 454   </tr>
 455   <tr>
 456     <td><code>name</code></td>
 457     <td> form field to search, for <code>field</code> type searches. May be a regex. </td>
 458   </tr>
 459   <tr>
 460     <td><code>value</code></td>
 461     <td> form field value. May be a regex. </td>
 462   </tr>
 463   <tr>
 464     <td><code>title</code></td>
 465     <td> Title prepended to the returned search results </td>
 466   </tr>
 467   <tr>
 468     <td><code>default</code></td>
 469     <td> defualt value if there are no results </td>
 470   </tr>
 471   <tr>
 472     <td><code>web</code></td>
 473     <td> web to search in, default is all webs </td>
 474   </tr>
 475   <tr>
 476     <td><code>format</code></td>
 477     <td> string for custom formatting results </td>
 478   </tr>
 479 </table>
 480
 481 The idea is that people can search for meta-data values without having to be aware of how or where meta-data is stored.
 482
 483 SMELL: should be replaced with a proper SQL-like search, c.f. [[DBCacheContrib]].
 484
 485 ## <a name="ObjectMethod &lt;strong&gt;search_InWebMetaDa"></a> [[ObjectMethod]] \*searchInWebMetaData `($query,$web,\@topics) -> \%matches`
 486
 487 Search for a meta-data expression in the content of a web. `$query` must be a `TWiki::Query` object.
 488
 489 Returns a reference to a hash that maps the names of topics that all matched to the result of the query expression (e.g. if the query expression is 'TOPICPARENT.name' then you will get back a hash that maps topic names to their parent.
 490
 491 ## <a name="ObjectMethod &lt;strong&gt;search_InWebConten"></a> [[ObjectMethod]] \*searchInWebContent `($searchString,$web,\@topics,\%options) -> \%map`
 492
 493 Search for a string in the content of a web. The search must be over all content and all formatted meta-data, though the latter search type is deprecated (use searchMetaData instead).
 494
 495 - `$searchString` - the search string, in egrep format if regex
 496 - `$web` - The web to search in
 497 - `\@topics` - reference to a list of topics to search
 498 - `\%options` - reference to an options hash
 499
 500 The `\%options` hash may contain the following options:
 501
 502 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
 503 - `casesensitive` - false to ignore case (defaulkt true)
 504 - `files_without_match` - true to return files only (default false)
 505
 506 The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'. If `files_without_match` is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
 507
 508 ## <a name="ObjectMethod &lt;strong&gt;get_RevisionAtTime"></a> [[ObjectMethod]] \*getRevisionAtTime `($web,$topic,$time) -> $rev`
 509
 510 - `$web` - web for topic
 511 - `$topic` - topic
 512 - `$time` - time (in epoch secs) for the rev
 513
 514 Get the revision number of a topic at a specific time. Returns a single-digit rev number or undef if it couldn't be determined (either because the topic isn't that old, or there was a problem)
 515
 516 ## <a name="ObjectMethod &lt;strong&gt;getLease&lt;/strong&gt; ($web,$t"></a> [[ObjectMethod]] **getLease** `($web,$topic) -> $lease`
 517
 518 - `$web` - web for topic
 519 - `$topic` - topic
 520
 521 If there is an lease on the topic, return the lease, otherwise undef. A lease is a block of meta-information about a topic that can be recovered (this is a hash containing `user`, `taken` and `expires`). Leases are taken out when a topic is edited. Only one lease can be active on a topic at a time. Leases are used to warn if another user is already editing a topic.
 522
 523 ## <a name="ObjectMethod &lt;strong&gt;setLease&lt;/strong&gt; ($web,$t"></a> [[ObjectMethod]] **setLease** `($web,$topic,$user,$length)`
 524
 525 Take out an lease on the given topic for this user for $length seconds.
 526
 527 See `getLease` for more details about Leases.
 528
 529 ## <a name="ObjectMethod &lt;strong&gt;clearLease&lt;/strong&gt; ($web,"></a> [[ObjectMethod]] **clearLease** `($web,$topic)`
 530
 531 Cancel the current lease.
 532
 533 See `getLease` for more details about Leases.
 534
 535 ## <a name="ObjectMethod &lt;strong&gt;remove_SpuriousLea"></a> [[ObjectMethod]] \*removeSpuriousLeases `($web)`
 536
 537 Remove leases that are not related to a topic. These can get left behind in some store implementations when a topic is created, but never saved.