cache/classes/store.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Cache store - base class
  19  *
  20  * This file is part of Moodle's cache API, affectionately called MUC.
  21  * It contains the components that are required in order to use caching.
  22  *
  23  * @package    core
  24  * @category   cache
  25  * @copyright  2012 Sam Hemelryk
  26  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  27  */
  28
  29 defined('MOODLE_INTERNAL') || die();
  30
  31 /**
  32  * Cache store interface.
  33  *
  34  * This interface defines the static methods that must be implemented by every cache store plugin.
  35  * To ensure plugins implement this class the abstract cache_store class implements this interface.
  36  *
  37  * @package    core
  38  * @category   cache
  39  * @copyright  2012 Sam Hemelryk
  40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  41  */
  42 interface cache_store_interface {
  43     /**
  44      * Static method to check if the store requirements are met.
  45      *
  46      * @return bool True if the stores software/hardware requirements have been met and it can be used. False otherwise.
  47      */
  48     public static function are_requirements_met();
  49
  50     /**
  51      * Static method to check if a store is usable with the given mode.
  52      *
  53      * @param int $mode One of cache_store::MODE_*
  54      */
  55     public static function is_supported_mode($mode);
  56
  57     /**
  58      * Returns the supported features as a binary flag.
  59      *
  60      * @param array $configuration The configuration of a store to consider specifically.
  61      * @return int The supported features.
  62      */
  63     public static function get_supported_features(array $configuration = array());
  64
  65     /**
  66      * Returns the supported modes as a binary flag.
  67      *
  68      * @param array $configuration The configuration of a store to consider specifically.
  69      * @return int The supported modes.
  70      */
  71     public static function get_supported_modes(array $configuration = array());
  72
  73     /**
  74      * Generates an instance of the cache store that can be used for testing.
  75      *
  76      * Returns an instance of the cache store, or false if one cannot be created.
  77      *
  78      * @param cache_definition $definition
  79      * @return cache_store|false
  80      */
  81     public static function initialise_test_instance(cache_definition $definition);
  82 }
  83
  84 /**
  85  * Abstract cache store class.
  86  *
  87  * All cache store plugins must extend this base class.
  88  * It lays down the foundation for what is required of a cache store plugin.
  89  *
  90  * @since 2.4
  91  * @package    core
  92  * @category   cache
  93  * @copyright  2012 Sam Hemelryk
  94  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  95  */
  96 abstract class cache_store implements cache_store_interface {
  97
  98     // Constants for features a cache store can support
  99
 100     /**
 101      * Supports multi-part keys
 102      */
 103     const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;
 104     /**
 105      * Ensures data remains in the cache once set.
 106      */
 107     const SUPPORTS_DATA_GUARANTEE = 2;
 108     /**
 109      * Supports a native ttl system.
 110      */
 111     const SUPPORTS_NATIVE_TTL = 4;
 112
 113     // Constants for the modes of a cache store
 114
 115     /**
 116      * Application caches. These are shared caches.
 117      */
 118     const MODE_APPLICATION = 1;
 119     /**
 120      * Session caches. Just access to the PHP session.
 121      */
 122     const MODE_SESSION = 2;
 123     /**
 124      * Request caches. Static caches really.
 125      */
 126     const MODE_REQUEST = 4;
 127
 128     /**
 129      * Constructs an instance of the cache store.
 130      *
 131      * This method should not create connections or perform and processing, it should be used
 132      *
 133      * @param string $name The name of the cache store
 134      * @param array $configuration The configuration for this store instance.
 135      */
 136     abstract public function __construct($name, array $configuration = array());
 137
 138     /**
 139      * Returns the name of this store instance.
 140      * @return string
 141      */
 142     abstract public function my_name();
 143
 144     /**
 145      * Initialises a new instance of the cache store given the definition the instance is to be used for.
 146      *
 147      * This function should prepare any given connections etc.
 148      *
 149      * @param cache_definition $definition
 150      */
 151     abstract public function initialise(cache_definition $definition);
 152
 153     /**
 154      * Returns true if this cache store instance has been initialised.
 155      * @return bool
 156      */
 157     abstract public function is_initialised();
 158
 159     /**
 160      * Returns true if this cache store instance is ready to use.
 161      * @return bool
 162      */
 163     abstract public function is_ready();
 164
 165     /**
 166      * Retrieves an item from the cache store given its key.
 167      *
 168      * @param string $key The key to retrieve
 169      * @return mixed The data that was associated with the key, or false if the key did not exist.
 170      */
 171     abstract public function get($key);
 172
 173     /**
 174      * Retrieves several items from the cache store in a single transaction.
 175      *
 176      * If not all of the items are available in the cache then the data value for those that are missing will be set to false.
 177      *
 178      * @param array $keys The array of keys to retrieve
 179      * @return array An array of items from the cache. There will be an item for each key, those that were not in the store will
 180      *      be set to false.
 181      */
 182     abstract public function get_many($keys);
 183
 184     /**
 185      * Sets an item in the cache given its key and data value.
 186      *
 187      * @param string $key The key to use.
 188      * @param mixed $data The data to set.
 189      * @return bool True if the operation was a success false otherwise.
 190      */
 191     abstract public function set($key, $data);
 192
 193     /**
 194      * Sets many items in the cache in a single transaction.
 195      *
 196      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 197      *      keys, 'key' and 'value'.
 198      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 199      *      sent ... if they care that is.
 200      */
 201     abstract public function set_many(array $keyvaluearray);
 202
 203     /**
 204      * Deletes an item from the cache store.
 205      *
 206      * @param string $key The key to delete.
 207      * @return bool Returns true if the operation was a success, false otherwise.
 208      */
 209     abstract public function delete($key);
 210
 211     /**
 212      * Deletes several keys from the cache in a single action.
 213      *
 214      * @param array $keys The keys to delete
 215      * @return int The number of items successfully deleted.
 216      */
 217     abstract public function delete_many(array $keys);
 218
 219     /**
 220      * Purges the cache deleting all items within it.
 221      *
 222      * @return boolean True on success. False otherwise.
 223      */
 224     abstract public function purge();
 225
 226     /**
 227      * Performs any necessary clean up when the store instance is being deleted.
 228      */
 229     abstract public function cleanup();
 230
 231     /**
 232      * Returns true if the user can add an instance of the store plugin.
 233      *
 234      * @return bool
 235      */
 236     public static function can_add_instance() {
 237         return true;
 238     }
 239
 240     /**
 241      * Returns true if the store instance guarantees data.
 242      *
 243      * @return bool
 244      */
 245     public function supports_data_guarantee() {
 246         return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE;
 247     }
 248
 249     /**
 250      * Returns true if the store instance supports multiple identifiers.
 251      *
 252      * @return bool
 253      */
 254     public function supports_multiple_identifiers() {
 255         return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS;
 256     }
 257
 258     /**
 259      * Returns true if the store instance supports native ttl.
 260      *
 261      * @return bool
 262      */
 263     public function supports_native_ttl() {
 264         return $this::supports_data_guarantee() & self::SUPPORTS_NATIVE_TTL;
 265     }
 266 }