PageRenderTime 47ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 0ms

/cache/classes/store.php

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