| 1 | <?php |
| 2 | /* |
| 3 | +--------------------------------------------------------------------+ |
| 4 | | CiviCRM version 4.6 | |
| 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 | * A queue is an object (usually backed by some persistent data store) |
| 30 | * which stores a list of tasks or messages for use by other processes. |
| 31 | * |
| 32 | * This would ideally be an interface, but it's handy to specify the |
| 33 | * "function __construct()" and the "$name" handling |
| 34 | * |
| 35 | * Note: This interface closely parallels the DrupalQueueInterface. |
| 36 | */ |
| 37 | abstract class CRM_Queue_Queue { |
| 38 | |
| 39 | /** |
| 40 | * @var string |
| 41 | */ |
| 42 | private $_name; |
| 43 | |
| 44 | /** |
| 45 | * Create a reference to queue. After constructing the queue, one should |
| 46 | * usually call createQueue (if it's a new queue) or loadQueue (if it's |
| 47 | * known to be an existing queue). |
| 48 | * |
| 49 | * @param array $queueSpec |
| 50 | * Array with keys: |
| 51 | * - type: string, required, e.g. "interactive", "immediate", "stomp", |
| 52 | * "beanstalk" |
| 53 | * - name: string, required, e.g. "upgrade-tasks" |
| 54 | * - reset: bool, optional; if a queue is found, then it should be |
| 55 | * flushed; default to TRUE |
| 56 | * - (additional keys depending on the queue provider). |
| 57 | */ |
| 58 | public function __construct($queueSpec) { |
| 59 | $this->_name = $queueSpec['name']; |
| 60 | } |
| 61 | |
| 62 | /** |
| 63 | * Determine the string name of this queue. |
| 64 | * |
| 65 | * @return string |
| 66 | */ |
| 67 | public function getName() { |
| 68 | return $this->_name; |
| 69 | } |
| 70 | |
| 71 | /** |
| 72 | * Perform any registation or resource-allocation for a new queue |
| 73 | */ |
| 74 | public abstract function createQueue(); |
| 75 | |
| 76 | /** |
| 77 | * Perform any loading or pre-fetch for an existing queue. |
| 78 | */ |
| 79 | public abstract function loadQueue(); |
| 80 | |
| 81 | /** |
| 82 | * Release any resources claimed by the queue (memory, DB rows, etc) |
| 83 | */ |
| 84 | public abstract function deleteQueue(); |
| 85 | |
| 86 | /** |
| 87 | * Check if the queue exists. |
| 88 | * |
| 89 | * @return bool |
| 90 | */ |
| 91 | public abstract function existsQueue(); |
| 92 | |
| 93 | /** |
| 94 | * Add a new item to the queue. |
| 95 | * |
| 96 | * @param mixed $data |
| 97 | * Serializable PHP object or array. |
| 98 | * @param array $options |
| 99 | * Queue-dependent options; for example, if this is a |
| 100 | * priority-queue, then $options might specify the item's priority. |
| 101 | */ |
| 102 | public abstract function createItem($data, $options = array()); |
| 103 | |
| 104 | /** |
| 105 | * Determine number of items remaining in the queue. |
| 106 | * |
| 107 | * @return int |
| 108 | */ |
| 109 | public abstract function numberOfItems(); |
| 110 | |
| 111 | /** |
| 112 | * Get the next item. |
| 113 | * |
| 114 | * @param int $lease_time |
| 115 | * Seconds. |
| 116 | * |
| 117 | * @return object |
| 118 | * with key 'data' that matches the inputted data |
| 119 | */ |
| 120 | public abstract function claimItem($lease_time = 3600); |
| 121 | |
| 122 | /** |
| 123 | * Get the next item, even if there's an active lease |
| 124 | * |
| 125 | * @param int $lease_time |
| 126 | * Seconds. |
| 127 | * |
| 128 | * @return object |
| 129 | * with key 'data' that matches the inputted data |
| 130 | */ |
| 131 | public abstract function stealItem($lease_time = 3600); |
| 132 | |
| 133 | /** |
| 134 | * Remove an item from the queue. |
| 135 | * |
| 136 | * @param object $item |
| 137 | * The item returned by claimItem. |
| 138 | */ |
| 139 | public abstract function deleteItem($item); |
| 140 | |
| 141 | /** |
| 142 | * Return an item that could not be processed. |
| 143 | * |
| 144 | * @param object $item |
| 145 | * The item returned by claimItem. |
| 146 | */ |
| 147 | public abstract function releaseItem($item); |
| 148 | |
| 149 | } |