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      * Generates the appropriate configuration required for unit testing.
  85      *
  86      * @return array Array of unit test configuration data to be used by initialise().
  87      */
  88     public static function unit_test_configuration();
  89 }
  90
  91 /**
  92  * Abstract cache store class.
  93  *
  94  * All cache store plugins must extend this base class.
  95  * It lays down the foundation for what is required of a cache store plugin.
  96  *
  97  * @since Moodle 2.4
  98  * @package    core
  99  * @category   cache
 100  * @copyright  2012 Sam Hemelryk
 101  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 102  */
 103 abstract class cache_store implements cache_store_interface {
 104
 105     // Constants for features a cache store can support
 106
 107     /**
 108      * Supports multi-part keys
 109      */
 110     const SUPPORTS_MULTIPLE_IDENTIFIERS = 1;
 111     /**
 112      * Ensures data remains in the cache once set.
 113      */
 114     const SUPPORTS_DATA_GUARANTEE = 2;
 115     /**
 116      * Supports a native ttl system.
 117      */
 118     const SUPPORTS_NATIVE_TTL = 4;
 119
 120     /**
 121      * The cache is searchable by key.
 122      */
 123     const IS_SEARCHABLE = 8;
 124
 125     /**
 126      * The cache store dereferences objects.
 127      *
 128      * When set, loaders will assume that all data coming from this store has already had all references
 129      * resolved.  So even for complex object structures it will not try to remove references again.
 130      */
 131     const DEREFERENCES_OBJECTS = 16;
 132
 133     // Constants for the modes of a cache store
 134
 135     /**
 136      * Application caches. These are shared caches.
 137      */
 138     const MODE_APPLICATION = 1;
 139     /**
 140      * Session caches. Just access to the PHP session.
 141      */
 142     const MODE_SESSION = 2;
 143     /**
 144      * Request caches. Static caches really.
 145      */
 146     const MODE_REQUEST = 4;
 147     /**
 148      * Static caches.
 149      */
 150     const STATIC_ACCEL = '** static accel. **';
 151
 152     /**
 153      * Constructs an instance of the cache store.
 154      *
 155      * The constructor should be responsible for creating anything needed by the store that is not
 156      * specific to a definition.
 157      * Tasks such as opening a connection to check it is available are best done here.
 158      * Tasks that are definition specific such as creating a storage area for the definition data
 159      * or creating key tables and indexs are best done within the initialise method.
 160      *
 161      * Once a store has been constructed the cache API will check it is ready to be intialised with
 162      * a definition by called $this->is_ready().
 163      * If the setup of the store failed (connection could not be established for example) then
 164      * that method should return false so that the store instance is not selected for use.
 165      *
 166      * @param string $name The name of the cache store
 167      * @param array $configuration The configuration for this store instance.
 168      */
 169     abstract public function __construct($name, array $configuration = array());
 170
 171     /**
 172      * Returns the name of this store instance.
 173      * @return string
 174      */
 175     abstract public function my_name();
 176
 177     /**
 178      * Initialises a new instance of the cache store given the definition the instance is to be used for.
 179      *
 180      * This function should be used to run any definition specific setup the store instance requires.
 181      * Tasks such as creating storage areas, or creating indexes are best done here.
 182      *
 183      * Its important to note that the initialise method is expected to always succeed.
 184      * If there are setup tasks that may fail they should be done within the __construct method
 185      * and should they fail is_ready should return false.
 186      *
 187      * @param cache_definition $definition
 188      */
 189     abstract public function initialise(cache_definition $definition);
 190
 191     /**
 192      * Returns true if this cache store instance has been initialised.
 193      * @return bool
 194      */
 195     abstract public function is_initialised();
 196
 197     /**
 198      * Returns true if this cache store instance is ready to use.
 199      * @return bool
 200      */
 201     public function is_ready() {
 202         return forward_static_call(array($this, 'are_requirements_met'));
 203     }
 204
 205     /**
 206      * Retrieves an item from the cache store given its key.
 207      *
 208      * @param string $key The key to retrieve
 209      * @return mixed The data that was associated with the key, or false if the key did not exist.
 210      */
 211     abstract public function get($key);
 212
 213     /**
 214      * Retrieves several items from the cache store in a single transaction.
 215      *
 216      * 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.
 217      *
 218      * @param array $keys The array of keys to retrieve
 219      * @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
 220      *      be set to false.
 221      */
 222     abstract public function get_many($keys);
 223
 224     /**
 225      * Sets an item in the cache given its key and data value.
 226      *
 227      * @param string $key The key to use.
 228      * @param mixed $data The data to set.
 229      * @return bool True if the operation was a success false otherwise.
 230      */
 231     abstract public function set($key, $data);
 232
 233     /**
 234      * Sets many items in the cache in a single transaction.
 235      *
 236      * @param array $keyvaluearray An array of key value pairs. Each item in the array will be an associative array with two
 237      *      keys, 'key' and 'value'.
 238      * @return int The number of items successfully set. It is up to the developer to check this matches the number of items
 239      *      sent ... if they care that is.
 240      */
 241     abstract public function set_many(array $keyvaluearray);
 242
 243     /**
 244      * Deletes an item from the cache store.
 245      *
 246      * @param string $key The key to delete.
 247      * @return bool Returns true if the operation was a success, false otherwise.
 248      */
 249     abstract public function delete($key);
 250
 251     /**
 252      * Deletes several keys from the cache in a single action.
 253      *
 254      * @param array $keys The keys to delete
 255      * @return int The number of items successfully deleted.
 256      */
 257     abstract public function delete_many(array $keys);
 258
 259     /**
 260      * Purges the cache deleting all items within it.
 261      *
 262      * @return boolean True on success. False otherwise.
 263      */
 264     abstract public function purge();
 265
 266     /**
 267      * @deprecated since 2.5
 268      * @see \cache_store::instance_deleted()
 269      */
 270     public function cleanup() {
 271         throw new coding_exception('cache_store::cleanup() can not be used anymore.' .
 272             ' Please use cache_store::instance_deleted() instead.');
 273     }
 274
 275     /**
 276      * Performs any necessary operation when the store instance has been created.
 277      *
 278      * @since Moodle 2.5
 279      */
 280     public function instance_created() {
 281         // By default, do nothing.
 282     }
 283
 284     /**
 285      * Performs any necessary operation when the store instance is being deleted.
 286      *
 287      * This method may be called before the store has been initialised.
 288      *
 289      * @since Moodle 2.5
 290      * @see cleanup()
 291      */
 292     public function instance_deleted() {
 293         if (method_exists($this, 'cleanup')) {
 294             // There used to be a legacy function called cleanup, it was renamed to instance delete.
 295             // To be removed in 2.6.
 296             $this->cleanup();
 297         }
 298     }
 299
 300     /**
 301      * Returns true if the user can add an instance of the store plugin.
 302      *
 303      * @return bool
 304      */
 305     public static function can_add_instance() {
 306         return true;
 307     }
 308
 309     /**
 310      * Returns true if the store instance guarantees data.
 311      *
 312      * @return bool
 313      */
 314     public function supports_data_guarantee() {
 315         return $this::get_supported_features() & self::SUPPORTS_DATA_GUARANTEE;
 316     }
 317
 318     /**
 319      * Returns true if the store instance supports multiple identifiers.
 320      *
 321      * @return bool
 322      */
 323     public function supports_multiple_identifiers() {
 324         return $this::get_supported_features() & self::SUPPORTS_MULTIPLE_IDENTIFIERS;
 325     }
 326
 327     /**
 328      * Returns true if the store instance supports native ttl.
 329      *
 330      * @return bool
 331      */
 332     public function supports_native_ttl() {
 333         return $this::get_supported_features() & self::SUPPORTS_NATIVE_TTL;
 334     }
 335
 336     /**
 337      * Returns true if the store instance is searchable.
 338      *
 339      * @return bool
 340      */
 341     public function is_searchable() {
 342         return in_array('cache_is_searchable', class_implements($this));
 343     }
 344
 345     /**
 346      * Returns true if the store automatically dereferences objects.
 347      *
 348      * @return bool
 349      */
 350     public function supports_dereferencing_objects() {
 351         return $this::get_supported_features() & self::DEREFERENCES_OBJECTS;
 352     }
 353
 354     /**
 355      * Creates a clone of this store instance ready to be initialised.
 356      *
 357      * This method is used so that a cache store needs only be constructed once.
 358      * Future requests for an instance of the store will be given a cloned instance.
 359      *
 360      * If you are writing a cache store that isn't compatible with the clone operation
 361      * you can override this method to handle any situations you want before cloning.
 362      *
 363      * @param array $details An array containing the details of the store from the cache config.
 364      * @return cache_store
 365      */
 366     public function create_clone(array $details = array()) {
 367         // By default we just run clone.
 368         // Any stores that have an issue with this will need to override the create_clone method.
 369         return clone($this);
 370     }
 371
 372     /**
 373      * Can be overridden to return any warnings this store instance should make to the admin.
 374      *
 375      * This should be used to notify things like configuration conflicts etc.
 376      * The warnings returned here will be displayed on the cache configuration screen.
 377      *
 378      * @return string[] An array of warning strings from the store instance.
 379      */
 380     public function get_warnings() {
 381         return array();
 382     }
 383
 384     /**
 385      * Returns true if this cache store instance is both suitable for testing, and ready for testing.
 386      *
 387      * Cache stores that support being used as the default store for unit and acceptance testing should
 388      * override this function and return true if there requirements have been met.
 389      *
 390      * @return bool
 391      */
 392     public static function ready_to_be_used_for_testing() {
 393         return false;
 394     }
 395 }