Debugging continued:
[core.git] / inc / main / classes / iterator / file / class_FileIterator.php
1 <?php
2 // Own namespace
3 namespace CoreFramework\Iterator\File;
4
5 /**
6  * A file iterator
7  *
8  * @author              Roland Haeder <webmaster@ship-simu.org>
9  * @version             0.0.0
10  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
11  * @license             GNU GPL 3.0 or any newer version
12  * @link                http://www.ship-simu.org
13  *
14  * This program is free software: you can redistribute it and/or modify
15  * it under the terms of the GNU General Public License as published by
16  * the Free Software Foundation, either version 3 of the License, or
17  * (at your option) any later version.
18  *
19  * This program is distributed in the hope that it will be useful,
20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22  * GNU General Public License for more details.
23  *
24  * You should have received a copy of the GNU General Public License
25  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
26  */
27 class FileIterator extends BaseIterator implements SeekableWritableFileIterator {
28         /**
29          * Protected constructor
30          *
31          * @return      void
32          */
33         protected function __construct () {
34                 // Call parent constructor
35                 parent::__construct(__CLASS__);
36         }
37
38         /**
39          * Creates an instance of this class
40          *
41          * @param       $pointerInstance        An instance of a Block class
42          * @return      $iteratorInstance       An instance of a Iterator class
43          */
44         public final static function createFileIterator (Block $blockInstance) {
45                 // Get new instance
46                 $iteratorInstance = new FileIterator();
47
48                 // Set the instance here
49                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d] Setting blockInstance=%s ...', __METHOD__, __LINE__, $blockInstance->__toString()));
50                 $iteratorInstance->setBlockInstance($blockInstance);
51
52                 // Return the prepared instance
53                 return $iteratorInstance;
54         }
55
56         /**
57          * Gets currently read data
58          *
59          * @return      $current        Currently read data
60          */
61         public function current () {
62                 // Call block instance
63                 return $this->getBlockInstance()->current();
64         }
65
66         /**
67          * Gets current seek position ("key").
68          *
69          * @return      $key    Current key in iteration
70          */
71         public function key () {
72                 // Return it
73                 return $this->getBlockInstance()->determineSeekPosition();
74         }
75
76         /**
77          * Advances to next "block" of bytes
78          *
79          * @return      void
80          */
81         public function next () {
82                 // Call block instance
83                 $this->getBlockInstance()->next();
84         }
85
86         /**
87          * Rewinds to the beginning of the file
88          *
89          * @return      $status         Status of this operation
90          */
91         public function rewind () {
92                 // Call block instance
93                 return $this->getBlockInstance()->rewind();
94         }
95
96         /**
97          * Checks wether the current entry is valid (not at the end of the file).
98          * This method will return TRUE if an emptied (nulled) entry has been found.
99          *
100          * @return      $isValid        Whether the next entry is valid
101          */
102         public function valid () {
103                 // Call block instance
104                 return $this->getBlockInstance()->valid();
105         }
106
107         /**
108          * Seeks to given position
109          *
110          * @param       $seekPosition   Seek position in file
111          * @return      $status                 Status of this operation
112          */
113         public function seek ($seekPosition) {
114                 // Call block instance
115                 return $this->getBlockInstance()->seek($seekPosition);
116         }
117
118         /**
119          * Size of file stack
120          *
121          * @return      $size   Size (in bytes) of file
122          */
123         public function size () {
124                 // Call the block object
125                 $size = $this->getBlockInstance()->size();
126
127                 // Return result
128                 return $size;
129         }
130
131         /**
132          * Reads given amount of bytes from file.
133          *
134          * @param       $bytes  Amount of bytes to read
135          * @return      $data   Data read from file
136          */
137         public function read ($bytes = NULL) {
138                 // Call block instance
139                 return $this->getBlockInstance()->read($bytes);
140         }
141
142         /**
143          * Analyzes entries in index file. This will count all found (and valid)
144          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
145          * only gaps are found, the file is considered as "virgin" (no entries).
146          *
147          * @return      void
148          */
149         public function analyzeFile () {
150                 // Just call the block instance
151                 $this->getBlockInstance()->analyzeFile();
152         }
153
154         /**
155          * Checks whether the file header is initialized
156          *
157          * @return      $isInitialized  Whether the file header is initialized
158          */
159         public function isFileHeaderInitialized () {
160                 // Just call the block instance
161                 return $this->getBlockInstance()->isFileHeaderInitialized();
162         }
163
164         /**
165          * Creates the assigned file
166          *
167          * @return      void
168          */
169         public function createFileHeader () {
170                 // Just call the block instance
171                 $this->getBlockInstance()->createFileHeader();
172         }
173
174         /**
175          * Pre-allocates file (if enabled) with some space for later faster write access.
176          *
177          * @param       $type   Type of the file
178          * @return      void
179          */
180         public function preAllocateFile ($type) {
181                 // Just call the block instance
182                 $this->getBlockInstance()->preAllocateFile($type);
183         }
184
185         /**
186          * Initializes counter for valid entries, arrays for damaged entries and
187          * an array for gap seek positions. If you call this method on your own,
188          * please re-analyze the file structure. So you are better to call
189          * analyzeFile() instead of this method.
190          *
191          * @return      void
192          */
193         public function initCountersGapsArray () {
194                 // Call block instance
195                 $this->getBlockInstance()->initCountersGapsArray();
196         }
197
198         /**
199          * Getter for header size
200          *
201          * @return      $totalEntries   Size of file header
202          */
203         public final function getHeaderSize () {
204                 // Call block instance
205                 return $this->getBlockInstance()->getHeaderSize();
206         }
207
208         /**
209          * Setter for header size
210          *
211          * @param       $headerSize             Size of file header
212          * @return      void
213          */
214         public final function setHeaderSize ($headerSize) {
215                 // Call block instance
216                 $this->getBlockInstance()->setHeaderSize($headerSize);
217         }
218
219         /**
220          * Getter for header array
221          *
222          * @return      $totalEntries   Size of file header
223          */
224         public final function getHeader () {
225                 // Call block instance
226                 return $this->getBlockInstance()->getHeader();
227         }
228
229         /**
230          * Setter for header
231          *
232          * @param       $header         Array for a file header
233          * @return      void
234          */
235         public final function setHeader (array $header) {
236                 // Call block instance
237                 $this->getBlockInstance()->setHeader($header);
238         }
239
240         /**
241          * Updates seekPosition attribute from file to avoid to much access on file.
242          *
243          * @return      void
244          */
245         public function updateSeekPosition () {
246                 // Call block instance
247                 $this->getBlockInstance()->updateSeekPosition();
248         }
249
250         /**
251          * Getter for total entries
252          *
253          * @return      $totalEntries   Total entries in this file
254          */
255         public final function getCounter () {
256                 // Call block instance
257                 return $this->getBlockInstance()->getCounter();
258         }
259
260         /**
261          * "Getter" for file size
262          *
263          * @return      $fileSize       Size of currently loaded file
264          */
265         public function getFileSize () {
266                 // Call block instance
267                 return $this->getBlockInstance()->getFileSize();
268         }
269
270         /**
271          * Writes data at given position
272          *
273          * @param       $seekPosition   Seek position
274          * @param       $data                   Data to be written
275          * @param       $flushHeader    Whether to flush the header (default: flush)
276          * @return      void
277          */
278         public function writeData ($seekPosition, $data, $flushHeader = TRUE) {
279                 // Call block instance
280                 $this->getBlockInstance()->writeData($seekPosition, $data, $flushHeader);
281         }
282
283         /**
284          * Getter for seek position
285          *
286          * @return      $seekPosition   Current seek position (stored here in object)
287          */
288         public function getSeekPosition () {
289                 // Call block instance
290                 return $this->getBlockInstance()->getSeekPosition();
291         }
292
293         /**
294          * Writes given value to the file and returns a hash and gap position for it
295          *
296          * @param       $groupId        Group identifier
297          * @param       $value          Value to be added to the stack
298          * @return      $data           Hash and gap position
299          */
300         public function writeValueToFile ($groupId, $value) {
301                 // Call block instance
302                 return $this->getBlockInstance()->writeValueToFile($groupId, $value);
303         }
304
305         /**
306          * Writes given raw data to the file and returns a gap position and length
307          *
308          * @param       $groupId        Group identifier
309          * @param       $hash           Hash from encoded value
310          * @param       $encoded        Encoded value to be written to the file
311          * @return      $data           Gap position and length of the raw data
312          */
313         public function writeDataToFreeGap ($groupId, $hash, $encoded) {
314                 // Call block instance
315                 return $this->getBlockInstance()->writeDataToFreeGap($groupId, $hash, $encoded);
316         }
317
318         /**
319          * Searches for next suitable gap the given length of data can fit in
320          * including padding bytes.
321          *
322          * @param       $length                 Length of raw data
323          * @return      $seekPosition   Found next gap's seek position
324          */
325         public function searchNextGap ($length) {
326                 // Call block instance
327                 print $this->getBlockInstance()->__toString() . PHP_EOL;
328                 return $this->getBlockInstance()->searchNextGap($length);
329         }
330
331 }