Source for file Storage.class.php

Documentation is available at Storage.class.php

  1. <?php
  2. /**
  3. * XOAD Events Storage file.
  4. *
  5. * <p>This file defines the {@link XOAD_Events_Storage} Class.</p>
  6. * <p>Example:</p>
  7. * <code>
  8. * <?php
  9. *
  10. * require_once('xoad.php');
  11. *
  12. * $storage =& XOAD_Events_Storage::getStorage();
  13. *
  14. * $storage->postEvent('event', 'class');
  15. *
  16. * ?>
  17. * </code>
  18. *
  19. * @author Stanimir Angeloff
  20. *
  21. * @package XOAD
  22. *
  23. * @subpackage XOAD_Events
  24. *
  25. * @version 0.6.0.0
  26. *
  27. */
  28.  
  29. /**
  30. * XOAD Events Storage Class.
  31. *
  32. * <p>This class is used as base class for all XOAD Events storage providers.</p>
  33. * <p>The class also defines the {@link getStorage} method which
  34. * is used to retrieve an instane to the configurated storage.</p>
  35. * <p>Example XOAD Events provider: {@link XOAD_Events_Storage_MySQL}.</p>
  36. * <p>Example:</p>
  37. * <code>
  38. * <?php
  39. *
  40. * define('XOAD_EVENTS_STORAGE_DSN', 'MySQL://server=?;user=?;password=?;database=?');
  41. *
  42. * require_once('xoad.php');
  43. *
  44. * // The line below will return a XOAD_Events_Storage_MySQL
  45. * // class instance.
  46. * $storage =& XOAD_Events_Storage::getStorage();
  47. *
  48. * $storage->postEvent('event', 'class');
  49. *
  50. * ?>
  51. * </code>
  52. *
  53. * @author Stanimir Angeloff
  54. *
  55. * @package XOAD
  56. *
  57. * @subpackage XOAD_Events
  58. *
  59. * @version 0.6.0.0
  60. *
  61. */
  62. class XOAD_Events_Storage
  63. {
  64. /**
  65. * Creates a new instance of the {@link XOAD_Events_Storage} class.
  66. *
  67. * @access public
  68. *
  69. * @param string $dsn The data source name and parameters to use
  70. * when creating the instance.
  71. *
  72. */
  73. function XOAD_Events_Storage($dsn = null)
  74. {
  75. if ( ! empty($dsn)) {
  76.  
  77. $pairs = explode(';', $dsn);
  78.  
  79. foreach ($pairs as $pair) {
  80.  
  81. if ( ! empty($pair)) {
  82.  
  83. list($key, $value) = explode('=', $pair, 2);
  84.  
  85. $this->$key = $value;
  86. }
  87. }
  88. }
  89. }
  90.  
  91. /**
  92. * Retrieves an instanse to the configurated XOAD Events storage provider.
  93. *
  94. * <p>Example:</p>
  95. * <code>
  96. * <?php
  97. *
  98. * require_once('xoad.php');
  99. *
  100. * $storage =& XOAD_Events_Storage::getStorage();
  101. *
  102. * $storage->postEvent('event', 'class');
  103. *
  104. * ?>
  105. * </code>
  106. *
  107. * @access public
  108. *
  109. * @return object Singleton {@link XOAD_Events_Storage} inherited class based
  110. * on the configuration (see {@link XOAD_EVENTS_STORAGE_DSN}).
  111. *
  112. * @static
  113. *
  114. */
  115. function &getStorage()
  116. {
  117. static $instance;
  118.  
  119. if ( ! isset($instance)) {
  120.  
  121. $className = null;
  122.  
  123. $classParameters = null;
  124.  
  125. $separator = '://';
  126.  
  127. $position = strpos(XOAD_EVENTS_STORAGE_DSN, $separator);
  128.  
  129. if ($position === false) {
  130.  
  131. $className = XOAD_EVENTS_STORAGE_DSN;
  132.  
  133. } else {
  134.  
  135. $className = substr(XOAD_EVENTS_STORAGE_DSN, 0, $position);
  136.  
  137. $classParameters = substr(XOAD_EVENTS_STORAGE_DSN, $position + strlen($separator));
  138. }
  139.  
  140. if (empty($className)) {
  141.  
  142. return null;
  143. }
  144.  
  145. $fileName = XOAD_BASE . '/classes/events/storage/' . $className . '.class.php';
  146.  
  147. /**
  148. * Load the file that defines the events storage provider.
  149. */
  150. require_once($fileName);
  151.  
  152. $realClassName = 'XOAD_Events_Storage_' . $className;
  153.  
  154. if ( ! class_exists($realClassName)) {
  155.  
  156. return null;
  157. }
  158.  
  159. $instance = new $realClassName($classParameters);
  160. }
  161.  
  162. return $instance;
  163. }
  164.  
  165. /**
  166. * Posts a single event to the storage.
  167. *
  168. * <p>The {@link $event} and {@link $class} arguments are required
  169. * for each event. The {@link $sender}, {@link $data}, {@link $filter},
  170. * {@link $time} and {@link $lifetime} arguments are optional.</p>
  171. * <p>In case you have supplied both {@link $class} and {@link $sender},
  172. * then the {@link $sender}'s class must match the one you've supplied.</p>
  173. * <p>This method calls {@link postMultipleEvents} with the appropriate
  174. * arguments.</p>
  175. *
  176. * @access public
  177. *
  178. * @param string $event The event name (case-sensitive).
  179. *
  180. * @param string $class The class that is the source of the event.
  181. *
  182. * @param object $sender The sender object of the event.
  183. *
  184. * @param mixed $data The data associated with the event.
  185. *
  186. * @param string $filter The event filter data (case-insensitive).
  187. * Using this argument you can post events with
  188. * the same name but with different filter data.
  189. * The client will respond to them individually.
  190. *
  191. * @param int $time The event start time (seconds since the Unix
  192. * Epoch (January 1 1970 00:00:00 GMT).
  193. *
  194. * @param int $lifetime The event lifetime (in seconds).
  195. *
  196. * @return bool true on success, false otherwise.
  197. *
  198. */
  199. function postEvent($event, $class, $sender = null, $data = null, $filter = null, $time = null, $lifetime = null)
  200. {
  201. return $this->postMultipleEvents(array(array(
  202. 'event' => $event,
  203. 'className' => $class,
  204. 'sender' => $sender,
  205. 'data' => $data,
  206. 'filter' => $filter,
  207. 'time' => $time,
  208. 'lifetime' => $lifetime
  209. )));
  210. }
  211.  
  212. /**
  213. * This method should be called from each successor to add
  214. * common data to the event.
  215. *
  216. * <p>When you call this method you should pass an associative
  217. * array that contains the event data. This method will populate
  218. * it with the missing information and will check the validity of
  219. * the presented.</p>
  220. *
  221. * @access public
  222. *
  223. * @return bool true on success, false otherwise
  224. *
  225. */
  226. function postMultipleEvents(&$event)
  227. {
  228. if (( ! isset($event['time'])) || ($event['time'] === null)) {
  229.  
  230. $event['time'] = XOAD_Utilities::getMicroTime();
  231. }
  232.  
  233. if (( ! isset($event['lifetime'])) || ($event['lifetime'] === null)) {
  234.  
  235. $event['lifetime'] = XOAD_EVENTS_LIFETIME;
  236. }
  237.  
  238. if ((isset($event['sender'])) && ($event['sender'] !== null)) {
  239.  
  240. if (XOAD_Utilities::getType($event['sender']) != 'object') {
  241.  
  242. return false;
  243. }
  244.  
  245. if (strcasecmp($event['className'], get_class($event['sender'])) != 0) {
  246.  
  247. return false;
  248. }
  249. }
  250.  
  251. return true;
  252. }
  253.  
  254. /**
  255. * This method should be called from each successor to retrieve
  256. * the start time of the old events in the storage.
  257. *
  258. * @access public
  259. *
  260. * @return int The start time of the old events.
  261. *
  262. */
  263. function cleanEvents()
  264. {
  265. return XOAD_Utilities::getMicroTime() - XOAD_EVENTS_LIFETIME;
  266. }
  267.  
  268. /**
  269. * Filters the events in the storage using a single criteria.
  270. *
  271. * <p>The {@link $event} and {@link $class} arguments are required
  272. * for each event. The {@link $filter} and {@link $time} arguments
  273. * are optional.</p>
  274. * <p>This method calls {@link filterMultipleEvents} with the appropriate
  275. * arguments.</p>
  276. *
  277. * @access public
  278. *
  279. * @param string $event The event name (case-sensitive).
  280. *
  281. * @param string $class The class that is the source of the event.
  282. *
  283. * @param string $filter The event filter data (case-insensitive).
  284. * Using this argument you can filter events with
  285. * the same name but with different filter data.
  286. *
  287. * @param int $time The event start time (seconds since the Unix
  288. * Epoch (January 1 1970 00:00:00 GMT).
  289. *
  290. * @return array Sequental array that contains all events that match the
  291. * supplied criterias, ordered by time (ascending).
  292. *
  293. */
  294. function filterEvents($event, $class, $filter = null, $time = null)
  295. {
  296. return $this->filterMultipleEvents(array(array(
  297. 'event' => $event,
  298. 'className' => $class,
  299. 'filter' => $filter,
  300. 'time' => $time
  301. )));
  302. }
  303.  
  304. /**
  305. * This method should be called from each successor to add
  306. * common data to the event.
  307. *
  308. * <p>When you call this method you should pass an associative
  309. * array that contains the event data. This method will populate
  310. * it with the missing information and will check the validity of
  311. * the presented.</p>
  312. *
  313. * @access public
  314. *
  315. * @return bool true on success, false otherwise
  316. *
  317. */
  318. function filterMultipleEvents(&$event)
  319. {
  320. if (( ! isset($event['time'])) || ($event['time'] === null)) {
  321.  
  322. $event['time'] = XOAD_Utilities::getMicroTime();
  323. }
  324.  
  325. return true;
  326. }
  327. }
  328. ?>

Documentation generated on Sat, 12 Nov 2005 20:24:47 +0200 by phpDocumentor 1.3.0RC3