includes/filebackend/filejournal/FileJournal.php

   1 <?php
   2 /**
   3  * @defgroup FileJournal File journal
   4  * @ingroup FileBackend
   5  */
   6
   7 /**
   8  * File operation journaling.
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License along
  21  * with this program; if not, write to the Free Software Foundation, Inc.,
  22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  23  * http://www.gnu.org/copyleft/gpl.html
  24  *
  25  * @file
  26  * @ingroup FileJournal
  27  * @author Aaron Schulz
  28  */
  29
  30 /**
  31  * @brief Class for handling file operation journaling.
  32  *
  33  * Subclasses should avoid throwing exceptions at all costs.
  34  *
  35  * @ingroup FileJournal
  36  * @since 1.20
  37  */
  38 abstract class FileJournal {
  39         protected $backend; // string
  40         protected $ttlDays; // integer
  41
  42         /**
  43          * Construct a new instance from configuration.
  44          * $config includes:
  45          *     'ttlDays' : days to keep log entries around (false means "forever")
  46          *
  47          * @param $config Array
  48          */
  49         protected function __construct( array $config ) {
  50                 $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  51         }
  52
  53         /**
  54          * Create an appropriate FileJournal object from config
  55          *
  56          * @param $config Array
  57          * @param $backend string A registered file backend name
  58          * @throws MWException
  59          * @return FileJournal
  60          */
  61         final public static function factory( array $config, $backend ) {
  62                 $class = $config['class'];
  63                 $jrn = new $class( $config );
  64                 if ( !$jrn instanceof self ) {
  65                         throw new MWException( "Class given is not an instance of FileJournal." );
  66                 }
  67                 $jrn->backend = $backend;
  68                 return $jrn;
  69         }
  70
  71         /**
  72          * Get a statistically unique ID string
  73          *
  74          * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  75          */
  76         final public function getTimestampedUUID() {
  77                 $s = '';
  78                 for ( $i = 0; $i < 5; $i++ ) {
  79                         $s .= mt_rand( 0, 2147483647 );
  80                 }
  81                 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  82                 return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  83         }
  84
  85         /**
  86          * Log changes made by a batch file operation.
  87          * $entries is an array of log entries, each of which contains:
  88          *     op      : Basic operation name (create, update, delete)
  89          *     path    : The storage path of the file
  90          *     newSha1 : The final base 36 SHA-1 of the file
  91          * Note that 'false' should be used as the SHA-1 for non-existing files.
  92          *
  93          * @param $entries Array List of file operations (each an array of parameters)
  94          * @param $batchId string UUID string that identifies the operation batch
  95          * @return Status
  96          */
  97         final public function logChangeBatch( array $entries, $batchId ) {
  98                 if ( !count( $entries ) ) {
  99                         return Status::newGood();
 100                 }
 101                 return $this->doLogChangeBatch( $entries, $batchId );
 102         }
 103
 104         /**
 105          * @see FileJournal::logChangeBatch()
 106          *
 107          * @param $entries Array List of file operations (each an array of parameters)
 108          * @param $batchId string UUID string that identifies the operation batch
 109          * @return Status
 110          */
 111         abstract protected function doLogChangeBatch( array $entries, $batchId );
 112
 113         /**
 114          * Get the position ID of the latest journal entry
 115          *
 116          * @return integer|false
 117          */
 118         final public function getCurrentPosition() {
 119                 return $this->doGetCurrentPosition();
 120         }
 121
 122         /**
 123          * @see FileJournal::getCurrentPosition()
 124          * @return integer|false
 125          */
 126         abstract protected function doGetCurrentPosition();
 127
 128         /**
 129          * Get an array of file change log entries.
 130          * A starting change ID and/or limit can be specified.
 131          *
 132          * The result as a list of associative arrays, each having:
 133          *     id         : unique, monotonic, ID for this change
 134          *     batch_uuid : UUID for an operation batch
 135          *     backend    : the backend name
 136          *     op         : primitive operation (create,update,delete,null)
 137          *     path       : affected storage path
 138          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 139          *     timestamp  : TS_MW timestamp of the batch change
 140
 141          * Also, $next is updated to the ID of the next entry.
 142          *
 143          * @param $start integer Starting change ID or null
 144          * @param $limit integer Maximum number of items to return
 145          * @param &$next string
 146          * @return Array
 147          */
 148         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 149                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 150                 if ( $limit && count( $entries ) > $limit ) {
 151                         $last = array_pop( $entries ); // remove the extra entry
 152                         $next = $last['id']; // update for next call
 153                 } else {
 154                         $next = null; // end of list
 155                 }
 156                 return $entries;
 157         }
 158
 159         /**
 160          * @see FileJournal::getChangeEntries()
 161          * @return Array
 162          */
 163         abstract protected function doGetChangeEntries( $start, $limit );
 164
 165         /**
 166          * Purge any old log entries
 167          *
 168          * @return Status
 169          */
 170         final public function purgeOldLogs() {
 171                 return $this->doPurgeOldLogs();
 172         }
 173
 174         /**
 175          * @see FileJournal::purgeOldLogs()
 176          * @return Status
 177          */
 178         abstract protected function doPurgeOldLogs();
 179 }
 180
 181 /**
 182  * Simple version of FileJournal that does nothing
 183  * @since 1.20
 184  */
 185 class NullFileJournal extends FileJournal {
 186         /**
 187          * @see FileJournal::doLogChangeBatch()
 188          * @param $entries array
 189          * @param $batchId string
 190          * @return Status
 191          */
 192         protected function doLogChangeBatch( array $entries, $batchId ) {
 193                 return Status::newGood();
 194         }
 195
 196         /**
 197          * @see FileJournal::doGetCurrentPosition()
 198          * @return integer|false
 199          */
 200         protected function doGetCurrentPosition() {
 201                 return false;
 202         }
 203
 204         /**
 205          * @see FileJournal::doGetChangeEntries()
 206          * @return Array
 207          */
 208         protected function doGetChangeEntries( $start, $limit ) {
 209                 return array();
 210         }
 211
 212         /**
 213          * @see FileJournal::doPurgeOldLogs()
 214          * @return Status
 215          */
 216         protected function doPurgeOldLogs() {
 217                 return Status::newGood();
 218         }
 219 }