inc/classes/main/iterator/file/class_FileIterator.php

   1 <?php
   2 /**
   3  * A file iterator
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 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 FileIterator extends BaseIterator implements SeekableWritableFileIterator {
  25         /**
  26          * Protected constructor
  27          *
  28          * @return      void
  29          */
  30         protected function __construct () {
  31                 // Call parent constructor
  32                 parent::__construct(__CLASS__);
  33         }
  34
  35         /**
  36          * Creates an instance of this class
  37          *
  38          * @param       $pointerInstance        An instance of a Block class
  39          * @return      $iteratorInstance       An instance of a Iterator class
  40          */
  41         public final static function createFileIterator (Block $blockInstance) {
  42                 // Get new instance
  43                 $iteratorInstance = new FileIterator();
  44
  45                 // Set the instance here
  46                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput(sprintf('[%s:%d] Setting blockInstance=%s ...', __METHOD__, __LINE__, $blockInstance->__toString()));
  47                 $iteratorInstance->setBlockInstance($blockInstance);
  48
  49                 // Return the prepared instance
  50                 return $iteratorInstance;
  51         }
  52
  53         /**
  54          * Gets currently read data
  55          *
  56          * @return      $current        Currently read data
  57          */
  58         public function current () {
  59                 // Call block instance
  60                 return $this->getBlockInstance()->current();
  61         }
  62
  63         /**
  64          * Gets current seek position ("key").
  65          *
  66          * @return      $key    Current key in iteration
  67          */
  68         public function key () {
  69                 // Return it
  70                 return $this->getBlockInstance()->determineSeekPosition();
  71         }
  72
  73         /**
  74          * Advances to next "block" of bytes
  75          *
  76          * @return      void
  77          */
  78         public function next () {
  79                 // Call block instance
  80                 $this->getBlockInstance()->next();
  81         }
  82
  83         /**
  84          * Rewinds to the beginning of the file
  85          *
  86          * @return      $status         Status of this operation
  87          */
  88         public function rewind () {
  89                 // Call block instance
  90                 return $this->getBlockInstance()->rewind();
  91         }
  92
  93         /**
  94          * Checks wether the current entry is valid (not at the end of the file).
  95          * This method will return TRUE if an emptied (nulled) entry has been found.
  96          *
  97          * @return      $isValid        Whether the next entry is valid
  98          */
  99         public function valid () {
 100                 // Call block instance
 101                 return $this->getBlockInstance()->valid();
 102         }
 103
 104         /**
 105          * Seeks to given position
 106          *
 107          * @param       $seekPosition   Seek position in file
 108          * @return      $status                 Status of this operation
 109          */
 110         public function seek ($seekPosition) {
 111                 // Call block instance
 112                 return $this->getBlockInstance()->seek($seekPosition);
 113         }
 114
 115         /**
 116          * Writes at given position by seeking to it.
 117          *
 118          * @param       $seekPosition   Seek position in file
 119          * @param       $data                   Data to be written
 120          * @return      void
 121          */
 122         public function writeAtPosition ($seekPosition, $data) {
 123                 // First seek to it
 124                 $this->seek($seekPosition);
 125
 126                 // Then write the data at that position
 127                 $this->getBlockInstance()->writeToFile($data);
 128         }
 129
 130         /**
 131          * Size of file stack
 132          *
 133          * @return      $size   Size (in bytes) of file
 134          */
 135         public function size () {
 136                 // Call the block object
 137                 $size = $this->getBlockInstance()->size();
 138
 139                 // Return result
 140                 return $size;
 141         }
 142
 143         /**
 144          * Reads given amount of bytes from file.
 145          *
 146          * @param       $bytes  Amount of bytes to read
 147          * @return      $data   Data read from file
 148          */
 149         public function read ($bytes) {
 150                 // Call block instance
 151                 return $this->getBlockInstance()->read($bytes);
 152         }
 153
 154         /**
 155          * Analyzes entries in index file. This will count all found (and valid)
 156          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
 157          * only gaps are found, the file is considered as "virgin" (no entries).
 158          *
 159          * @return      void
 160          */
 161         public function analyzeFile () {
 162                 // Just call the block instance
 163                 $this->getBlockInstance()->analyzeFile();
 164         }
 165
 166         /**
 167          * Checks whether the file header is initialized
 168          *
 169          * @return      $isInitialized  Whether the file header is initialized
 170          */
 171         public function isFileHeaderInitialized () {
 172                 // Just call the block instance
 173                 return $this->getBlockInstance()->isFileHeaderInitialized();
 174         }
 175
 176         /**
 177          * Creates the assigned file
 178          *
 179          * @return      void
 180          */
 181         public function createFileHeader () {
 182                 // Just call the block instance
 183                 $this->getBlockInstance()->createFileHeader();
 184         }
 185
 186         /**
 187          * Pre-allocates file (if enabled) with some space for later faster write access.
 188          *
 189          * @param       $type   Type of the file
 190          * @return      void
 191          */
 192         public function preAllocateFile ($type) {
 193                 // Just call the block instance
 194                 $this->getBlockInstance()->preAllocateFile($type);
 195         }
 196
 197         /**
 198          * Initializes counter for valid entries, arrays for damaged entries and
 199          * an array for gap seek positions. If you call this method on your own,
 200          * please re-analyze the file structure. So you are better to call
 201          * analyzeFile() instead of this method.
 202          *
 203          * @return      void
 204          */
 205         public function initCountersGapsArray () {
 206                 // Call block instance
 207                 $this->getBlockInstance()->initCountersGapsArray();
 208         }
 209
 210         /**
 211          * Getter for header size
 212          *
 213          * @return      $totalEntries   Size of file header
 214          */
 215         public final function getHeaderSize () {
 216                 // Call block instance
 217                 return $this->getBlockInstance()->getHeaderSize();
 218         }
 219
 220         /**
 221          * Setter for header size
 222          *
 223          * @param       $headerSize             Size of file header
 224          * @return      void
 225          */
 226         public final function setHeaderSize ($headerSize) {
 227                 // Call block instance
 228                 $this->getBlockInstance()->setHeaderSize($headerSize);
 229         }
 230
 231         /**
 232          * Getter for header array
 233          *
 234          * @return      $totalEntries   Size of file header
 235          */
 236         public final function getHeader () {
 237                 // Call block instance
 238                 return $this->getBlockInstance()->getHeader();
 239         }
 240
 241         /**
 242          * Setter for header
 243          *
 244          * @param       $header         Array for a file header
 245          * @return      void
 246          */
 247         public final function setHeader (array $header) {
 248                 // Call block instance
 249                 $this->getBlockInstance()->setHeader($header);
 250         }
 251
 252         /**
 253          * Updates seekPosition attribute from file to avoid to much access on file.
 254          *
 255          * @return      void
 256          */
 257         public function updateSeekPosition () {
 258                 // Call block instance
 259                 $this->getBlockInstance()->updateSeekPosition();
 260         }
 261
 262         /**
 263          * Getter for total entries
 264          *
 265          * @return      $totalEntries   Total entries in this file
 266          */
 267         public final function getCounter () {
 268                 // Call block instance
 269                 return $this->getBlockInstance()->getCounter();
 270         }
 271
 272         /**
 273          * "Getter" for file size
 274          *
 275          * @return      $fileSize       Size of currently loaded file
 276          */
 277         public function getFileSize () {
 278                 // Call block instance
 279                 return $this->getBlockInstance()->getFileSize();
 280         }
 281 }
 282
 283 // [EOF]
 284 ?>