2 rcs_id('$Id: backend.php,v 1.1 2001-09-18 19:16:23 dairiki Exp $');
9 //:deleted (*) (Set if latest content is empty.)
17 %content (?should this be here?)
18 _supplanted : Time version ceased to be the current version
20 mtime (*) : Time of version edit.
23 author : nominal author
24 author_id : authenticated author
33 (types are scalars: strings, ints, bools)
37 * A WikiDB_backend handles the storage and retrieval of data for a WikiDB.
39 * A WikiDB_backend handles the storage and retrieval of data for a WikiDB.
40 * It does not have to be this way, of course, but the standard WikiDB uses
41 * a WikiDB_backend. (Other WikiDB's could be written which use some other
42 * method to access their underlying data store.)
44 * The interface outlined here seems to work well with both RDBM based
45 * and flat DBM/hash based methods of data storage.
47 * Though it contains some default implementation of certain methods,
48 * this is an abstract base class. It is expected that most effificient
49 * backends will override nearly all the methods in this class.
57 * Get page meta-data from database.
59 * @param $pagename string Page name.
61 * Returns a hash containing the page meta-data.
62 * Returns an empty array if there is no meta-data for the requested page.
63 * Keys which might be present in the hash are:
65 * <dt> locked <dd> If the page is locked.
66 * <dt> hits <dd> The page hit count.
67 * <dt> created <dd> Unix time of page creation. (FIXME: Deprecated: I
68 * don't think we need this...)
71 function get_pagedata($pagename) {
72 trigger_error("virtual", E_USER_ERROR);
76 * Update the page meta-data.
80 * Only meta-data whose keys are preset in $newdata is affected.
84 * $backend->update_pagedata($pagename, array('locked' => 1));
86 * will set the value of 'locked' to 1 for the specified page, but it
87 * will not affect the value of 'hits' (or whatever other meta-data
88 * may have been stored for the page.)
90 * To delete a particular piece of meta-data, set it's value to false.
92 * $backend->update_pagedata($pagename, array('locked' => false));
95 * @param $pagename string Page name.
96 * @param $newdata hash New meta-data.
98 function update_pagedata($pagename, $newdata) {
99 trigger_error("virtual", E_USER_ERROR);
104 * Get the current version number for a page.
106 * @param $pagename string Page name.
107 * @return int The latest version number for the page. Returns zero if
108 * no versions of a page exist.
110 function get_latest_version($pagename) {
111 trigger_error("virtual", E_USER_ERROR);
115 * Get preceding version number.
117 * @param $pagename string Page name.
118 * @param $version int Find version before this one.
119 * @return int The version number of the version in the database which
120 * immediately preceeds $version.
122 function get_previous_version($pagename, $version) {
123 trigger_error("virtual", E_USER_ERROR);
127 * Get revision meta-data and content.
129 * @param $pagename string Page name.
130 * @param $version integer Which version to get.
131 * @param $want_content boolean
132 * Indicates the caller really wants the page content. If this
133 * flag is not set, the backend is free to skip fetching of the
134 * page content (as that may be expensive). If the backend omits
135 * the content, the backend might still want to set the value of
136 * '%content' to the empty string if it knows there's no content.
138 * @return hash The version data, or false if specified version does not
141 * Some keys which might be present in the $versiondata hash are:
144 * <dd> This is a pseudo-meta-data element (since it's actually
145 * the page data, get it?) containing the page content.
146 * If the content was not fetched, this key may not be present.
148 * For description of other version meta-data see WikiDB_PageRevision::get().
149 * @see WikiDB_PageRevision::get
151 function get_versiondata($pagename, $version, $want_content = false) {
152 trigger_error("virtual", E_USER_ERROR);
156 * Delete page from the database.
158 * Delete page (and all it's revisions) from the database.
160 * @param $pagename string Page name.
162 function delete_page($pagename) {
163 trigger_error("virtual", E_USER_ERROR);
167 * Delete an old revision of a page.
169 * Note that one is never allowed to delete the most recent version,
170 * but that this requirement is enforced by WikiDB not by the backend.
172 * In fact, to be safe, backends should probably allow the deletion of
173 * the most recent version.
175 * @param $pagename string Page name.
176 * @param $version integer Version to delete.
178 function delete_versiondata($pagename, $version) {
179 trigger_error("virtual", E_USER_ERROR);
183 * Create a new page revision.
185 * If the given ($pagename,$version) is already in the database,
186 * this method completely overwrites any stored data for that version.
188 * @param $pagename string Page name.
189 * @param $version int New revisions content.
190 * @param $data hash New revision metadata.
192 * @see get_versiondata
194 function set_versiondata($pagename, $version, $data) {
195 trigger_error("virtual", E_USER_ERROR);
199 * Update page version meta-data.
201 * If the given ($pagename,$version) is already in the database,
202 * this method only changes those meta-data values whose keys are
203 * explicity listed in $newdata.
205 * @param $pagename string Page name.
206 * @param $version int New revisions content.
207 * @param $newdata hash New revision metadata.
208 * @see set_versiondata, get_versiondata
210 function update_versiondata($pagename, $version, $newdata) {
211 $data = $this->get_versiondata($pagename, $version, true);
216 foreach ($newdata as $key => $val) {
222 $this->set_versiondata($pagename, $version, $data);
226 * Set links for page.
228 * @param $pagename string Page name.
230 * @param $links array List of page(names) which page links to.
232 function set_links($pagename, $links) {
233 trigger_error("virtual", E_USER_ERROR);
237 * Find pages which link to or are linked from a page.
239 * @param $pagename string Page name.
240 * @param $reversed boolean True to get backlinks.
242 * FIXME: array or iterator?
243 * @return object A WikiDB_backend_iterator.
245 function get_links($pagename, $reversed) {
246 //FIXME: implement simple (but slow) link finder.
251 * Get all revisions of a page.
253 * @param $pagename string The page name.
254 * @return object A WikiDB_backend_iterator.
256 function get_all_revisions($pagename) {
257 include_once('lib/WikiDB/backend/dumb/AllRevisionsIter.php');
258 return new WikiDB_backend_dumb_AllRevisionsIter($this, $pagename);
262 * Get all pages in the database.
264 * Pages should be returned in alphabetical order if that is
269 * @param $include_defaulted boolean
270 * If set, even pages with no content will be returned
271 * --- but still only if they have at least one revision (not
272 * counting the default revision 0) entered in the database.
274 * Normally pages whose current revision has empty content
275 * are not returned as these pages are considered to be
278 * @return object A WikiDB_backend_iterator.
280 function get_all_pages($include_defaulted) {
281 trigger_error("virtual", E_USER_ERROR);
285 * Title or full text search.
287 * Pages should be returned in alphabetical order if that is
292 * @param $search object A TextSearchQuery object describing what pages
293 * are to be searched for.
295 * @param $fullsearch boolean If true, a full text search is performed,
296 * otherwise a title search is performed.
298 * @return object A WikiDB_backend_iterator.
300 * @see WikiDB::titleSearch
302 function text_search($search = '', $fullsearch = false) {
303 // This is method implements a simple linear search
304 // through all the pages in the database.
306 // It is expected that most backends will overload
307 // method with something more efficient.
308 include_once('lib/WikiDB/backend/dumb/TextSearchIter.php');
309 $pages = $this->get_all_pages(false);
310 return new WikiDB_backend_dumb_TextSearchIter($this, $pages, $search, $fullsearch);
314 * Find pages with highest hit counts.
316 * Find the pages with the highest hit counts. The pages should
317 * be returned in reverse order by hit count.
320 * @param $limit integer No more than this many pages
321 * @return object A WikiDB_backend_iterator.
323 function most_popular($limit) {
324 // This is method fetches all pages, then
325 // sorts them by hit count.
326 // (Not very efficient.)
328 // It is expected that most backends will overload
329 // method with something more efficient.
330 include_once('lib/WikiDB/backend/dumb/MostPopularIter.php');
331 $pages = $this->get_all_pages(false);
333 return new WikiDB_backend_dumb_MostPopularIter($this, $pages, $limit);
337 * Find recent changes.
340 * @param $params hash See WikiDB::mostRecent for a description
341 * of parameters which can be included in this hash.
342 * @return object A WikiDB_backend_iterator.
343 * @see WikiDB::mostRecent
345 function most_recent($params) {
346 // This method is very inefficient and searches through
347 // all pages for the most recent changes.
349 // It is expected that most backends will overload
350 // method with something more efficient.
351 include_once('lib/WikiDB/backend/dumb/MostRecentIter.php');
352 $pages = $this->get_all_pages(true);
353 return new WikiDB_backend_dumb_MostRecentIter($this, $pages, $params);
357 * Lock backend database.
359 * Calls may be nested.
361 * @param $write_lock boolean Unless this is set to false, a write lock
362 * is acquired, otherwise a read lock. If the backend doesn't support
363 * read locking, then it should make a write lock no matter which type
364 * of lock was requested.
366 * All backends <em>should</em> support write locking.
368 function lock($write_lock = true) {
372 * Unlock backend database.
374 * @param $force boolean Normally, the database is not unlocked until
375 * unlock() is called as many times as lock() has been. If $force is
376 * set to true, the the database is unconditionally unlocked.
378 function unlock($force = false) {
389 * Synchronize with filesystem.
391 * This should flush all unwritten data to the filesystem.
397 * Optimize the database.
399 function optimize() {
403 * Check database integrity.
405 * This should check the validity of the internal structure of the database.
406 * Errors should be reported via:
408 * trigger_error("Message goes here.", E_USER_WARNING);
411 * @return boolean True iff database is in a consistent state.
417 * Put the database into a consistent state.
419 * This should put the database into a consistent state.
420 * (I.e. rebuild indexes, etc...)
422 * @return boolean True iff successful.
427 function _parse_searchwords($search) {
428 $search = strtolower(trim($search));
430 return array(array(),array());
432 $words = preg_split('/\s+/', $search);
434 foreach ($words as $key => $word) {
435 if ($word[0] == '-' && $word != '-') {
436 $word = substr($word, 1);
437 $exclude[] = preg_quote($word);
441 return array($words, $exclude);
447 * Iterator returned by backend methods which (possibly) return
450 * FIXME: this should be two seperate classes: page_iter and version_iter.
452 class WikiDB_backend_iterator
455 * Get the next record in the interator set.
457 * This returns a hash. The has may contain the following keys:
459 * <dt> pagename <dt> (string) the page name
460 * <dt> version <dt> (int) the version number
461 * <dt> pagedata <dt> (hash) page meta-data (as returned from backend::get_pagedata().)
462 * <dt> versiondata <dt> (hash) page meta-data (as returned from backend::get_versiondata().)
464 * If this is a page iterator, it must contain the 'pagename' entry --- the others
467 * If this is a version iterator, the 'pagename', 'version', <b>and</b> 'versiondata'
468 * entries are mandatory. ('pagedata' is optional.)
471 trigger_error("virtual", E_USER_ERROR);
475 * Release resources held by this iterator.
481 // (c-file-style: "gnu")
486 // c-hanging-comment-ender-p: nil
487 // indent-tabs-mode: nil