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