/kernel/private/interfaces/ezclusterfilehandlerinterface.php
PHP | 401 lines | 47 code | 42 blank | 312 comment | 0 complexity | 644d65cb2d90c9fce477355f9b67de5f MD5 | raw file
- <?php
- /**
- * File containing the eZClusterFileHandlerInterface interface.
- *
- * @copyright Copyright (C) 1999-2012 eZ Systems AS. All rights reserved.
- * @license http://www.gnu.org/licenses/gpl-2.0.txt GNU General Public License v2
- * @version //autogentag//
- * @package lib
- */
- /**
- * Cluster file handlers interface
- */
- interface eZClusterFileHandlerInterface
- {
- /**
- * Stores a file by path to the backend
- *
- * @param string $filePath Path to the file being stored.
- * @param string $scope Means something like "file category". May be used
- * to clean caches of a certain type.
- * @param bool $delete true if the file should be deleted after storing.
- * @param string $datatype
- *
- * @return void
- */
- public function fileStore( $filePath, $scope = false, $delete = false, $datatype = false );
- /**
- *
- * Store file contents.
- *
- * @param string $filePath Path to the file being stored.
- * @param string $contents Binary file content
- * @param string $scope "file category". May be used by cache management
- * @param string $datatype Datatype for the file. Also used to clean cache up
- *
- * @return void
- */
- public function fileStoreContents( $filePath, $contents, $scope = false, $datatype = false );
- /**
- * Store file contents using binary data
- *
- * @param string $contents Binary file content
- * @param string $scope "file category". May be used by cache management
- * @param string $datatype Datatype for the file. Also used to clean cache up
- * @param bool $storeLocally If true the file will also be stored on the
- * local file system.
- */
- public function storeContents( $contents, $scope = false, $datatype = false, $storeLocally = false );
- /**
- * Fetches a file locally
- *
- * @param string $filePath
- *
- * @return string|false the file path, or false if fetching failed
- */
- public function fileFetch( $filePath );
- /**
- * Handles cache requests / write operations
- *
- * Creates a single transaction out of the typical file operations for
- * accessing caches. Caches are normally ready from the database or local
- * file, if the entry does not exist or is expired then it generates the new
- * cache data and stores it. This method takes care of these operations and
- * handles the custom code by performing callbacks when needed.
- *
- * The $retrieveCallback is used when the file contents can be used (ie. not
- * re-generation) and is called when the file is ready locally.
- * The function will be called with the file path as the first parameter, the
- * mtime as the second and optionally $extraData as the third.
- * The function must return the file contents or an instance of
- * eZClusterFileFailure which can be used to tell the system that the
- * retrieve data cannot be used after all.
- *
- * $retrieveCallback can be set to null which makes the system go directly
- * to the generation.
- *
- * The $generateCallback is used when the file content is expired or does not
- * exist, in this case the content must be re-generated and stored. The
- * function will be called with the file path as the first parameter and
- * optionally $extraData as the second.
- * The function must return an array with information on the contents, the
- * array consists of:
- * - scope - The current scope of the file, is optional.
- * - datatype - The current datatype of the file, is optional.
- * - content - The file content, this can be any type except null.
- * - binarydata - The binary data which is written to the file.
- * - store - Whether *content* or *binarydata* should be stored to the
- * file, if false it will simply return the data. Optional,
- * by default it is true.
- * Note: Set $generateCallback to false to disable generation callback.
- * Note: Set $generateCallback to null to tell the function to perform a
- * write lock but not do any generation, the generation must done be
- * done by the caller by calling @see storeCache().
- *
- * Either *content* or *binarydata* must be supplied, if not an error is
- * issued and it returns null.
- *
- * If *content* is set it will be used as the return value of this function,
- * if not it will return the binary data.
- * If *binarydata* is set it will be used as the binary data for the file, if
- * not it will perform a var_export on *content* and use that as the binary
- * data.
- *
- * For convenience the $generateCallback function can return a string which
- * will be considered as the binary data for the file and returned as the
- * content.
- *
- * For controlling how long a cache entry can be used the parameters
- * @see $expiry and @see $ttl is used.
- * @see $expiry can be set to a timestamp which controls the absolute max
- * time for the cache, after this time/date the cache will never be used.
- * If the value is set to a negative value or null there the expiration check
- * is disabled.
- *
- * $ttl (time to live) tells how many seconds the cache can live from the
- * time it was stored. If the value is set to negative or null there is no
- * limit for the lifetime of the cache. A value of 0 means that the cache
- * will always expire and practically disables caching. For the cache to be
- * used both the $expiry and $ttl check must hold.
- *
- * @todo Reformat the doc so that it's readable
- */
- public function processCache( $retrieveCallback, $generateCallback = null, $ttl = null, $expiry = null, $extraData = null );
- /**
- * Calculates if the file data is expired or not.
- *
- * @param string $fname Name of file, available for easy debugging.
- * @param int $mtime Modification time of file, can be set to false if
- * file does not exist.
- * @param int $expiry Time when file is to be expired, a value of -1 will
- * disable this check.
- * @param int $curtime The current time to check against.
- * @param int $ttl Number of seconds the data can live, set to null to
- * disable TTL.
- * @return bool
- */
- public function isFileExpired( $fname, $mtime, $expiry, $curtime, $ttl );
- /**
- * Calculates if the current file data is expired or not.
- *
- * @param int $expiry Time when file is to be expired, a value of -1 will disable this check.
- * @param int $curtime The current time to check against.
- * @param int $ttl Number of seconds the data can live, set to null to disable TTL.
- * @return bool
- */
- public function isExpired( $expiry, $curtime, $ttl );
- /**
- * Calculates if the local file is expired or not.
- * @param int $expiry Time when file is to be expired, a value of -1 will disable this check.
- * @param int $curtime The current time to check against.
- * @param int $ttl Number of seconds the data can live, set to null to disable TTL.
- * @return bool
- */
- public function isLocalFileExpired( $expiry, $curtime, $ttl );
- /**
- * Calculates if the DB file is expired or not.
- * @param int $expiry Time when file is to be expired, a value of -1 will disable this check.
- * @param int $curtime The current time to check against.
- * @param int $ttl Number of seconds the data can live, set to null to disable TTL.
- * @return bool
- */
- public function isDBFileExpired( $expiry, $curtime, $ttl );
- /**
- * Provides access to the file contents by downloading the file locally and
- * calling $callback with the local filename. The callback can then process
- * the contents and return the data in the same way as in processCache().
- *
- * Downloading is only done once so the local copy is kept, while updates to
- * the remote DB entry is synced with the local one.
- *
- * The parameters $expiry and $extraData is the same as for processCache().
- *
- * @see self::processCache()
- * @note Unlike processCache() this returns null if the file cannot be
- * accessed.
- */
- public function processFile( $callback, $expiry = false, $extraData = null );
- /**
- * Fetches a cluster file and saves it locally under a new name
- *
- * @return string path to the saved file
- */
- public function fetchUnique();
- /**
- * Fetches file from db and saves it in FS under the same name.
- * @param bool $noLocalCache
- */
- function fetch( $noLocalCache = false );
- /**
- * Returns file contents.
- * @return contents string, or false in case of an error.
- */
- public function fileFetchContents( $filePath );
- /**
- * Returns file contents.
- * @return string|bool contents string, or false in case of an error.
- */
- public function fetchContents();
- /**
- * Returns file metadata.
- */
- public function stat();
- /**
- * Returns file size.
- * @return int|null
- */
- public function size();
- /**
- * Returns file modification time.
- * @return int|null
- */
- public function mtime();
- /**
- * Returns file name.
- * @return string
- */
- public function name();
- /**
- * @note has severe performance issues
- */
- public function fileDeleteByRegex( $dir, $fileRegex );
- /**
- * @note has some severe performance issues
- */
- public function fileDeleteByWildcard( $wildcard );
- public function fileDeleteByDirList( $dirList, $commonPath, $commonSuffix );
- /**
- * Deletes specified file/directory.
- *
- * If a directory specified it is deleted recursively.
- */
- public function fileDelete( $path, $fnamePart = false );
- /**
- * Deletes specified file/directory.
- *
- * If a directory specified it is deleted recursively.
- */
- public function delete();
- /**
- * Deletes a file that has been fetched before.
- */
- public function fileDeleteLocal( $path );
- /**
- * Deletes a file that has been fetched before.
- */
- public function deleteLocal();
- /**
- * Purges local and remote file data for current file.
- */
- public function purge( $printCallback = false, $microsleep = false, $max = false, $expiry = false );
- /**
- * Check if given file/dir exists.
- * @param string $file
- * @return bool
- */
- public function fileExists( $path );
- /**
- * Check if given file/dir exists.
- *
- * @note This function does not interact with database. Instead, it just
- * returns existance status determined in the constructor.
- *
- * @return bool
- */
- public function exists();
- /**
- * Outputs file contents prepending them with appropriate HTTP headers.
- *
- * @deprecated This function should not be used since it cannot handle
- * reading errors.
- */
- public function passthrough();
- /**
- * Copy file.
- */
- public function fileCopy( $srcPath, $dstPath );
- /**
- * Create symbolic or hard link to file.
- */
- public function fileLinkCopy( $srcPath, $dstPath, $symLink );
- /**
- * Move file.
- */
- public function fileMove( $srcPath, $dstPath );
- /**
- * Move file.
- * @param string $dstPath Destination path
- */
- public function move( $dstPath );
- /**
- * Get list of files stored in database.
- *
- * Used in bin/php/clusterize.php.
- *
- * @param array $scopes return only files that belong to any of these scopes
- * @param boolean $excludeScopes if true, then reverse the meaning of $scopes, which is
- * return only files that do not belong to any of the scopes listed in $scopes
- */
- public function getFileList( $scopes = false, $excludeScopes = false );
- /**
- * Starts cache generation for the current file.
- *
- * This is done by creating a file named by the original file name, prefixed
- * with '.generating'.
- *
- * @return bool false if the file is being generated, true if it is not
- */
- public function startCacheGeneration();
- /**
- * Ends the cache generation started by startCacheGeneration().
- */
- public function endCacheGeneration( $rename = true );
- /**
- * Aborts the current cache generation process.
- *
- * Does so by rolling back the current transaction, which should be the
- * .generating file lock
- */
- public function abortCacheGeneration();
- /**
- * Checks if the .generating file was changed, which would mean that generation
- * timed out. If not timed out, refreshes the timestamp so that storage won't
- * be stolen
- */
- public function checkCacheGenerationTimeout();
- /**
- * This method indicates if the cluster file handler requires clusterizing.
- *
- * If the handler does require clusterizing, it will be required/possible to
- * use bin/php/clusterize.php to get data in/out of the cluster when setting
- * it up or disabling it.
- *
- * @return bool
- */
- public function requiresClusterizing();
- /**
- * This method indicates if the cluster file handler requires binary files
- * to be purged in order to be physically deleted
- *
- * @since 4.3
- * @deprecated Deprecated as of 4.5, use {@link eZClusterFileHandlerInterface::requiresPurge()} instead.
- * @return bool
- */
- public function requiresBinaryPurge();
- /**
- * This method indicates if the cluster file handler requires binary files
- * to be purged in order to be physically deleted
- *
- * @since 4.5
- * @return bool
- */
- public function requiresPurge();
- /**
- * Indicates if the handler supports the stalecache feature
- * @return bool true if it does, false otherwise
- */
- public function hasStaleCacheSupport();
- }
- ?>