* - copy
* - move
* - delete
+ * - describe (since 1.21)
* - null
*
* a) Create a new file in storage with the contents of a string
* 'content' => <string of new file contents>,
* 'overwrite' => <boolean>,
* 'overwriteSame' => <boolean>,
- * 'disposition' => <Content-Disposition header value>
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map> # since 1.21
* );
* @endcode
*
* 'dst' => <storage path>,
* 'overwrite' => <boolean>,
* 'overwriteSame' => <boolean>,
- * 'disposition' => <Content-Disposition header value>
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map> # since 1.21
* )
* @endcode
*
* 'dst' => <storage path>,
* 'overwrite' => <boolean>,
* 'overwriteSame' => <boolean>,
+ * 'ignoreMissingSource' => <boolean>, # since 1.21
* 'disposition' => <Content-Disposition header value>
* )
* @endcode
* 'dst' => <storage path>,
* 'overwrite' => <boolean>,
* 'overwriteSame' => <boolean>,
+ * 'ignoreMissingSource' => <boolean>, # since 1.21
* 'disposition' => <Content-Disposition header value>
* )
* @endcode
* )
* @endcode
*
- * f) Do nothing (no-op)
+ * f) Update metadata for a file within storage
+ * @code
+ * array(
+ * 'op' => 'describe',
+ * 'src' => <storage path>,
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map>
+ * )
+ * @endcode
+ *
+ * g) Do nothing (no-op)
* @code
* array(
* 'op' => 'null',
* - overwriteSame : An error will not be given if a file already
* exists at the destination that has the same
* contents as the new contents to be written there.
- * - disposition : When supplied, the backend will add a Content-Disposition
+ * - disposition : If supplied, the backend will return a Content-Disposition
* header when GETs/HEADs of the destination file are made.
- * Backends that don't support file metadata will ignore this.
- * See http://tools.ietf.org/html/rfc6266 (since 1.20).
+ * Backends that don't support metadata ignore this.
+ * See http://tools.ietf.org/html/rfc6266. (since 1.20)
+ * - headers : If supplied, the backend will return these headers when
+ * GETs/HEADs of the destination file are made. Header values
+ * should be smaller than 256 bytes, often options or numbers.
+ * Existing headers will remain, but these will replace any
+ * conflicting previous headers, and headers will be removed
+ * if they are set to an empty string.
+ * Backends that don't support metadata ignore this. (since 1.21)
*
* $opts is an associative of boolean flags, including:
* - force : Operation precondition errors no longer trigger an abort.
* - nonJournaled : Don't log this operation batch in the file journal.
* This limits the ability of recovery scripts.
* - parallelize : Try to do operations in parallel when possible.
- * - bypassReadOnly : Allow writes in read-only mode (since 1.20).
+ * - bypassReadOnly : Allow writes in read-only mode. (since 1.20)
* - preserveCache : Don't clear the process cache before checking files.
* This should only be used if all entries in the process
- * cache were added after the files were already locked (since 1.20).
+ * cache were added after the files were already locked. (since 1.20)
*
* @remarks Remarks on locking:
* File system paths given to operations should refer to files that are
return $this->doOperation( array( 'op' => 'delete' ) + $params, $opts );
}
+ /**
+ * Performs a single describe operation.
+ * This sets $params['op'] to 'describe' and passes it to doOperation().
+ *
+ * @see FileBackend::doOperation()
+ *
+ * @param $params Array Operation parameters
+ * @param $opts Array Operation options
+ * @return Status
+ * @since 1.21
+ */
+ final public function describe( array $params, array $opts = array() ) {
+ return $this->doOperation( array( 'op' => 'describe' ) + $params, $opts );
+ }
+
/**
* Perform a set of independent file operations on some files.
*
* - copy
* - move
* - delete
+ * - describe (since 1.21)
* - null
*
* a) Create a new file in storage with the contents of a string
* 'op' => 'create',
* 'dst' => <storage path>,
* 'content' => <string of new file contents>,
- * 'disposition' => <Content-Disposition header value>
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map> # since 1.21
* )
* @endcode
+ *
* b) Copy a file system file into storage
* @code
* array(
* 'op' => 'store',
* 'src' => <file system path>,
* 'dst' => <storage path>,
- * 'disposition' => <Content-Disposition header value>
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map> # since 1.21
* )
* @endcode
+ *
* c) Copy a file within storage
* @code
* array(
* 'op' => 'copy',
* 'src' => <storage path>,
* 'dst' => <storage path>,
+ * 'ignoreMissingSource' => <boolean>, # since 1.21
* 'disposition' => <Content-Disposition header value>
* )
* @endcode
+ *
* d) Move a file within storage
* @code
* array(
* 'op' => 'move',
* 'src' => <storage path>,
* 'dst' => <storage path>,
+ * 'ignoreMissingSource' => <boolean>, # since 1.21
* 'disposition' => <Content-Disposition header value>
* )
* @endcode
+ *
* e) Delete a file within storage
* @code
* array(
* 'ignoreMissingSource' => <boolean>
* )
* @endcode
- * f) Do nothing (no-op)
+ *
+ * f) Update metadata for a file within storage
+ * @code
+ * array(
+ * 'op' => 'describe',
+ * 'src' => <storage path>,
+ * 'disposition' => <Content-Disposition header value>,
+ * 'headers' => <HTTP header name/value map>
+ * )
+ * @endcode
+ *
+ * g) Do nothing (no-op)
* @code
* array(
* 'op' => 'null',
* header when GETs/HEADs of the destination file are made.
* Backends that don't support file metadata will ignore this.
* See http://tools.ietf.org/html/rfc6266 (since 1.20).
+ * - headers : If supplied, the backend will return these headers when
+ * GETs/HEADs of the destination file are made. Header values
+ * should be smaller than 256 bytes, often options or numbers.
+ * Existing headers will remain, but these will replace any
+ * conflicting previous headers, and headers will be removed
+ * if they are set to an empty string.
+ * Backends that don't support metadata ignore this. (since 1.21)
*
* $opts is an associative of boolean flags, including:
* - bypassReadOnly : Allow writes in read-only mode (since 1.20)
return $this->doQuickOperation( array( 'op' => 'delete' ) + $params );
}
+ /**
+ * Performs a single quick describe operation.
+ * This sets $params['op'] to 'describe' and passes it to doQuickOperation().
+ *
+ * @see FileBackend::doQuickOperation()
+ *
+ * @param $params Array Operation parameters
+ * @return Status
+ * @since 1.21
+ */
+ final public function quickDescribe( array $params ) {
+ return $this->doQuickOperation( array( 'op' => 'describe' ) + $params );
+ }
+
/**
* Concatenate a list of storage files into a single file system file.
* The target path should refer to a file that is already locked or
* otherwise safe from modification from other processes. Normally,
* the file will be a new temp file, which should be adequate.
*
+ * If a callback function is given, it will be called each time a segment is
+ * appended and when the overall concatenate operation completes or fails.
+ * The arguments passed in are:
+ * - 1) A Status object containing errors if any problems occurred.
+ * - 2) The index of the relevant segment (starting at 1) if a segment was appended
+ * (including the last one) or null in the case of overall success or failure.
+ * When a good Status is returned with a null segment, then the operation completed.
+ * Callbacks should generally avoid throwing exceptions.
+ *
* @param $params Array Operation parameters
* $params include:
* - srcs : ordered source storage paths (e.g. chunk1, chunk2, ...)
* - dst : file system path to 0-byte temp file
* - parallelize : try to do operations in parallel when possible
+ * - callback : closure called when chunks are appended and on success/failure
* @return Status
*/
abstract public function concatenate( array $params );
*/
abstract public function getLocalCopyMulti( array $params );
+ /**
+ * Return an HTTP URL to a given file that requires no authentication to use.
+ * The URL may be pre-authenticated (via some token in the URL) and temporary.
+ * This will return null if the backend cannot make an HTTP URL for the file.
+ *
+ * This is useful for key/value stores when using scripts that seek around
+ * large files and those scripts (and the backend) support HTTP Range headers.
+ * Otherwise, one would need to use getLocalReference(), which involves loading
+ * the entire file on to local disk.
+ *
+ * @param $params Array
+ * $params include:
+ * - src : source storage path
+ * @return string|null
+ * @since 1.21
+ */
+ abstract public function getFileHttpUrl( array $params );
+
/**
* Check if a directory exists at a given storage path.
* Backends using key/value stores will check if the path is a
dépôts / lhc / web / wiklou.git / blobdiff