library/dddbl2/inc/DataObjectPool.class.php

   1 <?php
   2
   3 namespace DDDBL;
   4
   5 /**
   6   * The DataObjectPool is a class to  manage
   7   * the DataObjects for different types.
   8   *
   9   * DataObjects are stored within groups. Every group
  10   * has a validatator, with is applyed to
  11   * every DataObject stored in the group.
  12   * If no validatator is set, no validation will
  13   * be done.
  14   *
  15   * A DataObject is referenced by an identifier,
  16   * which is uniqiue within a group.
  17   *
  18   * when creating a DataObjectPool instance,
  19   * the wanted group is set. All following
  20   * operations are done at this group.
  21   *
  22   **/
  23 class DataObjectPool {
  24
  25   /**
  26     * the actual group to operate on
  27     *
  28     **/
  29   private $strGroup = null;
  30
  31   /**
  32     * list of validators for each group. structure:
  33     * array([group] => validator-callback,
  34     *       [group-n] => validator-callback-n, [..])
  35     *
  36     **/
  37   static private $arrValidatorList = array();
  38
  39   /**
  40     * list of DataObjects. stored in the following structure:
  41     * array([group][uniqueue-identifier] => DataObject-reference,
  42     *       [group-n][uniqueue-identifier-n] => DataObject-reference-n, [..])
  43     *
  44     **/
  45   static private $arrDataObjects = array();
  46
  47   /**
  48     * @param $strGroup - the group of DataObjects to operate on
  49     *
  50     * @throws UnexpectedParameterTypeException - if given group is not a string
  51     *
  52     * create an instance of DataObjectPool and store the group
  53     * to operate on
  54     *
  55     **/
  56   public function __construct($strGroup) {
  57
  58     if(!is_string($strGroup))
  59       throw new UnexpectedParameterTypeException('string', $strGroup);
  60
  61     $this->strGroup = $strGroup;
  62
  63     if(!array_key_exists($this->strGroup, self::$arrValidatorList))
  64       self::$arrValidatorList[$this->strGroup] = null;
  65
  66     if(!array_key_exists($this->strGroup, self::$arrDataObjects))
  67       self::$arrDataObjects[$this->strGroup] = array();
  68
  69   }
  70
  71   /**
  72     * @param $cloValidator - the validator to set for the group
  73     *
  74     * @throws UnexpectedParameterTypeException - if given validator is not a callable
  75     *
  76     * set the validator for the active group. this validator
  77     * is given to each newly created DataObject.
  78     * if it is changed, the existing DataObjects are
  79     * *NOT* revalidated.
  80     *
  81     **/
  82   public function setValidator($cloValidator) {
  83
  84     if(!is_callable($cloValidator))
  85       throw new UnexpectedParameterTypeException('string', $cloValidator);
  86
  87     self::$arrValidatorList[$this->strGroup] = $cloValidator;
  88
  89   }
  90
  91   /**
  92     * @param $strIdentifier - the unique identifier of the DataObject
  93     * @param $arrData       - the data to store in the DataObject
  94     *
  95     * @see DataObject:add()
  96     *
  97     * @throws UnexpectedParameterTypeException - if identifier is not a string
  98     * @throws \Exception                       - if given identifier is not unique
  99     *
 100     * @returns (DataObject) - reference to the created DataObject-instance
 101     *
 102     * create a new DataObject and store it in the pool. The given
 103     * identifier is the key to retrieve the DataObject from the pool.
 104     * The given data are stored within the DataObject.
 105     *
 106     * After creation and storage of the DataObject, a reference
 107     * to the object is returned
 108     *
 109     **/
 110   public function add($strIdentifier, array $arrData) {
 111
 112     if(!is_string($strIdentifier))
 113       throw new UnexpectedParameterTypeException('string', $strIdentifier);
 114
 115     if($this->exists($strIdentifier))
 116       throw new \Exception ("identifier already in use: $strIdentifier");
 117
 118     $objDataObject = new DataObject(self::$arrValidatorList[$this->strGroup], $arrData);
 119
 120     self::$arrDataObjects[$this->strGroup][$strIdentifier] = $objDataObject;
 121
 122     return $objDataObject;
 123
 124   }
 125
 126   /**
 127     * @param $strIdentifier - the identifier of the object to delete
 128     *
 129     * @throws UnexpectedParameterTypeException - if given identifier is not a string
 130     * @throws \Exception                       - if the given identifier is not known
 131     *
 132     * delete the stored DataObject from the DataObjectPool
 133     *
 134     **/
 135   public function delete($strIdentifier) {
 136
 137     if(!is_string($strIdentifier))
 138       throw new UnexpectedParameterTypeException('string', $strIdentifier);
 139
 140     if(!$this->exists($strIdentifier))
 141       throw new \Exception ("DataObject not found, identifier unknown: $strIdentifier");
 142
 143     unset(self::$arrDataObjects[$this->strGroup][$strIdentifier]);
 144
 145   }
 146
 147   /**
 148     * @param $strIdentifier - the identifier to check
 149     *
 150     * @throws UnexpectedParameterTypeException - if given identifier is not a string
 151     *
 152     * @returns (boolean) true, if the identifier exists
 153     * @returns (boolean) false, if the identifier do not exists
 154     *
 155     **/
 156   public function exists($strIdentifier) {
 157
 158     if(!is_string($strIdentifier))
 159       throw new UnexpectedParameterTypeException('string', $strIdentifier);
 160
 161     if(!isset(self::$arrDataObjects[$this->strGroup][$strIdentifier]))
 162       return false;
 163
 164     return true;
 165
 166   }
 167
 168   /**
 169     * @param $strIdentifier - the identifier of the DataObject to retrieve
 170     *
 171     * @throws UnexpectedParameterTypeException - if given identifier is not a string
 172     * @throws \Exception                       - if given identifier is unknown
 173     *
 174     * @returns (DataObject) - reference to the DataObject
 175     *
 176     * returns a reference to the DataObject stored under the identifer
 177     *
 178     **/
 179   public function get($strIdentifier) {
 180
 181     if(!is_string($strIdentifier))
 182       throw new UnexpectedParameterTypeException('string', $strIdentifier);
 183
 184     if(!$this->exists($strIdentifier))
 185       throw new \Exception ("DataObject not found, identifier unknown: $strIdentifier");
 186
 187     return self::$arrDataObjects[$this->strGroup][$strIdentifier];
 188
 189   }
 190
 191   /**
 192     * @returns (array) - list of all DataObjects of the active group
 193     *
 194     * returns an array of all stored DataObjects of the active group
 195     * with the following structure:
 196     *
 197     * array([identifier] => DataObject-reference,
 198     *       [identifier-n] => DataObject-reference-n, [..])
 199     *
 200     **/
 201   public function getAll() {
 202
 203     return self::$arrDataObjects[$this->strGroup];
 204
 205   }
 206
 207 }