application/hub/main/lists/class_BaseList.php

   1 <?php
   2 /**
   3  * A general list class
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 Hub Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class BaseList extends BaseHubSystem implements IteratorAggregate, Countable {
  25         // Exception constants
  26         const EXCEPTION_GROUP_ALREADY_ADDED = 0xf20;
  27         const EXCEPTION_GROUP_NOT_FOUND     = 0xf21;
  28         const EXCEPTION_INVALID_HASH        = 0xf22;
  29
  30         /**
  31          * List groups array
  32          */
  33         private $listGroups = array();
  34
  35         /**
  36          * List entries array
  37          */
  38         private $listEntries = array();
  39
  40         /**
  41          * List index array
  42          */
  43         private $listIndex = array();
  44
  45         /**
  46          * Protected constructor
  47          *
  48          * @param       $className      Name of the class
  49          * @return      void
  50          */
  51         protected function __construct ($className) {
  52                 // Call parent constructor
  53                 parent::__construct($className);
  54
  55                 // Remove some attributes
  56                 $this->removeNumberFormaters();
  57                 $this->removeSystemArray();
  58         }
  59
  60         /**
  61          * Getter for iterator instance from this list
  62          *
  63          * @return      $iteratorInstance       An instance of a Iterator class
  64          */
  65         public function getIterator () {
  66                 // Prepare a default iterator
  67                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('default_iterator_class');
  68
  69                 // And return it
  70                 return $iteratorInstance;
  71         }
  72
  73         /**
  74          * Checks wether the given group is set
  75          *
  76          * @param       $groupName      Group to check if found in list
  77          * @return      $isset          Wether the group is valid
  78          */
  79         public function isGroupSet ($groupName) {
  80                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName);
  81                 return isset($this->listGroups[$groupName]);
  82         }
  83
  84         /**
  85          * Adds the given group or if already added issues a ListGroupAlreadyAddedException
  86          *
  87          * @param       $groupName      Group to add
  88          * @return      void
  89          * @throws      ListGroupAlreadyAddedException  If the given group is already added
  90          */
  91         public function addGroup ($groupName) {
  92                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - START');
  93                 // Is the group already added?
  94                 if ($this->isGroupSet($groupName)) {
  95                         // Throw the exception here
  96                         throw new ListGroupAlreadyAddedException(array($this, $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
  97                 } // END - if
  98
  99                 // Add the group which is a simple array
 100                 $this->listGroups[$groupName] = ObjectFactory::createObjectByConfiguredName('list_group_class');
 101                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - FINISHED');
 102         }
 103
 104         /**
 105          * Adds the given instance to list group and sub group
 106          *
 107          * @param       $groupName      Group to add instance to
 108          * @param       $subGroup       Sub group to add instance to
 109          * @param       $instance       An instance of Visitable
 110          * @return      void
 111          * @throws      NoListGroupException    If the given group is not found
 112          */
 113         public function addInstance ($groupName, $subGroup, Visitable $instance) {
 114                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
 115                 // Is the group there?
 116                 if (!$this->isGroupSet($groupName)) {
 117                         // Throw the exception here
 118                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
 119                 } // END - if
 120
 121                 // Is the sub group there?
 122                 if (!$this->listGroups[$groupName]->isGroupSet($subGroup)) {
 123                         // Automatically add it
 124                         $this->listGroups[$groupName]->addGroup($subGroup);
 125                 } // END - if
 126
 127                 // Generate the hash
 128                 $hash = $this->generateHash($groupName, $subGroup, $instance);
 129
 130                 // Now add it to the group list and hash it
 131                 $this->listGroups[$groupName]->addEntry($subGroup, $hash);
 132
 133                 // Add the hash to the index
 134                 $this->listIndex[] = $hash;
 135
 136                 // Add the instance itself to the list
 137                 $this->listEntries[$hash] = $instance;
 138                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
 139         }
 140
 141         /**
 142          * Gets an array from given list
 143          *
 144          * @param       $list   The requested list
 145          * @return      $array  The requested array
 146          * @throws      NoListGroupException    If the given group is not found
 147          */
 148         public final function getArrayFromList ($list) {
 149                 // Is the group there?
 150                 if ((!is_null($list)) && (!$this->isGroupSet($list))) {
 151                         // Throw the exception here
 152                         throw new NoListGroupException(array($this, $list), self::EXCEPTION_GROUP_NOT_FOUND);
 153                 } // END - if
 154
 155                 // Init array
 156                 $array = array();
 157
 158                 // Is there another list?
 159                 if (!is_null($list)) {
 160                         // Then get it as well
 161                         $array = $this->listGroups[$list]->getArrayFromList(null);
 162                 } // END - if
 163
 164                 // Walk through all entries
 165                 foreach ($this->listIndex as $hash) {
 166                         //* DEBUG: */ print __METHOD__.':hash='.$hash."\n";
 167                         // Is the list entry set?
 168                         if ($this->isHashValid($hash)) {
 169                                 // Add it
 170                                 $array[] = $this->listEntries[$hash];
 171                                 //* DEBUG: */ print __METHOD__.": ADDED!\n";
 172                         } // END - if
 173                 } // END - foreach
 174
 175                 // Return it
 176                 return $array;
 177         }
 178
 179         /**
 180          * Adds the given entry to list group
 181          *
 182          * @param       $groupName      Group to add instance to
 183          * @param       $entry          An entry of any type
 184          * @return      void
 185          * @throws      NoListGroupException    If the given group is not found
 186          */
 187         public function addEntry ($groupName, $entry) {
 188                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): '.$groupName . ' - START');
 189                 // Is the group already added?
 190                 if (!$this->isGroupSet($groupName)) {
 191                         // Throw the exception here
 192                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
 193                 } // END - if
 194
 195                 // Generate hash
 196                 $hash = $this->generateHash($groupName, $groupName, $entry);
 197                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): hash='.$hash.'');
 198
 199                 // Add the hash to the index
 200                 $this->listIndex[] = $hash;
 201                 //* DEBUG: */ print $groupName.'/'.count($this->listIndex)."\n";
 202
 203                 // Now add the entry to the list
 204                 $this->listEntries[$hash] = $entry;
 205                 //* DEBUG: */ print $groupName.'/'.count($this->listEntries)."\n";
 206                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): '.$groupName . ' - FINISHED');
 207         }
 208
 209         /**
 210          * Generates a hash from given group, sub group and entry
 211          *
 212          * @param       $groupName      Group to add instance to
 213          * @param       $subGroup       Sub group to add instance to
 214          * @param       $entry          An entry of any type
 215          * @return      $hash           The generated
 216          */
 217         private function generateHash ($groupName, $subGroup, $entry) {
 218                 // Created entry, 'null' is default
 219                 $entry2 = 'null';
 220
 221                 // Determine type of entry
 222                 if (is_null($entry)) {
 223                         // Ignore this
 224                 } elseif ($entry instanceof FrameworkInterface) {
 225                         // Own instance detected
 226                         $entry2 = $entry->hashCode();
 227                 } elseif ((is_int($entry)) || (is_float($entry)) || (is_resource($entry))) {
 228                         // Integer/float/resource detected
 229                         $entry2 = gettype($entry) . ':' . $entry;
 230                 } elseif (is_string($entry)) {
 231                         // String found
 232                         $entry2 = crc32($entry) . ':' . strlen($entry);
 233                 } else {
 234                         // Unsupported type detected
 235                         $this->debugOutut(__METHOD__ . ': entry type ' . gettype($entry) . ' is unsupported.');
 236
 237                         // @TODO Extend this somehow?
 238                         $entry2 = gettype($entry);
 239                 }
 240
 241                 // Construct string which we shall hash
 242                 $hashString = $groupName . ':' . $subGroup . ':' . $entry2;
 243
 244                 // Hash it with fastest hasher
 245                 $hash = crc32($hashString);
 246
 247                 // And return it
 248                 return $hash;
 249         }
 250
 251         /**
 252          * Counts all entries in this list
 253          *
 254          * @return      $count  All entries in this list
 255          */
 256         public final function count () {
 257                 return count($this->listIndex);
 258         }
 259
 260         /**
 261          * Checks wether the given hash is valid
 262          *
 263          * @param       $hash           The hash we should validate
 264          * @return      $isValid        Wether the given hash is valid
 265          */
 266         public final function isHashValid ($hash) {
 267                 // Check it
 268                 $isValid = ((in_array($hash, $this->listIndex)) && (isset($this->listEntries[$hash])));
 269
 270                 // Return the result
 271                 return $isValid;
 272         }
 273
 274         /**
 275          * Gets an entry from given hash index
 276          *
 277          * @param       $hashIndex      The hash index to resolve the mapped entry
 278          * @return      $entry          Solved entry from list
 279          * @throws      InvalidListHashException If the solved hash index is invalid
 280          */
 281         public function getEntry ($hashIndex) {
 282                 // Get the hash value
 283                 $hash = $this->listIndex[$hashIndex];
 284
 285                 // Is the hash valid?
 286                 if (!$this->isHashValid($hash)) {
 287                         // Throw an exception here
 288                         throw new InvalidListHashException(array($this, $hash, $hashIndex), self::EXCEPTION_INVALID_HASH);
 289                 } // END - if
 290
 291                 // Now copy the entry
 292                 $entry = $this->listEntries[$hash];
 293
 294                 // Return it
 295                 return $entry;
 296         }
 297 }
 298
 299 //
 300 ?>