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 ($item) {
  44  *   if (my_process($item->data)) {
  45  *     $queue->deleteItem($item);
  46  *   } else {
  47  *     $queue->releaseItem($item);
  48  *   }
  49  * }
  50  * @endcode
  51  */
  52 class CRM_Queue_Service {
  53
  54   static $_singleton;
  55
  56   /**
  57    * FIXME: Singleton pattern should be removed when dependency-injection
  58    * becomes available.
  59    *
  60    * @param $forceNew bool
  61    *
  62    * @return \CRM_Queue_Service
  63    */
  64   static function &singleton($forceNew = FALSE) {
  65     if ($forceNew || !self::$_singleton) {
  66       self::$_singleton = new CRM_Queue_Service();
  67     }
  68     return self::$_singleton;
  69   }
  70
  71   /**
  72    * @var array(queueName => CRM_Queue_Queue)
  73    */
  74   var $queues;
  75
  76   /**
  77    *
  78    */
  79   function __construct() {
  80     $this->queues = array();
  81   }
  82
  83   /**
  84    *
  85    * @param $queueSpec, array with keys:
  86    *   - type: string, required, e.g. "interactive", "immediate", "stomp", "beanstalk"
  87    *   - name: string, required, e.g. "upgrade-tasks"
  88    *   - reset: bool, optional; if a queue is found, then it should be flushed; default to TRUE
  89    *   - (additional keys depending on the queue provider)
  90    *
  91    * @return CRM_Queue_Queue
  92    */
  93   function create($queueSpec) {
  94     if (@is_object($this->queues[$queueSpec['name']]) && empty($queueSpec['reset'])) {
  95       return $this->queues[$queueSpec['name']];
  96     }
  97
  98     $queue = $this->instantiateQueueObject($queueSpec);
  99     $exists = $queue->existsQueue();
 100     if (!$exists) {
 101       $queue->createQueue();
 102     }
 103     elseif (@$queueSpec['reset']) {
 104       $queue->deleteQueue();
 105       $queue->createQueue();
 106     }
 107     else {
 108       $queue->loadQueue();
 109     }
 110     $this->queues[$queueSpec['name']] = $queue;
 111     return $queue;
 112   }
 113
 114   /**
 115    *
 116    * @param $queueSpec, array with keys:
 117    *   - type: string, required, e.g. "interactive", "immediate", "stomp", "beanstalk"
 118    *   - name: string, required, e.g. "upgrade-tasks"
 119    *   - (additional keys depending on the queue provider)
 120    *
 121    * @return CRM_Queue_Queue
 122    */
 123   function load($queueSpec) {
 124     if (is_object($this->queues[$queueSpec['name']])) {
 125       return $this->queues[$queueSpec['name']];
 126     }
 127     $queue = $this->instantiateQueueObject($queueSpec);
 128     $queue->loadQueue();
 129     $this->queues[$queueSpec['name']] = $queue;
 130     return $queue;
 131   }
 132
 133   /**
 134    * Convert a queue "type" name to a class name
 135    *
 136    * @param $type string, e.g. "interactive", "immediate", "stomp", "beanstalk"
 137    *
 138    * @return string, class-name
 139    */
 140   protected function getQueueClass($type) {
 141     $type = preg_replace('/[^a-zA-Z0-9]/', '', $type);
 142     $className = 'CRM_Queue_Queue_' . $type;
 143     // FIXME: when used with class-autoloader, this may be unnecessary
 144     if (!class_exists($className)) {
 145       $classFile = 'CRM/Queue/Queue/' . $type . '.php';
 146       require_once $classFile;
 147     }
 148     return $className;
 149   }
 150
 151   /**
 152    *
 153    * @param $queueSpec array, see create()
 154    *
 155    * @return CRM_Queue_Queue
 156    */
 157   protected function instantiateQueueObject($queueSpec) {
 158     // note: you should probably never do anything else here
 159     $class = new ReflectionClass($this->getQueueClass($queueSpec['type']));
 160     return $class->newInstance($queueSpec);
 161   }
 162 }
 163