* Renamed FileBackend functions internal to FileBackend/FileOp, making their usage...

* Added convenience functions to FileBackendBase for basic file ops. Previously, doOperation() was the only convenience function...give it some friends :)
* More documentation comments.

diff --git a/includes/filerepo/backend/FSFileBackend.php b/includes/filerepo/backend/FSFileBackend.php
index e803467..83298fe 100644 (file)
--- a/includes/filerepo/backend/FSFileBackend.php
+++ b/includes/filerepo/backend/FSFileBackend.php
@@ -48,9 +48,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doStore()
+        * @see FileBackend::doStoreInternal()
         */
-       protected function doStore( array $params ) {
+       protected function doStoreInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $dest ) = $this->resolveStoragePath( $params['dst'] );
@@ -92,9 +92,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doCopy()
+        * @see FileBackend::doCopyInternal()
         */
-       protected function doCopy( array $params ) {
+       protected function doCopyInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $source ) = $this->resolveStoragePath( $params['src'] );
@@ -143,9 +143,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doMove()
+        * @see FileBackend::doMoveInternal()
         */
-       protected function doMove( array $params ) {
+       protected function doMoveInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $source ) = $this->resolveStoragePath( $params['src'] );
@@ -195,9 +195,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doDelete()
+        * @see FileBackend::doDeleteInternal()
         */
-       protected function doDelete( array $params ) {
+       protected function doDeleteInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $source ) = $this->resolveStoragePath( $params['src'] );
@@ -225,9 +225,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doConcatenate()
+        * @see FileBackend::doConcatenateInternal()
         */
-       protected function doConcatenate( array $params ) {
+       protected function doConcatenateInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $dest ) = $this->resolveStoragePath( $params['dst'] );
@@ -326,9 +326,9 @@ class FSFileBackend extends FileBackend {
        }
 
        /**
-        * @see FileBackend::doCreate()
+        * @see FileBackend::doCreateInternal()
         */
