CRM/Queue/Service.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * The queue service provides an interface for creating or locating
  30  * queues. Note that this approach hides the details of data-storage:
  31  * different queue-providers may store the queue content in different
  32  * ways (in memory, in SQL, or in an external service).
  33  *
  34  * @code
  35  * $queue = CRM_Queue_Service::singleton()->create(array(
  36  *   'type' => 'interactive',
  37  *   'name' => 'upgrade-tasks',
  38  * ));
  39  * $queue->createItem($myData);
  40  *
  41  * // Some time later...
  42  * $item = $queue->claimItem();
  43  * if (my_process($item->data)) {
  44  *   $myMessage->deleteItem();
  45  * } else {
  46  *   $myMessage->releaseItem();
  47  * }
  48  * @endcode
  49  */
  50 class CRM_Queue_Service {
  51
  52   static $_singleton;
  53
  54   /**
  55    * FIXME: Singleton pattern should be removed when dependency-injection
  56    * becomes available.
  57    *
  58    * @param $forceNew bool
  59    *
  60    * @return \CRM_Queue_Service
  61    */
  62   static function &singleton($forceNew = FALSE) {
  63     if ($forceNew || !self::$_singleton) {
  64       self::$_singleton = new CRM_Queue_Service();
  65     }
  66     return self::$_singleton;
  67   }
  68
  69   /**
  70    * @var array(queueName => CRM_Queue_Queue)
  71    */
  72   var $queues;
  73   function __construct() {
  74     $this->queues = array();
  75   }
  76
  77   /**
  78    *
  79    * @param $queueSpec, array with keys:
  80    *   - type: string, required, e.g. "interactive", "immediate", "stomp", "beanstalk"
  81    *   - name: string, required, e.g. "upgrade-tasks"
  82    *   - reset: bool, optional; if a queue is found, then it should be flushed; default to TRUE
  83    *   - (additional keys depending on the queue provider)
  84    *
  85    * @return CRM_Queue_Queue
  86    */
  87   function create($queueSpec) {
  88     if (@is_object($this->queues[$queueSpec['name']]) && empty($queueSpec['reset'])) {
  89       return $this->queues[$queueSpec['name']];
  90     }
  91
  92     $queue = $this->instantiateQueueObject($queueSpec);
  93     $exists = $queue->existsQueue();
  94     if (!$exists) {
  95       $queue->createQueue();
  96     }
  97     elseif (@$queueSpec['reset']) {
  98       $queue->deleteQueue();
  99       $queue->createQueue();
 100     }
 101     else {
 102       $queue->loadQueue();
 103     }
 104     $this->queues[$queueSpec['name']] = $queue;
 105     return $queue;
 106   }
 107
 108   /**
 109    *
 110    * @param $queueSpec, array with keys:
 111    *   - type: string, required, e.g. "interactive", "immediate", "stomp", "beanstalk"
 112    *   - name: string, required, e.g. "upgrade-tasks"
 113    *   - (additional keys depending on the queue provider)
 114    *
 115    * @return CRM_Queue_Queue
 116    */
 117   function load($queueSpec) {
 118     if (is_object($this->queues[$queueSpec['name']])) {
 119       return $this->queues[$queueSpec['name']];
 120     }
 121     $queue = $this->instantiateQueueObject($queueSpec);
 122     $queue->loadQueue();
 123     $this->queues[$queueSpec['name']] = $queue;
 124     return $queue;
 125   }
 126
 127   /**
 128    * Convert a queue "type" name to a class name
 129    *
 130    * @param $type string, e.g. "interactive", "immediate", "stomp", "beanstalk"
 131    *
 132    * @return string, class-name
 133    */
 134   protected function getQueueClass($type) {
 135     $type = preg_replace('/[^a-zA-Z0-9]/', '', $type);
 136     $className = 'CRM_Queue_Queue_' . $type;
 137     // FIXME: when used with class-autoloader, this may be unnecessary
 138     if (!class_exists($className)) {
 139       $classFile = 'CRM/Queue/Queue/' . $type . '.php';
 140       require_once $classFile;
 141     }
 142     return $className;
 143   }
 144
 145   /**
 146    *
 147    * @param $queueSpec array, see create()
 148    *
 149    * @return CRM_Queue_Queue
 150    */
 151   protected function instantiateQueueObject($queueSpec) {
 152     // note: you should probably never do anything else here
 153     $class = new ReflectionClass($this->getQueueClass($queueSpec['type']));
 154     return $class->newInstance($queueSpec);
 155   }
 156 }
 157