3 * @defgroup FileJournal File journal
8 * File operation journaling.
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.
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.
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
26 * @ingroup FileJournal
27 * @author Aaron Schulz
31 * @brief Class for handling file operation journaling.
33 * Subclasses should avoid throwing exceptions at all costs.
35 * @ingroup FileJournal
38 abstract class FileJournal
{
39 protected $backend; // string
40 protected $ttlDays; // integer
43 * Construct a new instance from configuration.
45 * 'ttlDays' : days to keep log entries around (false means "forever")
47 * @param $config Array
49 protected function __construct( array $config ) {
50 $this->ttlDays
= isset( $config['ttlDays'] ) ?
$config['ttlDays'] : false;
54 * Create an appropriate FileJournal object from config
56 * @param $config Array
57 * @param $backend string A registered file backend name
60 final public static function factory( array $config, $backend ) {
61 $class = $config['class'];
62 $jrn = new $class( $config );
63 if ( !$jrn instanceof self
) {
64 throw new MWException( "Class given is not an instance of FileJournal." );
66 $jrn->backend
= $backend;
71 * Get a statistically unique ID string
73 * @return string <9 char TS_MW timestamp in base 36><22 random base 36 chars>
75 final public function getTimestampedUUID() {
77 for ( $i = 0; $i < 5; $i++
) {
78 $s .= mt_rand( 0, 2147483647 );
80 $s = wfBaseConvert( sha1( $s ), 16, 36, 31 );
81 return substr( wfBaseConvert( wfTimestamp( TS_MW
), 10, 36, 9 ) . $s, 0, 31 );
85 * Log changes made by a batch file operation.
86 * $entries is an array of log entries, each of which contains:
87 * op : Basic operation name (create, store, copy, delete)
88 * path : The storage path of the file
89 * newSha1 : The final base 36 SHA-1 of the file
90 * Note that 'false' should be used as the SHA-1 for non-existing files.
92 * @param $entries Array List of file operations (each an array of parameters)
93 * @param $batchId string UUID string that identifies the operation batch
96 final public function logChangeBatch( array $entries, $batchId ) {
97 if ( !count( $entries ) ) {
98 return Status
::newGood();
100 return $this->doLogChangeBatch( $entries, $batchId );
104 * @see FileJournal::logChangeBatch()
106 * @param $entries Array List of file operations (each an array of parameters)
107 * @param $batchId string UUID string that identifies the operation batch
110 abstract protected function doLogChangeBatch( array $entries, $batchId );
113 * Purge any old log entries
117 final public function purgeOldLogs() {
118 return $this->doPurgeOldLogs();
122 * @see FileJournal::purgeOldLogs()
125 abstract protected function doPurgeOldLogs();
129 * Simple version of FileJournal that does nothing
132 class NullFileJournal
extends FileJournal
{
134 * @see FileJournal::logChangeBatch()
137 protected function doLogChangeBatch( array $entries, $batchId ) {
138 return Status
::newGood();
142 * @see FileJournal::purgeOldLogs()
145 protected function doPurgeOldLogs() {
146 return Status
::newGood();