-       protected function doCreate( array $params ) {
+       protected function doCreateInternal( array $params ) {
                $status = Status::newGood();
 
                list( $c, $dest ) = $this->resolveStoragePath( $params['dst'] );

diff --git a/includes/filerepo/backend/FileBackend.php b/includes/filerepo/backend/FileBackend.php
index 9b695b6..4b260e6 100644 (file)
--- a/includes/filerepo/backend/FileBackend.php
+++ b/includes/filerepo/backend/FileBackend.php
@@ -147,16 +147,110 @@ abstract class FileBackendBase {
        abstract public function doOperations( array $ops, array $opts = array() );
 
        /**
-        * Same as doOperations() except it takes a single operation array
+        * Same as doOperations() except it takes a single operation.
+        * If you are doing a batch of operations that should either
+        * all succeed or all fail, then use that function instead.
         *
-        * @param $op Array
-        * @param $opts Array
+        * @see FileBackendBase::doOperations()
+        *
+        * @param $op Array Operation
+        * @param $opts Array Operation options
         * @return Status
         */
        final public function doOperation( array $op, array $opts = array() ) {
                return $this->doOperations( array( $op ), $opts );
        }
 
+       /**
+        * Performs a single store operation.
+        * This sets $params['op'] to 'store' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function store( array $params, array $opts = array() ) {
+               $params['op'] = 'store';
+               return $this->doOperation( $params, $opts );
+       }
+
+       /**
+        * Performs a single copy operation.
+        * This sets $params['op'] to 'copy' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function copy( array $params, array $opts = array() ) {
+               $params['op'] = 'copy';
+               return $this->doOperation( $params, $opts );
+       }
+
+       /**
+        * Performs a single move operation.
+        * This sets $params['op'] to 'move' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function move( array $params, array $opts = array() ) {
+               $params['op'] = 'move';
+               return $this->doOperation( $params, $opts );
+       }
+
+       /**
+        * Performs a single delete operation.
+        * This sets $params['op'] to 'delete' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function delete( array $params, array $opts = array() ) {
+               $params['op'] = 'delete';
+               return $this->doOperation( $params, $opts );
+       }
+
+       /**
+        * Performs a single create operation.
+        * This sets $params['op'] to 'create' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function create( array $params, array $opts = array() ) {
+               $params['op'] = 'create';
+               return $this->doOperation( $params, $opts );
+       }
+
+       /**
+        * Performs a single concatenate operation.
+        * This sets $params['op'] to 'concatenate' and passes it to doOperation().
+        *
+        * @see FileBackendBase::doOperation()
+        *
+        * @param $params Array Operation parameters
+        * @param $opts Array Operation options
+        * @return Status
+        */
+       final public function concatenate( array $params, array $opts = array() ) {
+               $params['op'] = 'concatenate';
+               return $this->doOperation( $params, $opts );
+       }
+
        /**
         * Prepare a storage path for usage. This will create containers
         * that don't yet exist or, on FS backends, create parent directories.
@@ -371,16 +465,16 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function store( array $params ) {
-               $status = $this->doStore( $params );
+       final public function storeInternal( array $params ) {
+               $status = $this->doStoreInternal( $params );
                $this->clearCache( array( $params['dst'] ) );
                return $status;
        }
 
        /**
-        * @see FileBackend::store()
+        * @see FileBackend::storeInternal()
         */
-       abstract protected function doStore( array $params );
+       abstract protected function doStoreInternal( array $params );
 
        /**
         * Copy a file from one storage path to another in the backend.
@@ -393,16 +487,16 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function copy( array $params ) {
-               $status = $this->doCopy( $params );
+       final public function copyInternal( array $params ) {
+               $status = $this->doCopyInternal( $params );
                $this->clearCache( array( $params['dst'] ) );
                return $status;
        }
 
        /**
-        * @see FileBackend::copy()
+        * @see FileBackend::copyInternal()
         */
-       abstract protected function doCopy( array $params );
+       abstract protected function doCopyInternal( array $params );
 
        /**
         * Delete a file at the storage path.
@@ -413,8 +507,8 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function delete( array $params ) {
-               $status = $this->doDelete( $params );
+       final public function deleteInternal( array $params ) {
+               $status = $this->doDeleteInternal( $params );
                $this->clearCache( array( $params['src'] ) );
                return $status;
        }
@@ -422,7 +516,7 @@ abstract class FileBackend extends FileBackendBase {
        /**
         * @see FileBackend::delete()
         */
-       abstract protected function doDelete( array $params );
+       abstract protected function doDeleteInternal( array $params );
 
        /**
         * Move a file from one storage path to another in the backend.
@@ -435,8 +529,8 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function move( array $params ) {
-               $status = $this->doMove( $params );
+       final public function moveInternal( array $params ) {
+               $status = $this->doMoveInternal( $params );
                $this->clearCache( array( $params['src'], $params['dst'] ) );
                return $status;
        }
@@ -444,14 +538,14 @@ abstract class FileBackend extends FileBackendBase {
        /**
         * @see FileBackend::move()
         */
-       protected function doMove( array $params ) {
+       protected function doMoveInternal( array $params ) {
                // Copy source to dest
-               $status = $this->backend->copy( $params );
+               $status = $this->backend->copyInternal( $params );
                if ( !$status->isOK() ) {
                        return $status;
                }
                // Delete source (only fails due to races or medium going down)
-               $status->merge( $this->backend->delete( array( 'src' => $params['src'] ) ) );
+               $status->merge( $this->backend->deleteInternal( array( 'src' => $params['src'] ) ) );
                $status->setResult( true, $status->value ); // ignore delete() errors
                return $status;
        }
@@ -467,8 +561,8 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function concatenate( array $params ) {
-               $status = $this->doConcatenate( $params );
+       final public function concatenateInternal( array $params ) {
+               $status = $this->doConcatenateInternal( $params );
                $this->clearCache( array( $params['dst'] ) );
                return $status;
        }
@@ -476,7 +570,7 @@ abstract class FileBackend extends FileBackendBase {
        /**
         * @see FileBackend::concatenate()
         */
-       abstract protected function doConcatenate( array $params );
+       abstract protected function doConcatenateInternal( array $params );
 
        /**
         * Create a file in the backend with the given contents.
@@ -489,8 +583,8 @@ abstract class FileBackend extends FileBackendBase {
         * @param $params Array
         * @return Status
         */
-       final public function create( array $params ) {
-               $status = $this->doCreate( $params );
+       final public function createInternal( array $params ) {
+               $status = $this->doCreateInternal( $params );
                $this->clearCache( array( $params['dst'] ) );
                return $status;
        }
@@ -498,7 +592,7 @@ abstract class FileBackend extends FileBackendBase {
        /**
         * @see FileBackend::create()
         */
-       abstract protected function doCreate( array $params );
+       abstract protected function doCreateInternal( array $params );
 
        /**
         * @see FileBackendBase::prepare()

diff --git a/includes/filerepo/backend/FileOp.php b/includes/filerepo/backend/FileOp.php
index d5059d6..f6715f1 100644 (file)
--- a/includes/filerepo/backend/FileOp.php
+++ b/includes/filerepo/backend/FileOp.php
@@ -429,7 +429,7 @@ abstract class FileOp {
                                'dst'           => $this->params['src'],
                                'overwriteDest' => true
                        );
-                       $status = $this->backend->store( $params );
+                       $status = $this->backend->storeInternal( $params );
                        if ( !$status->isOK() ) {
                                return $status;
                        }
@@ -451,7 +451,7 @@ abstract class FileOp {
                                'dst'           => $this->params['dst'],
                                'overwriteDest' => true
                        );
-                       $status = $this->backend->store( $params );
+                       $status = $this->backend->storeInternal( $params );
                        if ( !$status->isOK() ) {
                                return $status;
                        }
@@ -503,7 +503,7 @@ abstract class FileOp {
 
 /**
  * Store a file into the backend from a file on the file system.
- * Parameters similar to FileBackend::store(), which include:
+ * Parameters similar to FileBackend::storeInternal(), which include:
  *     src           : source path on file system
  *     dst           : destination storage path
  *     overwriteDest : do nothing and pass if an identical file exists at destination
@@ -542,7 +542,7 @@ class StoreFileOp extends FileOp {
                }
                // Store the file at the destination
                if ( !$this->destSameAsSource ) {
-                       $status->merge( $this->backend->store( $this->params ) );
+                       $status->merge( $this->backend->storeInternal( $this->params ) );
                }
                return $status;
        }
@@ -602,7 +602,7 @@ class CreateFileOp extends FileOp {
                }
                // Create the file at the destination
                if ( !$this->destSameAsSource ) {
-                       $status->merge( $this->backend->create( $this->params ) );
+                       $status->merge( $this->backend->createInternal( $this->params ) );
                }
                return $status;
        }
@@ -667,7 +667,7 @@ class CopyFileOp extends FileOp {
                }
                // Copy the file into the destination
                if ( !$this->destSameAsSource ) {
-                       $status->merge( $this->backend->copy( $this->params ) );
+                       $status->merge( $this->backend->copyInternal( $this->params ) );
                }
                return $status;
        }
@@ -737,7 +737,7 @@ class MoveFileOp extends FileOp {
                }
                if ( !$this->destSameAsSource ) {
                        // Move the file into the destination
-                       $status->merge( $this->backend->move( $this->params ) );
+                       $status->merge( $this->backend->moveInternal( $this->params ) );
                } else {
                        // Create a source backup copy as needed
                        $status->merge( $this->backupSource() );
@@ -746,7 +746,7 @@ class MoveFileOp extends FileOp {
                        }
                        // Just delete source as the destination needs no changes
                        $params = array( 'src' => $this->params['src'] );
-                       $status->merge( $this->backend->delete( $params ) );
+                       $status->merge( $this->backend->deleteInternal( $params ) );
                        if ( !$status->isOK() ) {
                                return $status;
                        }
@@ -762,7 +762,7 @@ class MoveFileOp extends FileOp {
                                'src' => $this->params['dst'],
                                'dst' => $this->params['src']
                        );
-                       $status->merge( $this->backend->move( $params ) );
+                       $status->merge( $this->backend->moveInternal( $params ) );
                        if ( !$status->isOK() ) {
                                return $status; // also can't restore any dest file
                        }
@@ -830,7 +830,7 @@ class ConcatenateFileOp extends FileOp {
                        }
                }
                // Concatenate the file at the destination
-               $status->merge( $this->backend->concatenate( $this->params ) );
+               $status->merge( $this->backend->concatenateInternal( $this->params ) );
                return $status;
        }
 
@@ -890,7 +890,7 @@ class DeleteFileOp extends FileOp {
                                return $status;
                        }
                        // Delete the source file
-                       $status->merge( $this->backend->delete( $this->params ) );
+                       $status->merge( $this->backend->deleteInternal( $this->params ) );
                        if ( !$status->isOK() ) {
                                return $status;
                        }