CRM/Queue/Service.php

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