]> git.mxchange.org Git - core.git/blob - framework/main/interfaces/iterator/file/class_SeekableWritableFileIterator.php
Continued:
[core.git] / framework / main / interfaces / iterator / file / class_SeekableWritableFileIterator.php
1 <?php
2 // Own namespace
3 namespace Org\Mxchange\CoreFramework\Iterator\Filesystem;
4
5 // Import SPL stuff
6 use \SeekableIterator;
7
8 /**
9  * An interface for seekable iterators which also allow to write to the file
10  * in different ways.
11  *
12  * @author              Roland Haeder <webmaster@ship-simu.org>
13  * @version             0.0.0
14  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2021 Core Developer Team
15  * @license             GNU GPL 3.0 or any newer version
16  * @link                http://www.ship-simu.org
17  *
18  * This program is free software: you can redistribute it and/or modify
19  * it under the terms of the GNU General Public License as published by
20  * the Free Software Foundation, either version 3 of the License, or
21  * (at your option) any later version.
22  *
23  * This program is distributed in the hope that it will be useful,
24  * but WITHOUT ANY WARRANTY; without even the implied warranty of
25  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
26  * GNU General Public License for more details.
27  *
28  * You should have received a copy of the GNU General Public License
29  * along with this program. If not, see <http://www.gnu.org/licenses/>.
30  */
31 interface SeekableWritableFileIterator extends SeekableIterator {
32         /**
33          * Size of file stack
34          *
35          * @return      $size   Size (in bytes) of file
36          */
37         function size ();
38
39         /**
40          * Reads given amount of bytes from file.
41          *
42          * @param       $bytes  Amount of bytes to read
43          * @return      $data   Data read from file
44          */
45         function read (int $bytes = 0);
46
47         /**
48          * Analyzes entries in index file. This will count all found (and valid)
49          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
50          * only gaps are found, the file is considered as "virgin" (no entries).
51          *
52          * @return      void
53          */
54         function analyzeFileStructure ();
55
56         /**
57          * Checks whether the file header is initialized
58          *
59          * @return      $isInitialized  Whether the file header is initialized
60          */
61         function isFileHeaderInitialized ();
62
63         /**
64          * Creates the assigned file
65          *
66          * @return      void
67          */
68         function createFileHeader ();
69
70         /**
71          * Pre-allocates file (if enabled) with some space for later faster write access.
72          *
73          * @param       $type   Type of the file
74          * @return      void
75          */
76         function preAllocateFile (string $type);
77
78         /**
79          * Initializes counter for valid entries, arrays for damaged entries and
80          * an array for gap seek positions. If you call this method on your own,
81          * please re-analyze the file structure. So you are better to call
82          * analyzeFileStructure() instead of this method.
83          *
84          * @return      void
85          */
86         function initCountersGapsArray ();
87
88         /**
89          * Getter for header size
90          *
91          * @return      $totalEntries   Size of file header
92          */
93         function getHeaderSize ();
94
95         /**
96          * Setter for header size
97          *
98          * @param       $headerSize             Size of file header
99          * @return      void
100          */
101         function setHeaderSize (int $headerSize);
102
103         /**
104          * Getter for header array
105          *
106          * @return      $totalEntries   Size of file header
107          */
108         function getHeader ();
109
110         /**
111          * Setter for header
112          *
113          * @param       $header         Array for a file header
114          * @return      void
115          */
116         function setHeader (array $header);
117
118         /**
119          * Updates seekPosition attribute from file to avoid to much access on file.
120          *
121          * @return      void
122          */
123         function updateSeekPosition ();
124
125         /**
126          * Getter for total entries
127          *
128          * @return      $totalEntries   Total entries in this file
129          */
130         function getCounter ();
131
132         /**
133          * "Getter" for file size
134          *
135          * @return      $fileSize       Size of currently loaded file
136          */
137         function getFileSize ();
138
139         /**
140          * Getter for seek position
141          *
142          * @return      $seekPosition   Current seek position (stored here in object)
143          */
144         function getSeekPosition ();
145
146         /**
147          * Searches for next suitable gap the given length of data can fit in
148          * including padding bytes.
149          *
150          * @param       $length                 Length of raw data
151          * @return      $seekPosition   Found next gap's seek position
152          */
153         function searchNextGap (int $length);
154
155         /**
156          * Checks whether the abstracted file only contains gaps by counting all
157          * gaps' bytes together and compare it to total length.
158          *
159          * @return      $isGapsOnly             Whether the abstracted file only contains gaps
160          */
161         function isFileGapsOnly();
162
163         /**
164          * Writes data at given position
165          *
166          * @param       $seekPosition   Seek position
167          * @param       $data                   Data to be written
168          * @param       $flushHeader    Whether to flush the header (default: flush)
169          * @return      void
170          */
171         function writeData (int $seekPosition, string $data, bool $flushHeader = true);
172
173         /**
174          * Writes at given position by seeking to it.
175          *
176          * @param       $seekPosition   Seek position in file
177          * @param       $data                   Data to be written
178          * @return      mixed                   Number of writes bytes or false on error
179          */
180         function writeAtPosition (int $seedPosition, string $data);
181
182         /**
183          * Writes given value to the file and returns a hash and gap position for it
184          *
185          * @param       $groupId        Group identifier
186          * @param       $value          Value to be added to the stack
187          * @return      $data           Hash and gap position
188          */
189         function writeValueToFile (string $groupId, $value);
190
191         /**
192          * Writes given raw data to the file and returns a gap position and length
193          *
194          * @param       $groupId        Group identifier
195          * @param       $hash           Hash from encoded value
196          * @param       $encoded        Encoded value to be written to the file
197          * @return      $data           Gap position and length of the raw data
198          */
199         function writeDataToFreeGap (string $groupId, string $hash, string $encoded);
200
201 }