]> 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 - 2020 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          * Seeks to given position
34          *
35          * @param       $seekPosition   Seek position in file
36          * @return      $status                 Status of this operation
37          */
38         function seek ($seekPosition);
39
40         /**
41          * Size of file stack
42          *
43          * @return      $size   Size (in bytes) of file
44          */
45         function size ();
46
47         /**
48          * Reads given amount of bytes from file.
49          *
50          * @param       $bytes  Amount of bytes to read
51          * @return      $data   Data read from file
52          */
53         function read ($bytes);
54
55         /**
56          * Analyzes entries in index file. This will count all found (and valid)
57          * entries, mark invalid as damaged and count gaps ("fragmentation"). If
58          * only gaps are found, the file is considered as "virgin" (no entries).
59          *
60          * @return      void
61          */
62         function analyzeFile ();
63
64         /**
65          * Checks whether the file header is initialized
66          *
67          * @return      $isInitialized  Whether the file header is initialized
68          */
69         function isFileHeaderInitialized ();
70
71         /**
72          * Creates the assigned file
73          *
74          * @return      void
75          */
76         function createFileHeader ();
77
78         /**
79          * Pre-allocates file (if enabled) with some space for later faster write access.
80          *
81          * @param       $type   Type of the file
82          * @return      void
83          */
84         function preAllocateFile ($type);
85
86         /**
87          * Initializes counter for valid entries, arrays for damaged entries and
88          * an array for gap seek positions. If you call this method on your own,
89          * please re-analyze the file structure. So you are better to call
90          * analyzeFile() instead of this method.
91          *
92          * @return      void
93          */
94         function initCountersGapsArray ();
95
96         /**
97          * Getter for header size
98          *
99          * @return      $totalEntries   Size of file header
100          */
101         function getHeaderSize ();
102
103         /**
104          * Setter for header size
105          *
106          * @param       $headerSize             Size of file header
107          * @return      void
108          */
109         function setHeaderSize ($headerSize);
110
111         /**
112          * Getter for header array
113          *
114          * @return      $totalEntries   Size of file header
115          */
116         function getHeader ();
117
118         /**
119          * Setter for header
120          *
121          * @param       $header         Array for a file header
122          * @return      void
123          */
124         function setHeader (array $header);
125
126         /**
127          * Updates seekPosition attribute from file to avoid to much access on file.
128          *
129          * @return      void
130          */
131         function updateSeekPosition ();
132
133         /**
134          * Getter for total entries
135          *
136          * @return      $totalEntries   Total entries in this file
137          */
138         function getCounter ();
139
140         /**
141          * "Getter" for file size
142          *
143          * @return      $fileSize       Size of currently loaded file
144          */
145         function getFileSize ();
146
147         /**
148          * Writes data at given position
149          *
150          * @param       $seekPosition   Seek position
151          * @param       $data                   Data to be written
152          * @param       $flushHeader    Whether to flush the header (default: flush)
153          * @return      void
154          */
155         function writeData ($seekPosition, $data, $flushHeader = true);
156
157         /**
158          * Getter for seek position
159          *
160          * @return      $seekPosition   Current seek position (stored here in object)
161          */
162         function getSeekPosition ();
163
164         /**
165          * Writes given value to the file and returns a hash and gap position for it
166          *
167          * @param       $groupId        Group identifier
168          * @param       $value          Value to be added to the stack
169          * @return      $data           Hash and gap position
170          */
171         function writeValueToFile ($groupId, $value);
172
173         /**
174          * Writes given raw data to the file and returns a gap position and length
175          *
176          * @param       $groupId        Group identifier
177          * @param       $hash           Hash from encoded value
178          * @param       $encoded        Encoded value to be written to the file
179          * @return      $data           Gap position and length of the raw data
180          */
181         function writeDataToFreeGap ($groupId, $hash, $encoded);
182
183         /**
184          * Searches for next suitable gap the given length of data can fit in
185          * including padding bytes.
186          *
187          * @param       $length                 Length of raw data
188          * @return      $seekPosition   Found next gap's seek position
189          */
190         function searchNextGap ($length);
191
192 }