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 string $backend 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 array $entries List of file operations (each an array of parameters)
  94          * @param string $batchId 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 array $entries List of file operations (each an array of parameters)
 108          * @param string $batchId 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 the position ID of the latest journal entry at some point in time
 130          *
 131          * @param $time integer|string timestamp
 132          * @return integer|false
 133          */
 134         final public function getPositionAtTime( $time ) {
 135                 return $this->doGetPositionAtTime( $time );
 136         }
 137
 138         /**
 139          * @see FileJournal::getPositionAtTime()
 140          * @param $time integer|string timestamp
 141          * @return integer|false
 142          */
 143         abstract protected function doGetPositionAtTime( $time );
 144
 145         /**
 146          * Get an array of file change log entries.
 147          * A starting change ID and/or limit can be specified.
 148          *
 149          * The result as a list of associative arrays, each having:
 150          *     id         : unique, monotonic, ID for this change
 151          *     batch_uuid : UUID for an operation batch
 152          *     backend    : the backend name
 153          *     op         : primitive operation (create,update,delete,null)
 154          *     path       : affected storage path
 155          *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 156          *     timestamp  : TS_MW timestamp of the batch change
 157
 158          * Also, $next is updated to the ID of the next entry.
 159          *
 160          * @param $start integer Starting change ID or null
 161          * @param $limit integer Maximum number of items to return
 162          * @param &$next string
 163          * @return Array
 164          */
 165         final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 166                 $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 167                 if ( $limit && count( $entries ) > $limit ) {
 168                         $last = array_pop( $entries ); // remove the extra entry
 169                         $next = $last['id']; // update for next call
 170                 } else {
 171                         $next = null; // end of list
 172                 }
 173                 return $entries;
 174         }
 175
 176         /**
 177          * @see FileJournal::getChangeEntries()
 178          * @return Array
 179          */
 180         abstract protected function doGetChangeEntries( $start, $limit );
 181
 182         /**
 183          * Purge any old log entries
 184          *
 185          * @return Status
 186          */
 187         final public function purgeOldLogs() {
 188                 return $this->doPurgeOldLogs();
 189         }
 190
 191         /**
 192          * @see FileJournal::purgeOldLogs()
 193          * @return Status
 194          */
 195         abstract protected function doPurgeOldLogs();
 196 }
 197
 198 /**
 199  * Simple version of FileJournal that does nothing
 200  * @since 1.20
 201  */
 202 class NullFileJournal extends FileJournal {
 203         /**
 204          * @see FileJournal::doLogChangeBatch()
 205          * @param $entries array
 206          * @param $batchId string
 207          * @return Status
 208          */
 209         protected function doLogChangeBatch( array $entries, $batchId ) {
 210                 return Status::newGood();
 211         }
 212
 213         /**
 214          * @see FileJournal::doGetCurrentPosition()
 215          * @return integer|false
 216          */
 217         protected function doGetCurrentPosition() {
 218                 return false;
 219         }
 220
 221         /**
 222          * @see FileJournal::doGetPositionAtTime()
 223          * @param $time integer|string timestamp
 224          * @return integer|false
 225          */
 226         protected function doGetPositionAtTime( $time ) {
 227                 return false;
 228         }
 229
 230         /**
 231          * @see FileJournal::doGetChangeEntries()
 232          * @return Array
 233          */
 234         protected function doGetChangeEntries( $start, $limit ) {
 235                 return array();
 236         }
 237
 238         /**
 239          * @see FileJournal::doPurgeOldLogs()
 240          * @return Status
 241          */
 242         protected function doPurgeOldLogs() {
 243                 return Status::newGood();
 244         }
 245 }