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
  56         /**
  57          * Getter for iterator instance from this list
  58          *
  59          * @return      $iteratorInstance       An instance of a Iterator class
  60          */
  61         public function getIterator () {
  62                 // Prepare a default iterator
  63                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('default_iterator_class');
  64
  65                 // And return it
  66                 return $iteratorInstance;
  67         }
  68
  69         /**
  70          * Checks wether the given group is set
  71          *
  72          * @param       $groupName      Group to check if found in list
  73          * @return      $isset          Wether the group is valid
  74          */
  75         public function isGroupSet ($groupName) {
  76                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName);
  77                 return isset($this->listGroups[$groupName]);
  78         }
  79
  80         /**
  81          * Adds the given group or if already added issues a ListGroupAlreadyAddedException
  82          *
  83          * @param       $groupName      Group to add
  84          * @return      void
  85          * @throws      ListGroupAlreadyAddedException  If the given group is already added
  86          */
  87         public function addGroup ($groupName) {
  88                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - START');
  89                 // Is the group already added?
  90                 if ($this->isGroupSet($groupName)) {
  91                         // Throw the exception here
  92                         throw new ListGroupAlreadyAddedException(array($this, $groupName), self::EXCEPTION_GROUP_ALREADY_ADDED);
  93                 } // END - if
  94
  95                 // Add the group which is a simple array
  96                 $this->listGroups[$groupName] = ObjectFactory::createObjectByConfiguredName('list_group_class');
  97                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName . ' - FINISHED');
  98         }
  99
 100         /**
 101          * Adds the given instance to list group and sub group
 102          *
 103          * @param       $groupName      Group to add instance to
 104          * @param       $subGroup       Sub group to add instance to
 105          * @param       $instance       An instance of Visitable
 106          * @return      void
 107          * @throws      NoListGroupException    If the given group is not found
 108          */
 109         public function addInstance ($groupName, $subGroup, Visitable $instance) {
 110                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
 111                 // Is the group there?
 112                 if (!$this->isGroupSet($groupName)) {
 113                         // Throw the exception here
 114                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
 115                 } // END - if
 116
 117                 // Is the sub group there?
 118                 if (!$this->listGroups[$groupName]->isGroupSet($subGroup)) {
 119                         // Automatically add it
 120                         $this->listGroups[$groupName]->addGroup($subGroup);
 121                 } // END - if
 122
 123                 // Generate the hash
 124                 $hash = $this->generateHash($groupName, $subGroup, $instance);
 125
 126                 // Now add it to the group list and hash it
 127                 $this->listGroups[$groupName]->addEntry($subGroup, $hash);
 128
 129                 // Add the hash to the index
 130                 $this->listIndex[] = $hash;
 131
 132                 // Add the instance itself to the list
 133                 $this->listEntries[$hash] = $instance;
 134                 //* DEBUG: */ $this->debugOutput(__METHOD__.': '.$groupName  . '/' . $subGroup . ' - START');
 135         }
 136
 137         /**
 138          * Gets an array from given list
 139          *
 140          * @param       $list   The requested list
 141          * @return      $array  The requested array
 142          * @throws      NoListGroupException    If the given group is not found
 143          */
 144         public final function getArrayFromList ($list) {
 145                 // Is the group there?
 146                 if ((!is_null($list)) && (!$this->isGroupSet($list))) {
 147                         // Throw the exception here
 148                         throw new NoListGroupException(array($this, $list), self::EXCEPTION_GROUP_NOT_FOUND);
 149                 } // END - if
 150
 151                 // Init array
 152                 $array = array();
 153
 154                 // Is there another list?
 155                 if (!is_null($list)) {
 156                         // Then get it as well
 157                         $array = $this->listGroups[$list]->getArrayFromList(null);
 158                 } // END - if
 159
 160                 // Walk through all entries
 161                 foreach ($this->listIndex as $hash) {
 162                         //* DEBUG: */ print __METHOD__.':hash='.$hash."\n";
 163                         // Is the list entry set?
 164                         if ($this->isHashValid($hash)) {
 165                                 // Add it
 166                                 $array[] = $this->listEntries[$hash];
 167                                 //* DEBUG: */ print __METHOD__.": ADDED!\n";
 168                         } // END - if
 169                 } // END - foreach
 170
 171                 // Return it
 172                 return $array;
 173         }
 174
 175         /**
 176          * Adds the given entry to list group
 177          *
 178          * @param       $groupName      Group to add instance to
 179          * @param       $entry          An entry of any type
 180          * @return      void
 181          * @throws      NoListGroupException    If the given group is not found
 182          */
 183         public function addEntry ($groupName, $entry) {
 184                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): '.$groupName . ' - START');
 185                 // Is the group already added?
 186                 if (!$this->isGroupSet($groupName)) {
 187                         // Throw the exception here
 188                         throw new NoListGroupException(array($this, $groupName), self::EXCEPTION_GROUP_NOT_FOUND);
 189                 } // END - if
 190
 191                 // Generate hash
 192                 $hash = $this->generateHash($groupName, $groupName, $entry);
 193                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): hash='.$hash.'');
 194
 195                 // Add the hash to the index
 196                 $this->listIndex[] = $hash;
 197                 //* DEBUG: */ print $groupName.'/'.count($this->listIndex)."\n";
 198
 199                 // Now add the entry to the list
 200                 $this->listEntries[$hash] = $entry;
 201                 //* DEBUG: */ print $groupName.'/'.count($this->listEntries)."\n";
 202                 //* DEBUG: */ $this->debugOutput(__METHOD__.'('.$this->__toString().'): '.$groupName . ' - FINISHED');
 203         }
 204
 205         /**
 206          * Generates a hash from given group, sub group and entry
 207          *
 208          * @param       $groupName      Group to add instance to
 209          * @param       $subGroup       Sub group to add instance to
 210          * @param       $entry          An entry of any type
 211          * @return      $hash           The generated
 212          */
 213         private function generateHash ($groupName, $subGroup, $entry) {
 214                 // Created entry, 'null' is default
 215                 $entry2 = 'null';
 216
 217                 // Determine type of entry
 218                 if (is_null($entry)) {
 219                         // Ignore this
 220                 } elseif ($entry instanceof FrameworkInterface) {
 221                         // Own instance detected
 222                         $entry2 = $entry->hashCode();
 223                 } elseif ((is_int($entry)) || (is_float($entry)) || (is_resource($entry))) {
 224                         // Integer/float/resource detected
 225                         $entry2 = gettype($entry) . ':' . $entry;
 226                 } elseif (is_string($entry)) {
 227                         // String found
 228                         $entry2 = crc32($entry) . ':' . strlen($entry);
 229                 } else {
 230                         // Unsupported type detected
 231                         $this->debugOutut(__METHOD__ . ': entry type ' . gettype($entry) . ' is unsupported.');
 232
 233                         // @TODO Extend this somehow?
 234                         $entry2 = gettype($entry);
 235                 }
 236
 237                 // Construct string which we shall hash
 238                 $hashString = $groupName . ':' . $subGroup . ':' . $entry2;
 239
 240                 // Hash it with fastest hasher
 241                 $hash = crc32($hashString);
 242
 243                 // And return it
 244                 return $hash;
 245         }
 246
 247         /**
 248          * Counts all entries in this list
 249          *
 250          * @return      $count  All entries in this list
 251          */
 252         public final function count () {
 253                 return count($this->listIndex);
 254         }
 255
 256         /**
 257          * Checks wether the given hash is valid
 258          *
 259          * @param       $hash           The hash we should validate
 260          * @return      $isValid        Wether the given hash is valid
 261          */
 262         public final function isHashValid ($hash) {
 263                 // Check it
 264                 $isValid = ((in_array($hash, $this->listIndex)) && (isset($this->listEntries[$hash])));
 265
 266                 // Return the result
 267                 return $isValid;
 268         }
 269
 270         /**
 271          * Gets an entry from given hash index
 272          *
 273          * @param       $hashIndex      The hash index to resolve the mapped entry
 274          * @return      $entry          Solved entry from list
 275          * @throws      InvalidListHashException If the solved hash index is invalid
 276          */
 277         public function getEntry ($hashIndex) {
 278                 // Get the hash value
 279                 $hash = $this->listIndex[$hashIndex];
 280
 281                 // Is the hash valid?
 282                 if (!$this->isHashValid($hash)) {
 283                         // Throw an exception here
 284                         throw new InvalidListHashException(array($this, $hash, $hashIndex), self::EXCEPTION_INVALID_HASH);
 285                 } // END - if
 286
 287                 // Now copy the entry
 288                 $entry = $this->listEntries[$hash];
 289
 290                 // Return it
 291                 return $entry;
 292         }
 293 }
 294
 295 //
 296 ?>