library/dddbl2/inc/Queue.class.php

   1 <?php
   2
   3 namespace DDDBL;
   4
   5 /**
   6   * this class implements a queue of handler, which
   7   * are called in a specified order.
   8   *
   9   * this allows the combiniation of different steps,
  10   * like database-connection management, query execution
  11   * and result parsing in a simple list of actions.
  12   *
  13   * Queue::getClone() returns a clone of the queue,
  14   * which allows modifications of the queue by
  15   * the executed handler.
  16   * in this way different problems, like substituions,
  17   * test-cases, statistics and much more can be solved,
  18   * without destroying the configured order for other queries.
  19   *
  20   **/
  21 class Queue {
  22
  23   /**
  24     * the sorted (!) queue of handler to execute
  25     *
  26     **/
  27   private $arrHandlerQueue = array();
  28
  29   /**
  30     * @see \DDDBL\DataObject
  31     *
  32     * an DataObject, which is used to store the states of the queue
  33     *
  34     **/
  35   private $objState   = null;
  36
  37   /**
  38     * @param $intPosition - the position to store the handler at
  39     * @param $cloHandler  - the handler to store in the queue
  40     *
  41     * @throws UnexpectedParameterTypeException - if the first parameter is not an integer
  42     * @throws UnexpectedParameterTypeException - if the second parameter is not a callable
  43     * @throws \Exception                       - if there is already a handler stored under the given position
  44     *
  45     * store the given handler under the given position in the queue.
  46     * if the position is already in use an expection is thrown.
  47     *
  48     **/
  49   public function addHandler($intPosition, $cloHandler) {
  50
  51     if(!is_int($intPosition))
  52       throw new UnexpectedParameterTypeException('integer', $intPosition);
  53
  54     if(!is_callable($cloHandler))
  55       throw new UnexpectedParameterTypeException('callable', $cloHandler);
  56
  57     if(!empty($this->arrHandlerQueue[$intPosition]))
  58       throw new \Exception("there is already a handler stored for position: $intPosition");
  59
  60     $this->arrHandlerQueue[$intPosition] = $cloHandler;
  61
  62     ksort($this->arrHandlerQueue);
  63
  64   }
  65
  66   /**
  67     * @param $intPosition - the position the handler for deletion is stored under
  68     *
  69     * @throws UnexpectedParameterTypeException - if the parameter is not an integer
  70     *
  71     * delete the handler stored under the given position
  72     *
  73     **/
  74   public function deleteHandler($intPosition) {
  75
  76     if(!is_int($intPosition))
  77       throw new UnexpectedParameterTypeException('integer', $intPosition);
  78
  79     if(array_key_exists($intPosition, $this->arrHandlerQueue))
  80       unset($this->arrHandlerQueue[$intPosition]);
  81
  82   }
  83
  84   /**
  85     * @returns (\DDDBL\Queue) - a clone of the queue-instance
  86     *
  87     * return a clone of the acutal queue
  88     *
  89     **/
  90   public function getClone() {
  91
  92     return clone $this;
  93
  94   }
  95
  96   /**
  97     * @param $arrParameter - the parameter to use when executing the queue-handler
  98     *
  99     * @returns (mixed) the state of "result"
 100     *
 101     * execute all handler in the queue, in the given
 102     * order from low to high. after execution return the
 103     * state "result".
 104     *
 105     * handler which generates an output
 106     * are expected to store the result in this state
 107     *
 108     **/
 109   public function execute(array $arrParameter) {
 110
 111     $this->getState()->add(array('result' => null));
 112
 113     foreach($this->arrHandlerQueue AS $cloHandler)
 114       $cloHandler($this, $arrParameter);
 115
 116     return $this->getState()->get('result');
 117
 118   }
 119
 120   /**
 121     * @returns (DataObject) - the DataObject which handles the states of the queue
 122     *
 123     * returns a reference to the DataObject, which
 124     * stores all states of the queue.
 125     *
 126     * if no object exists till now, a new one is created
 127     *
 128     **/
 129   public function getState() {
 130
 131     if(!is_object($this->objState))
 132       $this->objState = new DataObject();
 133
 134     return $this->objState;
 135
 136   }
 137
 138 }