[Summary view] [Print] [Text view]

   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      /** @var string */
  40      protected $backend;
  41  
  42      /** @var int */
  43      protected $ttlDays;
  44  
  45      /**
  46       * Construct a new instance from configuration.
  47       *
  48       * @param array $config Includes:
  49       *     'ttlDays' : days to keep log entries around (false means "forever")
  50       */
  51  	protected function __construct( array $config ) {
  52          $this->ttlDays = isset( $config['ttlDays'] ) ? $config['ttlDays'] : false;
  53      }
  54  
  55      /**
  56       * Create an appropriate FileJournal object from config
  57       *
  58       * @param array $config
  59       * @param string $backend A registered file backend name
  60       * @throws MWException
  61       * @return FileJournal
  62       */
  63  	final public static function factory( array $config, $backend ) {
  64          $class = $config['class'];
  65          $jrn = new $class( $config );
  66          if ( !$jrn instanceof self ) {
  67              throw new MWException( "Class given is not an instance of FileJournal." );
  68          }
  69          $jrn->backend = $backend;
  70  
  71          return $jrn;
  72      }
  73  
  74      /**
  75       * Get a statistically unique ID string
  76       *
  77       * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
  78       */
  79  	final public function getTimestampedUUID() {
  80          $s = '';
  81          for ( $i = 0; $i < 5; $i++ ) {
  82              $s .= mt_rand( 0, 2147483647 );
  83          }
  84          $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
  85  
  86          return substr( wfBaseConvert( wfTimestamp( TS_MW ), 10, 36, 9 ) . $s, 0, 31 );
  87      }
  88  
  89      /**
  90       * Log changes made by a batch file operation.
  91       *
  92       * @param array $entries List of file operations (each an array of parameters) which contain:
  93       *     op      : Basic operation name (create, update, delete)
  94       *     path    : The storage path of the file
  95       *     newSha1 : The final base 36 SHA-1 of the file
  96       *   Note that 'false' should be used as the SHA-1 for non-existing files.
  97       * @param string $batchId UUID string that identifies the operation batch
  98       * @return Status
  99       */
 100  	final public function logChangeBatch( array $entries, $batchId ) {
 101          if ( !count( $entries ) ) {
 102              return Status::newGood();
 103          }
 104  
 105          return $this->doLogChangeBatch( $entries, $batchId );
 106      }
 107  
 108      /**
 109       * @see FileJournal::logChangeBatch()
 110       *
 111       * @param array $entries List of file operations (each an array of parameters)
 112       * @param string $batchId UUID string that identifies the operation batch
 113       * @return Status
 114       */
 115      abstract protected function doLogChangeBatch( array $entries, $batchId );
 116  
 117      /**
 118       * Get the position ID of the latest journal entry
 119       *
 120       * @return int|bool
 121       */
 122  	final public function getCurrentPosition() {
 123          return $this->doGetCurrentPosition();
 124      }
 125  
 126      /**
 127       * @see FileJournal::getCurrentPosition()
 128       * @return int|bool
 129       */
 130      abstract protected function doGetCurrentPosition();
 131  
 132      /**
 133       * Get the position ID of the latest journal entry at some point in time
 134       *
 135       * @param int|string $time Timestamp
 136       * @return int|bool
 137       */
 138  	final public function getPositionAtTime( $time ) {
 139          return $this->doGetPositionAtTime( $time );
 140      }
 141  
 142      /**
 143       * @see FileJournal::getPositionAtTime()
 144       * @param int|string $time Timestamp
 145       * @return int|bool
 146       */
 147      abstract protected function doGetPositionAtTime( $time );
 148  
 149      /**
 150       * Get an array of file change log entries.
 151       * A starting change ID and/or limit can be specified.
 152       *
 153       * @param int $start Starting change ID or null
 154       * @param int $limit Maximum number of items to return
 155       * @param string &$next Updated to the ID of the next entry.
 156       * @return array List of associative arrays, each having:
 157       *     id         : unique, monotonic, ID for this change
 158       *     batch_uuid : UUID for an operation batch
 159       *     backend    : the backend name
 160       *     op         : primitive operation (create,update,delete,null)
 161       *     path       : affected storage path
 162       *     new_sha1   : base 36 sha1 of the new file had the operation succeeded
 163       *     timestamp  : TS_MW timestamp of the batch change
 164       *   Also, $next is updated to the ID of the next entry.
 165       */
 166  	final public function getChangeEntries( $start = null, $limit = 0, &$next = null ) {
 167          $entries = $this->doGetChangeEntries( $start, $limit ? $limit + 1 : 0 );
 168          if ( $limit && count( $entries ) > $limit ) {
 169              $last = array_pop( $entries ); // remove the extra entry
 170              $next = $last['id']; // update for next call
 171          } else {
 172              $next = null; // end of list
 173          }
 174  
 175          return $entries;
 176      }
 177  
 178      /**
 179       * @see FileJournal::getChangeEntries()
 180       * @param int $start
 181       * @param int $limit
 182       * @return array
 183       */
 184      abstract protected function doGetChangeEntries( $start, $limit );
 185  
 186      /**
 187       * Purge any old log entries
 188       *
 189       * @return Status
 190       */
 191  	final public function purgeOldLogs() {
 192          return $this->doPurgeOldLogs();
 193      }
 194  
 195      /**
 196       * @see FileJournal::purgeOldLogs()
 197       * @return Status
 198       */
 199      abstract protected function doPurgeOldLogs();
 200  }
 201  
 202  /**
 203   * Simple version of FileJournal that does nothing
 204   * @since 1.20
 205   */
 206  class NullFileJournal extends FileJournal {
 207      /**
 208       * @see FileJournal::doLogChangeBatch()
 209       * @param array $entries
 210       * @param string $batchId
 211       * @return Status
 212       */
 213  	protected function doLogChangeBatch( array $entries, $batchId ) {
 214          return Status::newGood();
 215      }
 216  
 217      /**
 218       * @see FileJournal::doGetCurrentPosition()
 219       * @return int|bool
 220       */
 221  	protected function doGetCurrentPosition() {
 222          return false;
 223      }
 224  
 225      /**
 226       * @see FileJournal::doGetPositionAtTime()
 227       * @param int|string $time Timestamp
 228       * @return int|bool
 229       */
 230  	protected function doGetPositionAtTime( $time ) {
 231          return false;
 232      }
 233  
 234      /**
 235       * @see FileJournal::doGetChangeEntries()
 236       * @param int $start
 237       * @param int $limit
 238       * @return array
 239       */
 240  	protected function doGetChangeEntries( $start, $limit ) {
 241          return array();
 242      }
 243  
 244      /**
 245       * @see FileJournal::doPurgeOldLogs()
 246       * @return Status
 247       */
 248  	protected function doPurgeOldLogs() {
 249          return Status::newGood();
 250      }
 251  }