CRM/Queue/Service.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.7                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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   protected static $_singleton;
  55
  56   /**
  57    * FIXME: Singleton pattern should be removed when dependency-injection
  58    * becomes available.
  59    *
  60    * @param bool $forceNew
  61    *   TRUE if a new instance must be created.
  62    *
  63    * @return \CRM_Queue_Service
  64    */
  65   public static function &singleton($forceNew = FALSE) {
  66     if ($forceNew || !self::$_singleton) {
  67       self::$_singleton = new CRM_Queue_Service();
  68     }
  69     return self::$_singleton;
  70   }
  71
  72   /**
  73    * @var array (string $queueName => CRM_Queue_Queue)
  74    */
  75   public $queues;
  76
  77   /**
  78    */
  79   public function __construct() {
  80     $this->queues = array();
  81   }
  82
  83   /**
  84    * Create a queue. If one already exists, then it will be reused.
  85    *
  86    * @param array $queueSpec
  87    *   Array with keys:
  88    *   - type: string, required, e.g. "interactive", "immediate", "stomp",
  89    *    "beanstalk"
  90    *   - name: string, required, e.g. "upgrade-tasks"
  91    *   - reset: bool, optional; if a queue is found, then it should be
  92    *     flushed; default to TRUE
  93    *   - (additional keys depending on the queue provider).
  94    *
  95    * @return CRM_Queue_Queue
  96    */
  97   public function create($queueSpec) {
  98     if (@is_object($this->queues[$queueSpec['name']]) && empty($queueSpec['reset'])) {
  99       return $this->queues[$queueSpec['name']];
 100     }
 101
 102     $queue = $this->instantiateQueueObject($queueSpec);
 103     $exists = $queue->existsQueue();
 104     if (!$exists) {
 105       $queue->createQueue();
 106     }
 107     elseif (@$queueSpec['reset']) {
 108       $queue->deleteQueue();
 109       $queue->createQueue();
 110     }
 111     else {
 112       $queue->loadQueue();
 113     }
 114     $this->queues[$queueSpec['name']] = $queue;
 115     return $queue;
 116   }
 117
 118   /**
 119    * Look up an existing queue.
 120    *
 121    * @param array $queueSpec
 122    *   Array with keys:
 123    *   - type: string, required, e.g. "interactive", "immediate", "stomp",
 124    *     "beanstalk"
 125    *   - name: string, required, e.g. "upgrade-tasks"
 126    *   - (additional keys depending on the queue provider).
 127    *
 128    * @return CRM_Queue_Queue
 129    */
 130   public function load($queueSpec) {
 131     if (is_object($this->queues[$queueSpec['name']])) {
 132       return $this->queues[$queueSpec['name']];
 133     }
 134     $queue = $this->instantiateQueueObject($queueSpec);
 135     $queue->loadQueue();
 136     $this->queues[$queueSpec['name']] = $queue;
 137     return $queue;
 138   }
 139
 140   /**
 141    * Convert a queue "type" name to a class name.
 142    *
 143    * @param string $type
 144    *   E.g. "interactive", "immediate", "stomp", "beanstalk".
 145    *
 146    * @return string
 147    *   Class-name
 148    */
 149   protected function getQueueClass($type) {
 150     $type = preg_replace('/[^a-zA-Z0-9]/', '', $type);
 151     $className = 'CRM_Queue_Queue_' . $type;
 152     // FIXME: when used with class-autoloader, this may be unnecessary
 153     if (!class_exists($className)) {
 154       $classFile = 'CRM/Queue/Queue/' . $type . '.php';
 155       require_once $classFile;
 156     }
 157     return $className;
 158   }
 159
 160   /**
 161    * @param array $queueSpec
 162    *   See create().
 163    *
 164    * @return CRM_Queue_Queue
 165    */
 166   protected function instantiateQueueObject($queueSpec) {
 167     // note: you should probably never do anything else here
 168     $class = new ReflectionClass($this->getQueueClass($queueSpec['type']));
 169     return $class->newInstance($queueSpec);
 170   }
 171
 172 }