inc/classes/main/stacker/file/class_BaseFileStack.php

   1 <?php
   2 /**
   3  * A general file-based stack class
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2013 Core 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 BaseFileStack extends BaseStacker {
  25         /**
  26          * Magic for this stack
  27          */
  28         const STACK_MAGIC = 'STACKv0.1';
  29
  30         /**
  31          * Separator magic->count
  32          */
  33         const SEPARATOR_MAGIC_COUNT = 0x00;
  34
  35         /**
  36          * Separator position->entries
  37          */
  38         const SEPARATOR_SEEK_POS_ENTRIES = 0xff;
  39
  40         /**
  41          * Separator hash->name
  42          */
  43         const SEPARATOR_HASH_NAME = 0x05;
  44
  45         /**
  46          * Length of count
  47          */
  48         const COUNT_LENGTH = 20;
  49
  50         /**
  51          * Length of position
  52          */
  53         const COUNT_POSITION = 20;
  54
  55         /**
  56          * Protected constructor
  57          *
  58          * @param       $className      Name of the class
  59          * @return      void
  60          */
  61         protected function __construct ($className) {
  62                 // Call parent constructor
  63                 parent::__construct($className);
  64         }
  65
  66         /**
  67          * Checks whether the file header is initialized
  68          *
  69          * @return      $isInitialized  Whether the file header is initialized
  70          */
  71         private function isFileHeaderInitialized () {
  72                 // Default is not initialized
  73                 $isInitialized = FALSE;
  74
  75                 // Is the file initialized?
  76                 if ($this->isFileInitialized()) {
  77                         // Some bytes has been written, so rewind to start of it.
  78                         $this->getIteratorInstance()->rewind();
  79
  80                         // Read file header
  81                         $this->readFileHeader();
  82                 } // END - if
  83
  84                 // Return result
  85                 return $isInitialized;
  86         }
  87
  88         /**
  89          * Checks whether the file-based stack has been initialized
  90          *
  91          * @return      $isInitialized          Whether the file's size is zero
  92          */
  93         private function isFileInitialized () {
  94                 // Default is not initialized
  95                 $isInitialized = FALSE;
  96
  97                 // Get it from iterator which holds the pointer instance. If FALSE is returned
  98                 $fileSize = $this->getIteratorInstance()->size();
  99
 100                 /*
 101                  * The returned file size should not be FALSE or NULL as this means
 102                  * that the pointer class does not work correctly.
 103                  */
 104                 assert(is_int($fileSize));
 105
 106                 // Is more than 0 returned?
 107                 if ($fileSize > 0) {
 108                         // So is the header written?
 109                         $isInitialized = $this->getIteratorInstance()->isHeaderInitialized();
 110                 } // END - if
 111
 112                 // Return result
 113                 return $isInitialized;
 114         }
 115
 116         /**
 117          * Creates the file-stack's header
 118          *
 119          * @return      void
 120          */
 121         private function createFileHeader () {
 122                 // The file's header should not be initialized here
 123                 assert(!$this->isFileHeaderInitialized());
 124
 125                 // Init  counter
 126                 $this->getIteratorInstance()->initCounter();
 127
 128                 // Flush file header
 129                 $this->flushFileHeader();
 130         }
 131
 132         /**
 133          * Flushes the file header
 134          *
 135          * @return      void
 136          */
 137         private function flushFileHeader () {
 138                 // Put all informations together
 139                 $header = sprintf('%s%s%s%s%s',
 140                         // Magic
 141                         self::STACK_MAGIC,
 142
 143                         // Separator magic<->count
 144                         chr(self::SEPARATOR_MAGIC_COUNT),
 145
 146                         // Total entries (will be zero) and pad it to 20 chars
 147                         str_pad($this->dec2hex($this->getIteratorInstance()->getCount()), self::COUNT_LENGTH, '0', STR_PAD_LEFT),
 148
 149                         // Position (will be zero)
 150                         str_pad($this->dec2hex(0, 2), self::COUNT_POSITION, '0', STR_PAD_LEFT),
 151
 152                         // Separator position<->entries
 153                         chr(self::SEPARATOR_SEEK_POS_ENTRIES)
 154                 );
 155
 156                 // Write it to disk
 157                 $this->getIteratorInstance()->writeAtPosition(0, $header);
 158         }
 159
 160         /**
 161          * Initializes this file-based stack.
 162          *
 163          * @param       $fileName       File name of this stack
 164          * @return      void
 165          */
 166         protected function initFileStack ($fileName) {
 167                 // Get a file i/o pointer instance
 168                 $pointerInstance = ObjectFactory::createObjectByConfiguredName('file_raw_input_output_class', array($fileName));
 169
 170                 // Get iterator instance
 171                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('file_io_iterator_class', array($pointerInstance));
 172
 173                 // Is the instance implementing the right interface?
 174                 assert($iteratorInstance instanceof SeekableWritableFileIterator);
 175
 176                 // Set iterator here
 177                 $this->setIteratorInstance($iteratorInstance);
 178
 179                 // Is the file's header initialized?
 180                 if ($this->isFileHeaderInitialized()) {
 181                         // Then load it
 182                         $this->loadFileHeader();
 183                 } else {
 184                         // No, then create it (which may pre-allocate the stack)
 185                         $this->createFileHeader();
 186
 187                         // And pre-allocate a bit
 188                         $this->preAllocateFile();
 189                 }
 190         }
 191
 192         /**
 193          * Initializes given stacker
 194          *
 195          * @param       $stackerName    Name of the stack
 196          * @param       $forceReInit    Force re-initialization
 197          * @return      void
 198          * @throws      AlreadyInitializedStackerException      If the stack is already initialized
 199          */
 200         public function initStack ($stackerName, $forceReInit = FALSE) {
 201                 // Is the stack already initialized?
 202                 if (($forceReInit === FALSE) && ($this->isStackInitialized($stackerName))) {
 203                         // Then throw the exception
 204                         throw new AlreadyInitializedStackerException(array($this, $stackerName, $forceReInit), self::EXCEPTION_STACKER_ALREADY_INITIALIZED);
 205                 } // END - if
 206
 207                 // Initialize the given stack
 208                 $this->partialStub('stackerName=' . $stackerName . ',forceReInit=' . intval($forceReInit));
 209         }
 210
 211         /**
 212          * Checks whether the given stack is initialized (set in array $stackers)
 213          *
 214          * @param       $stackerName    Name of the stack
 215          * @return      $isInitialized  Whether the stack is initialized
 216          */
 217         public function isStackInitialized ($stackerName) {
 218                 // Is is there?
 219                 $this->partialStub('stackerName=' . $stackerName);
 220                 $isInitialized = TRUE;
 221
 222                 // Return result
 223                 return $isInitialized;
 224         }
 225
 226         /**
 227          * Getter for size of given stack (array count)
 228          *
 229          * @param       $stackerName    Name of the stack
 230          * @return      $count                  Size of stack (array count)
 231          * @throws      NoStackerException      If given stack is missing
 232          */
 233         public function getStackCount ($stackerName) {
 234                 // Is the stack not yet initialized?
 235                 if (!$this->isStackInitialized($stackerName)) {
 236                         // Throw an exception
 237                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 238                 } // END - if
 239
 240                 // Now, count the array of entries
 241                 $this->partialStub('stackerName=' . $stackerName);
 242                 $count = 0;
 243
 244                 // Return result
 245                 return $count;
 246         }
 247
 248         /**
 249          * Adds a value to given stack
 250          *
 251          * @param       $stackerName    Name of the stack
 252          * @param       $value                  Value to add to this stacker
 253          * @return      void
 254          * @throws      FullStackerException    Thrown if the stack is full
 255          */
 256         protected function addValue ($stackerName, $value) {
 257                 // Is the stack not yet initialized or full?
 258                 if (!$this->isStackInitialized($stackerName)) {
 259                         // Then do it here
 260                         $this->initStack($stackerName);
 261                 } elseif ($this->isStackFull($stackerName)) {
 262                         // Stacker is full
 263                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
 264                 }
 265
 266                 // Now add the value to the stack
 267                 $this->partialStub('stackerName=' . $stackerName . ',value[]=' . gettype($value));
 268         }
 269
 270         /**
 271          * Get last value from named stacker
 272          *
 273          * @param       $stackerName    Name of the stack
 274          * @return      $value                  Value of last added value
 275          * @throws      NoStackerException      If the named stacker was not found
 276          * @throws      EmptyStackerException   If the named stacker is empty
 277          */
 278         protected function getLastValue ($stackerName) {
 279                 // Is the stack not yet initialized or full?
 280                 if (!$this->isStackInitialized($stackerName)) {
 281                         // Throw an exception
 282                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 283                 } elseif ($this->isStackEmpty($stackerName)) {
 284                         // Throw an exception
 285                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 286                 }
 287
 288                 // Now get the last value
 289                 $this->partialStub('stackerName=' . $stackerName);
 290                 $value = NULL;
 291
 292                 // Return it
 293                 return $value;
 294         }
 295
 296         /**
 297          * Get first value from named stacker
 298          *
 299          * @param       $stackerName    Name of the stack
 300          * @return      $value                  Value of last added value
 301          * @throws      NoStackerException      If the named stacker was not found
 302          * @throws      EmptyStackerException   If the named stacker is empty
 303          */
 304         protected function getFirstValue ($stackerName) {
 305                 // Is the stack not yet initialized or full?
 306                 if (!$this->isStackInitialized($stackerName)) {
 307                         // Throw an exception
 308                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 309                 } elseif ($this->isStackEmpty($stackerName)) {
 310                         // Throw an exception
 311                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 312                 }
 313
 314                 // Now get the first value
 315                 $this->partialStub('stackerName=' . $stackerName);
 316                 $value = NULL;
 317
 318                 // Return it
 319                 return $value;
 320         }
 321
 322         /**
 323          * "Pops" last entry from stack
 324          *
 325          * @param       $stackerName    Name of the stack
 326          * @return      $value                  Value "poped" from array
 327          * @throws      NoStackerException      If the named stacker was not found
 328          * @throws      EmptyStackerException   If the named stacker is empty
 329          */
 330         protected function popLast ($stackerName) {
 331                 // Is the stack not yet initialized or full?
 332                 if (!$this->isStackInitialized($stackerName)) {
 333                         // Throw an exception
 334                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 335                 } elseif ($this->isStackEmpty($stackerName)) {
 336                         // Throw an exception
 337                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 338                 }
 339
 340                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 341                 $this->partialStub('stackerName=' . $stackerName);
 342                 return NULL;
 343         }
 344
 345         /**
 346          * "Pops" first entry from stack
 347          *
 348          * @param       $stackerName    Name of the stack
 349          * @return      $value                  Value "shifted" from array
 350          * @throws      NoStackerException      If the named stacker was not found
 351          * @throws      EmptyStackerException   If the named stacker is empty
 352          */
 353         protected function popFirst ($stackerName) {
 354                 // Is the stack not yet initialized or full?
 355                 if (!$this->isStackInitialized($stackerName)) {
 356                         // Throw an exception
 357                         throw new NoStackerException(array($this, $stackerName), self::EXCEPTION_NO_STACKER_FOUND);
 358                 } elseif ($this->isStackEmpty($stackerName)) {
 359                         // Throw an exception
 360                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 361                 }
 362
 363                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 364                 $this->partialStub('stackerName=' . $stackerName);
 365                 return NULL;
 366         }
 367 }
 368
 369 // [EOF]
 370 ?>